opencode-agent-skill 14.2.0-beta.1 → 15.0.0

package/global-config/skills/database-engineering/references/workflow.md

@@ -13,3 +13,18 @@ Define the invariant and the smallest atomic boundary. Consider retries, unique
 
 ## Verification
 Validate migration up/down strategy when supported, run affected data tests, and inspect generated SQL/schema diff. For risky changes use representative existing data or a dry run. Confirm old/new application compatibility when rollout can overlap.
+
+
+## Fixture/demo cleanup safety
+
+Treat cleanup of test/demo records as a data migration, not a UI concern.
+
+- refuse production targets and never silently fall back from a test database to a development database;
+- dry-run before deletion and report the exact candidate IDs/keys plus pre-cleanup counts;
+- match deterministic markers or audited source provenance, never a broad substring that could include legitimate records;
+- preserve canonical seed/demo records and real user history;
+- delete in dependency-safe FK order and use a transaction/rollback boundary when the stack supports it;
+- report post-cleanup counts and run the cleanup a second time to prove idempotency;
+- verify public/API data after cleanup. Frontend filtering is not cleanup evidence.
+
+Only claim `DB_CLEAN_PASS` when fresh data-layer evidence proves the cleanup candidates, counts, canonical preservation, public-data result, and zero-change second pass.

package/global-config/skills/engineering-orchestrator/references/long-horizon.md

@@ -13,6 +13,11 @@ When the user explicitly chooses the long-horizon workflow (for example with `/u
   STATE.json
   EVIDENCE.json
   EVENTS.jsonl
+  EXECUTION_CONTRACT.json
+  FINAL_VERDICTS.json
+  phases/
+    MANIFEST.json
+    phase-XX-<slug>.json
   tasks/
   reports/
 ```
@@ -21,11 +26,15 @@ The directory is git-ignored execution state, not hidden reasoning. Store requir
 
 ## Machine-enforced gates
 
-The V6 engine enforces three boundaries:
+The runtime enforces seven boundaries:
 
-1. **Plan gate** — `work plan` leaves the item in `awaiting-plan-approval`. Long/high-risk plans require a structured `plan-verification` receipt bound to the current plan hash before `work approve-plan` succeeds.
-2. **Concurrent state gate** — all mutable `STATE.json` and `EVIDENCE.json` operations use a per-work-item lock plus atomic file replacement, preventing safe-wave executors from losing each other's state.
-3. **Integration gate** — long/high-risk PASS requires a structured `integration-verification` receipt bound to the current workspace fingerprint. Finalization rejects any later workspace change.
+1. **Inherited-work gate** — snapshot source-facing dirty paths before planning. UES children may not discard them with restore/checkout/stash/clean/reset, and planned writers must declare every touched file.
+2. **Local-env gate** — local `.env*` runtime inputs are no-write by default; only explicit user authorization permits local env mutation. Repository templates remain writable.
+3. **Plan gate** — `work plan` leaves the item in `awaiting-plan-approval`. Long/high-risk plans require a structured `plan-verification` receipt bound to the current plan hash before `work approve-plan` succeeds.
+4. **Phase gate** — explicit execution phases become deterministic previous-phase barriers. Constraint-only phases stay global invariants.
+5. **Concurrent state gate** — all mutable `STATE.json` and `EVIDENCE.json` operations use a per-work-item lock plus atomic file replacement, preventing safe-wave executors from losing each other's state.
+6. **Integration gate** — long/high-risk source completion requires a structured `integration-verification` receipt bound to the current workspace fingerprint. Finalization rejects any later workspace change.
+7. **Verdict matrix gate** — source, runtime, database cleanup and real-device proof remain independent. Missing required evidence is reported as not verified rather than promoted to PASS.
 
 ## Pipeline
 
@@ -33,18 +42,19 @@ The V6 engine enforces three boundaries:
 2. Write observable acceptance criteria into `SPEC.md`.
 3. Initialize state with `ocskill work init`.
 4. Create `PLAN.json` following the plan schema and import it with `ocskill work plan`.
-5. Run `ues-plan-checker`. If it returns PASS, create `work gate-receipt <slug> plan` and persist approval with `work approve-plan --receipt-file ...`.
-6. Use `ocskill task-graph` to compute dependency-safe waves.
-7. For each ready task:
+5. If the user supplied explicit `PHASE N` sections, preserve every execution phase in the plan and let UES add phase barriers; constraint-only phases remain invariants.
+6. Run `ues-plan-checker`. If it returns PASS, create `work gate-receipt <slug> plan` and persist approval with `work approve-plan --receipt-file ...`.
+7. Persist the execution contract/phase artifacts and use `ocskill task-graph` to compute dependency-safe waves.
+8. For each ready task:
    - on OpenCode V2, if two or more approved tasks are independent, prefer `ues.dispatch_parallel` so one shared model can execute them concurrently with isolated worktrees, leases, independent verifier sessions and serialized integration;
    - otherwise prefer `ues.dispatch_task`, which performs `work start`, creates a fresh `ues-executor` session, selects the configured attempt-based model tier, prompts it with a bounded context pack and waits for completion;
    - inspect the child diff and verification;
    - record at least one successful `work verify-command` receipt for long/high-risk work;
    - persist `work complete --evidence ...` or `work fail --reason ...`.
-8. On failure, re-diagnose rather than stacking patches. A later `ues.dispatch_task` attempt can escalate from standard to heavy when configured.
-9. After all tasks complete, run `ues-integration-verifier`.
-10. Persist the verifier's actual result with a structured integration receipt plus `ocskill work verify-integration --receipt-file ...`.
-11. Only a recorded PASS with an unchanged workspace can be finalized.
+9. On failure, re-diagnose rather than stacking patches. A later `ues.dispatch_task` attempt can escalate from standard to heavy when configured.
+10. After all tasks complete, run `ues-integration-verifier`.
+11. Persist the verifier's actual result with a structured integration receipt plus `ocskill work verify-integration --receipt-file ...`.
+12. Emit the independent final verdict matrix and persist `FINAL_VERDICTS.json`. Only a recorded PASS with an unchanged workspace can be finalized.
 
 ## Parallelism
 

package/lib/activity-deadline.mjs

@@ -0,0 +1,70 @@
+function finite(value, fallback, min = 0, max = Number.MAX_SAFE_INTEGER) {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(parsed)))
+}
+
+export function createAdaptiveDeadline(options = {}, startedAt = Date.now()) {
+  const initialMs = finite(options.hardTimeoutMs, 60_000, 1_000)
+  const absoluteMs = Math.max(
+    initialMs,
+    finite(options.absoluteHardTimeoutMs, initialMs, initialMs),
+  )
+  const extensionMs = finite(options.activityExtensionMs, 0, 0, absoluteMs)
+  const activityWindowMs = finite(
+    options.activityWindowMs,
+    Math.max(5_000, Math.min(extensionMs || initialMs, 30_000)),
+    1_000,
+    absoluteMs,
+  )
+
+  let deadlineAt = startedAt + initialMs
+  const absoluteAt = startedAt + absoluteMs
+  let extensions = 0
+
+  function maybeExtend(now = Date.now(), lastActivityAt = 0) {
+    if (extensionMs <= 0 || deadlineAt >= absoluteAt) {
+      return { extended: false, deadlineAt, absoluteAt, extensions }
+    }
+    if (now - Number(lastActivityAt || 0) > activityWindowMs) {
+      return { extended: false, deadlineAt, absoluteAt, extensions }
+    }
+    const next = Math.min(absoluteAt, Math.max(deadlineAt, now + extensionMs))
+    if (next <= deadlineAt) {
+      return { extended: false, deadlineAt, absoluteAt, extensions }
+    }
+    deadlineAt = next
+    extensions += 1
+    return { extended: true, deadlineAt, absoluteAt, extensions }
+  }
+
+  function shouldAbort(now = Date.now(), lastActivityAt = 0) {
+    if (now < deadlineAt) {
+      return { abort: false, deadlineAt, absoluteAt, extensions }
+    }
+    const extension = maybeExtend(now, lastActivityAt)
+    if (extension.extended) {
+      return { abort: false, ...extension }
+    }
+    return {
+      abort: true,
+      reason: now >= absoluteAt ? "absolute-hard-timeout" : "hard-timeout",
+      deadlineAt,
+      absoluteAt,
+      extensions,
+    }
+  }
+
+  return {
+    startedAt,
+    initialMs,
+    absoluteMs,
+    extensionMs,
+    activityWindowMs,
+    get deadlineAt() { return deadlineAt },
+    get absoluteAt() { return absoluteAt },
+    get extensions() { return extensions },
+    maybeExtend,
+    shouldAbort,
+  }
+}

package/lib/adaptive-context-budget.mjs

@@ -59,20 +59,35 @@ export function adaptiveContextBudget(taskPolicy = {}, role = "executor", attemp
   const profile = String(taskPolicy.executionProfile || taskPolicy.profile?.name || "standard")
   const highRisk = taskPolicy.risk === "high" || taskPolicy.risk === "critical"
 
-  // High-risk work keeps the original evidence budget. Turbo mode must not trade
-  // away security/payment/schema evidence for latency.
-  if (highRisk || options.disabled === true) {
+  if (options.disabled === true) {
     return {
       schemaVersion: 1,
       budget: base,
       baseBudget: base,
       adaptive: false,
-      reason: highRisk ? "high-risk-preserves-base-budget" : "disabled",
+      reason: "disabled",
     }
   }
 
   const table = ROLE_TARGETS[profile] || ROLE_TARGETS.standard
   const target = clamp(table?.[role], base, 4_000, base)
+  const plannerRole = role === "architect" || role === "plan-checker"
+
+  // High-risk execution/verification keeps the full evidence ceiling. Read-only
+  // planning roles are allowed a bounded context because they can use targeted
+  // repository tools and are independently plan-gated before any write begins.
+  if (highRisk && !plannerRole) {
+    return {
+      schemaVersion: 1,
+      budget: base,
+      baseBudget: base,
+      adaptive: false,
+      reason: "high-risk-execution-preserves-base-budget",
+      profile,
+      role,
+      attempt: Math.max(1, Math.trunc(Number(attempt || 1))),
+    }
+  }
   const normalizedAttempt = Math.max(1, Math.trunc(Number(attempt || 1)))
 
   // Failed attempts expand deterministically back toward the policy ceiling.
@@ -92,6 +107,11 @@ export function adaptiveContextBudget(taskPolicy = {}, role = "executor", attemp
     profile,
     role,
     attempt: normalizedAttempt,
-    reason: budget < base ? "role-bounded-expand-on-failure" : "policy-ceiling",
+    reason:
+      highRisk && plannerRole
+        ? "high-risk-planner-role-bounded"
+        : budget < base
+          ? "role-bounded-expand-on-failure"
+          : "policy-ceiling",
   }
 }

package/lib/affected-tests.mjs

@@ -6,7 +6,7 @@ import { runtimeWorkspaceFingerprint } from "./workspace-fingerprint.mjs"
 
 const TEST_RE = /(?:^|[/.\\])(?:__tests__|tests?|spec)(?:[/.\\]|$)|\.(?:test|spec|e2e-spec)\.[cm]?[jt]sx?$/i
 const SOURCE_EXT = new Set([".js",".jsx",".mjs",".cjs",".ts",".tsx",".py",".java",".kt",".kts",".cs",".go",".rs",".dart",".swift"])
-const SKIP = new Set([".git","node_modules",".next","dist","build","coverage",".venv","venv","target","Pods","DerivedData",".gradle",".ues-cache",".ues-work",".ues-sandboxes",".ues-traces",".ues-learning",".ues-dashboard",".ues-memory",".ues-evals"])
+const SKIP = new Set([".git","node_modules",".next","dist","build","coverage",".venv","venv","target","Pods","DerivedData",".gradle",".ues-cache",".ues-work",".ues-sandboxes",".ues-traces",".ues-learning",".ues-dashboard",".ues-memory",".ues-evals",".ues-services"])
 const AFFECTED_TEST_CACHE = new Map()
 const AFFECTED_TEST_INFLIGHT = new Map()
 

package/lib/capability-fabric.mjs

@@ -106,6 +106,46 @@ export function defaultCapabilityRegistry(root = process.cwd()) {
       "code.search": [
         { id: "ues-semantic-index", kind: "builtin", priority: 100, quality: 0.9, costClass: "low", latencyClass: "fast" },
       ],
+      "code.edit.anchored": [
+        { id: "ues-hashline", kind: "builtin", priority: 120, quality: 0.98, costClass: "low", latencyClass: "fast", metadata: { failClosed: true, staleAnchorReject: true } },
+      ],
+      "code.structure": [
+        { id: "ast-grep", kind: "command", command: "ast-grep", priority: 120, quality: 0.96, costClass: "low", latencyClass: "fast" },
+        { id: "sg", kind: "command", command: "sg", priority: 115, quality: 0.96, costClass: "low", latencyClass: "fast" },
+        { id: "ues-semantic-index", kind: "builtin", priority: 80, quality: 0.8, costClass: "low", latencyClass: "fast" },
+      ],
+      "code.diagnostics": [
+        { id: "typescript-language-server", kind: "command", command: "typescript-language-server", priority: 110, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "pyright-langserver", kind: "command", command: "pyright-langserver", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "pylsp", kind: "command", command: "pylsp", priority: 95, quality: 0.85, costClass: "low", latencyClass: "medium" },
+        { id: "gopls", kind: "command", command: "gopls", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "rust-analyzer", kind: "command", command: "rust-analyzer", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "clangd", kind: "command", command: "clangd", priority: 100, quality: 0.9, costClass: "low", latencyClass: "medium" },
+      ],
+      "document.ingestion": [
+        { id: "ues-builtin-text", kind: "builtin", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast", metadata: { formats: ["text", "markdown", "json", "csv", "html", "xml"] } },
+        { id: "markitdown-cli", kind: "command", command: "markitdown", priority: 95, quality: 0.95, costClass: "low", latencyClass: "medium", metadata: { optional: true, formats: ["pdf", "docx", "pptx", "xlsx", "epub", "zip"] } },
+      ],
+      "context.reversible": [
+        { id: "ues-evidence-context", kind: "builtin", priority: 120, quality: 0.98, costClass: "low", latencyClass: "fast", metadata: { reversible: true, searchable: true, levels: ["T1", "T2", "T3", "raw"] } },
+      ],
+      "runtime.service": [
+        {
+          id: "ues-managed-service",
+          kind: "builtin",
+          priority: 125,
+          quality: 0.98,
+          costClass: "low",
+          latencyClass: "fast",
+          metadata: {
+            shellFree: true,
+            readiness: ["port", "log", "process"],
+            actions: ["start", "wait-ready", "status", "logs", "stop", "restart"],
+            boundedLifetime: true,
+            evidenceLogs: true,
+          },
+        },
+      ],
       memory: [
         { id: "ues-memory", kind: "builtin", priority: 100, quality: 0.9, costClass: "low", latencyClass: "fast" },
       ],

package/lib/code-intelligence/edit-anchor.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto"
+
+const DEFAULT_HASH_CHARS = 8
+
+function normalizeNewlines(value) {
+  return String(value ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n")
+}
+
+function hashText(value, chars = DEFAULT_HASH_CHARS) {
+  return createHash("sha256").update(String(value ?? "")).digest("hex").slice(0, Math.max(6, Math.min(16, Number(chars || DEFAULT_HASH_CHARS))))
+}
+
+export function lineAnchor(lineNumber, lineText, options = {}) {
+  const line = Math.max(1, Math.trunc(Number(lineNumber || 1)))
+  return `L${line}:${hashText(lineText, options.hashChars)}`
+}
+
+export function parseLineAnchor(anchor) {
+  const match = String(anchor || "").trim().match(/^L([1-9]\d*):([a-f0-9]{6,16})$/i)
+  if (!match) return null
+  return { line: Number(match[1]), hash: match[2].toLowerCase() }
+}
+
+export function anchoredLines(source, options = {}) {
+  const text = normalizeNewlines(source)
+  const lines = text.split("\n")
+  const startLine = Math.max(1, Math.trunc(Number(options.startLine || 1)))
+  const requestedEnd = options.endLine == null ? lines.length : Math.trunc(Number(options.endLine))
+  const endLine = Math.max(startLine, Math.min(lines.length, requestedEnd || lines.length))
+  const rows = []
+  for (let line = startLine; line <= endLine; line += 1) {
+    const value = lines[line - 1] ?? ""
+    rows.push({ line, anchor: lineAnchor(line, value, options), text: value })
+  }
+  return {
+    schemaVersion: 1,
+    startLine,
+    endLine,
+    lineCount: lines.length,
+    sourceHash: hashText(text, 16),
+    rows,
+    text: rows.map((row) => `${row.anchor}|${row.text}`).join("\n"),
+  }
+}
+
+function validateAnchor(lines, rawAnchor, label, options = {}) {
+  const parsed = parseLineAnchor(rawAnchor)
+  if (!parsed) throw new Error(`${label} must use L<line>:<hash> format`)
+  if (parsed.line > lines.length) throw new Error(`${label} points beyond end of file`)
+  const actual = lineAnchor(parsed.line, lines[parsed.line - 1] ?? "", options)
+  if (actual.toLowerCase() !== String(rawAnchor).toLowerCase()) {
+    const error = new Error(`${label} is stale or ambiguous; re-read anchored source before editing`)
+    error.code = "UES_STALE_ANCHOR"
+    error.expected = actual
+    error.received = String(rawAnchor)
+    throw error
+  }
+  return parsed
+}
+
+export function applyAnchoredEdits(source, edits = [], options = {}) {
+  const text = normalizeNewlines(source)
+  const lines = text.split("\n")
+  if (!Array.isArray(edits) || edits.length === 0) throw new Error("at least one anchored edit is required")
+  const maxEdits = Math.max(1, Math.min(200, Number(options.maxEdits || 50)))
+  if (edits.length > maxEdits) throw new Error(`too many anchored edits; maximum is ${maxEdits}`)
+
+  const prepared = edits.map((edit, index) => {
+    const start = validateAnchor(lines, edit?.anchor || edit?.startAnchor, `edit[${index}].anchor`, options)
+    const end = edit?.endAnchor
+      ? validateAnchor(lines, edit.endAnchor, `edit[${index}].endAnchor`, options)
+      : start
+    if (end.line < start.line) throw new Error(`edit[${index}] endAnchor precedes anchor`)
+    return {
+      index,
+      startLine: start.line,
+      endLine: end.line,
+      replacement: normalizeNewlines(edit?.replacement ?? ""),
+    }
+  })
+
+  prepared.sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine)
+  for (let index = 1; index < prepared.length; index += 1) {
+    if (prepared[index].startLine <= prepared[index - 1].endLine) {
+      throw new Error(`anchored edits overlap at edit[${prepared[index].index}]`)
+    }
+  }
+
+  const next = [...lines]
+  for (const edit of [...prepared].sort((a, b) => b.startLine - a.startLine)) {
+    const replacementLines = edit.replacement.split("\n")
+    next.splice(edit.startLine - 1, edit.endLine - edit.startLine + 1, ...replacementLines)
+  }
+  const output = next.join("\n")
+  return {
+    schemaVersion: 1,
+    sourceHash: hashText(text, 16),
+    outputHash: hashText(output, 16),
+    applied: prepared.length,
+    text: output,
+  }
+}

package/lib/code-intelligence/index.mjs

@@ -0,0 +1,95 @@
+import { lstat, readFile, realpath, rename, rm, writeFile } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import { querySemanticIndex } from "../semantic-index.mjs"
+import { anchoredLines, applyAnchoredEdits } from "./edit-anchor.mjs"
+import { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"
+
+const AST_COMMANDS = ["ast-grep", "sg"]
+const commandCache = new Map()
+const COMMAND_TTL_MS = 60_000
+
+function commandExists(command) {
+  const now = Date.now()
+  const cached = commandCache.get(command)
+  if (cached && now - cached.at < COMMAND_TTL_MS) return cached.available
+  const finder = process.platform === "win32" ? "where" : "which"
+  const available = spawnSync(finder, [command], { stdio: "ignore", windowsHide: true }).status === 0
+  commandCache.set(command, { available, at: now })
+  return available
+}
+
+function inside(root, target) { return target === root || target.startsWith(root + path.sep) }
+
+async function safeFile(root, relative) {
+  const base = await realpath(path.resolve(root)).catch(() => path.resolve(root))
+  const requested = path.resolve(base, String(relative || ""))
+  if (!inside(base, requested)) throw new Error("code path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("code path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("code symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+export function probeCodeIntelligence(file = "") {
+  const astProvider = AST_COMMANDS.find(commandExists) || null
+  return {
+    schemaVersion: 1,
+    anchoredEditing: true,
+    semanticIndex: true,
+    astProvider,
+    lsp: lspProviderStatus(file),
+  }
+}
+
+export async function readAnchoredCode(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("code file exceeds anchored-read limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  return { file: path.relative(target.base, target.file).replaceAll("\\", "/"), ...anchoredLines(source, options) }
+}
+
+export async function applyAnchoredFileEdits(root, relative, edits, options = {}) {
+  const target = await safeFile(root, relative)
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("code file exceeds anchored-edit limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  const result = applyAnchoredEdits(source, edits, options)
+  const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
+  if (options.dryRun === true) return { ...result, file: relativeFile, dryRun: true }
+  const temp = target.file + "." + process.pid + "." + Date.now() + ".ues.tmp"
+  await writeFile(temp, result.text, "utf8")
+  try { await rename(temp, target.file) } catch (error) { await rm(temp, { force: true }).catch(() => {}); throw error }
+  return { ...result, file: relativeFile, dryRun: false }
+}
+
+function runAstGrep(root, pattern, language, limit) {
+  const command = AST_COMMANDS.find(commandExists) || null
+  if (!command || !String(pattern || "").trim()) return { provider: null, results: [], error: null }
+  const args = ["run", "--pattern", String(pattern), "--json=stream"]
+  if (language) args.push("--lang", String(language))
+  args.push(".")
+  const result = spawnSync(command, args, { cwd: path.resolve(root), encoding: "utf8", timeout: 20_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true })
+  if (result.status !== 0) return { provider: command, results: [], error: String(result.stderr || ("ast-grep exit " + result.status)).trim().slice(0, 1000) }
+  const rows = String(result.stdout || "").split(/\r?\n/).filter(Boolean).slice(0, limit).map((line) => {
+    try { return JSON.parse(line) } catch { return { raw: line } }
+  })
+  return { provider: command, results: rows, error: null }
+}
+
+export async function searchCodeIntelligence(root, query, options = {}) {
+  const maxResults = Math.max(1, Math.min(50, Number(options.maxResults || 12)))
+  const semantic = await querySemanticIndex(root, query, { maxFiles: options.maxFiles || 6000, limit: maxResults })
+  const structural = options.structuralPattern ? runAstGrep(root, options.structuralPattern, options.language, maxResults) : { provider: null, results: [], error: null }
+  return {
+    schemaVersion: 1,
+    query: String(query || ""),
+    providers: probeCodeIntelligence(options.file || ""),
+    semantic: { ...semantic, results: (semantic.results || []).slice(0, maxResults) },
+    structural,
+  }
+}
+
+export { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"

package/lib/code-intelligence/lsp-provider.mjs

@@ -0,0 +1,189 @@
+import { spawn, spawnSync } from "node:child_process"
+import { lstat, readFile, realpath } from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+const PROVIDERS = [
+  { id: "typescript-language-server", extensions: new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]), commands: [["typescript-language-server", ["--stdio"]]], languageId: (ext) => [".ts", ".tsx"].includes(ext) ? "typescript" : "javascript" },
+  { id: "pyright-langserver", extensions: new Set([".py"]), commands: [["pyright-langserver", ["--stdio"]], ["pylsp", []]], languageId: () => "python" },
+  { id: "gopls", extensions: new Set([".go"]), commands: [["gopls", []]], languageId: () => "go" },
+  { id: "rust-analyzer", extensions: new Set([".rs"]), commands: [["rust-analyzer", []]], languageId: () => "rust" },
+  { id: "clangd", extensions: new Set([".c", ".cc", ".cpp", ".cxx", ".h", ".hpp"]), commands: [["clangd", []]], languageId: (ext) => [".c", ".h"].includes(ext) ? "c" : "cpp" },
+]
+
+const commandCache = new Map()
+const COMMAND_TTL_MS = 60_000
+
+function commandExists(command) {
+  const now = Date.now()
+  const cached = commandCache.get(command)
+  if (cached && now - cached.at < COMMAND_TTL_MS) return cached.available
+  const finder = process.platform === "win32" ? "where" : "which"
+  const available = spawnSync(finder, [command], { stdio: "ignore", windowsHide: true }).status === 0
+  commandCache.set(command, { available, at: now })
+  return available
+}
+
+function inside(root, target) {
+  return target === root || target.startsWith(root + path.sep)
+}
+
+async function safeFile(root, relative) {
+  const base = await realpath(path.resolve(root)).catch(() => path.resolve(root))
+  const requested = path.resolve(base, String(relative || ""))
+  if (!inside(base, requested)) throw new Error("diagnostic path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("diagnostic path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("diagnostic symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+function providerFor(file) {
+  const ext = path.extname(file).toLowerCase()
+  for (const provider of PROVIDERS) {
+    if (!provider.extensions.has(ext)) continue
+    for (const [command, args] of provider.commands) {
+      if (commandExists(command)) return { ...provider, command, args, languageId: provider.languageId(ext) }
+    }
+    return { ...provider, command: null, args: [], languageId: provider.languageId(ext) }
+  }
+  return null
+}
+
+export function lspProviderStatus(file = "") {
+  const ext = path.extname(String(file || "")).toLowerCase()
+  const providers = PROVIDERS
+    .filter((provider) => !ext || provider.extensions.has(ext))
+    .map((provider) => {
+      const selected = provider.commands.find(([command]) => commandExists(command)) || null
+      return { id: provider.id, available: Boolean(selected), command: selected?.[0] || null, extensions: [...provider.extensions] }
+    })
+  return { schemaVersion: 1, extension: ext, available: providers.some((row) => row.available), providers }
+}
+
+function encodeMessage(payload) {
+  const body = Buffer.from(JSON.stringify(payload), "utf8")
+  return Buffer.concat([Buffer.from("Content-Length: " + body.length + "\r\n\r\n", "ascii"), body])
+}
+
+function sanitizeDiagnostic(value = {}) {
+  return {
+    range: value.range || null,
+    severity: Number.isFinite(Number(value.severity)) ? Number(value.severity) : null,
+    code: value.code == null ? null : String(value.code),
+    source: value.source == null ? null : String(value.source),
+    message: String(value.message || "").slice(0, 4000),
+  }
+}
+
+export async function diagnoseCode(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const provider = providerFor(target.file)
+  const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
+  if (!provider?.command) {
+    return { schemaVersion: 1, file: relativeFile, available: false, provider: provider?.id || null, diagnostics: [], reason: provider ? "lsp-command-unavailable" : "unsupported-extension" }
+  }
+
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 1024 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("diagnostic file exceeds limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  const uri = pathToFileURL(target.file).href
+  const rootUri = pathToFileURL(target.base + path.sep).href
+  const timeoutMs = Math.max(500, Math.min(10_000, Number(options.timeoutMs || 3000)))
+  const maxDiagnostics = Math.max(1, Math.min(500, Number(options.maxDiagnostics || 100)))
+
+  return await new Promise((resolve) => {
+    const child = spawn(provider.command, provider.args, { cwd: target.base, stdio: ["pipe", "pipe", "pipe"], windowsHide: true, shell: false })
+    let buffer = Buffer.alloc(0)
+    let stderr = ""
+    let settled = false
+    let initialized = false
+    let diagnostics = []
+    let timer = null
+
+    const finish = (reason, error = null) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      try {
+        if (initialized && child.stdin.writable) {
+          child.stdin.write(encodeMessage({ jsonrpc: "2.0", id: 2, method: "shutdown", params: null }))
+          child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "exit", params: null }))
+        }
+      } catch {}
+      setTimeout(() => { try { child.kill() } catch {} }, 50).unref?.()
+      resolve({
+        schemaVersion: 1,
+        file: relativeFile,
+        available: true,
+        provider: provider.id,
+        command: provider.command,
+        diagnostics: diagnostics.slice(0, maxDiagnostics),
+        reason,
+        stderr: stderr.trim().slice(0, 2000) || null,
+        error: error ? String(error instanceof Error ? error.message : error).slice(0, 1000) : null,
+      })
+    }
+
+    const handle = (message) => {
+      if (message?.id === 1 && message?.result) {
+        initialized = true
+        try {
+          child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "initialized", params: {} }))
+          child.stdin.write(encodeMessage({
+            jsonrpc: "2.0",
+            method: "textDocument/didOpen",
+            params: { textDocument: { uri, languageId: provider.languageId, version: 1, text: source } },
+          }))
+        } catch (error) {
+          finish("write-failed", error)
+        }
+        return
+      }
+      if (message?.method === "textDocument/publishDiagnostics" && message?.params?.uri === uri) {
+        diagnostics = Array.isArray(message.params.diagnostics) ? message.params.diagnostics.map(sanitizeDiagnostic).slice(0, maxDiagnostics) : []
+        finish("publishDiagnostics")
+      }
+    }
+
+    const parse = () => {
+      while (!settled) {
+        const headerEnd = buffer.indexOf("\r\n\r\n")
+        if (headerEnd < 0) return
+        const header = buffer.subarray(0, headerEnd).toString("ascii")
+        const match = header.match(/Content-Length:\s*(\d+)/i)
+        if (!match) { buffer = buffer.subarray(headerEnd + 4); continue }
+        const length = Number(match[1])
+        const bodyStart = headerEnd + 4
+        if (buffer.length < bodyStart + length) return
+        const body = buffer.subarray(bodyStart, bodyStart + length).toString("utf8")
+        buffer = buffer.subarray(bodyStart + length)
+        try { handle(JSON.parse(body)) } catch {}
+      }
+    }
+
+    child.stdout.on("data", (chunk) => { buffer = Buffer.concat([buffer, Buffer.from(chunk)]); parse() })
+    child.stderr.on("data", (chunk) => { if (stderr.length < 64 * 1024) stderr += chunk.toString() })
+    child.on("error", (error) => finish("spawn-error", error))
+    child.on("close", (code) => { if (!settled) finish("server-exit:" + (code ?? "unknown")) })
+
+    try {
+      child.stdin.write(encodeMessage({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          processId: process.pid,
+          rootUri,
+          capabilities: { textDocument: { publishDiagnostics: { relatedInformation: true } } },
+          workspaceFolders: [{ uri: rootUri, name: path.basename(target.base) || "workspace" }],
+        },
+      }))
+    } catch (error) {
+      finish("initialize-write-failed", error)
+    }
+    timer = setTimeout(() => finish("timeout"), timeoutMs)
+    timer.unref?.()
+  })
+}