devloom 1.0.0 → 1.2.0

package/scripts/loop-run.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * DevLoom Loop Runner — Single loop tick executor
+ * Usage: node scripts/loop-run.mjs [--pattern <name>] [--cadence <cron>] [--level L1|L2|L3]
+ *
+ * Reads loop config, validates pattern, checks budget, constructs prompt,
+ * logs outcome.
+ */
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, "..")
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    return fallback
+  }
+}
+
+function writeJson(path, data) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n")
+}
+
+function nextMidnightISO() {
+  const now = new Date()
+  const mid = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1, 0, 0, 0, 0)
+  return mid.toISOString()
+}
+
+function parseArgs() {
+  const args = {}
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i]
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2)
+      const val = process.argv[i + 1]
+      if (val && !val.startsWith("--")) {
+        args[key] = val
+        i++
+      } else {
+        args[key] = true
+      }
+    }
+  }
+  return args
+}
+
+// --- Main ---
+async function main() {
+  const cli = parseArgs()
+  const loopDir = join(ROOT, ".opencode", "devloom", "loop")
+
+  // 1. Read loop config
+  const configPath = join(loopDir, "loop-config.json")
+  const config = readJson(configPath, {})
+  config.pattern = cli.pattern || config.pattern || "daily-triage"
+  config.cadence = cli.cadence || config.cadence || "0 0 * * *"
+  config.level = cli.level || config.level || "L1"
+  config.paused = config.paused || false
+
+  // 2a. Read until-done progress if mode is until-done
+  let progress = null
+  if (config.mode === "until-done") {
+    const progressPath = join(loopDir, "progress.json")
+    progress = readJson(progressPath, null)
+  }
+
+  // 2. Validate pattern exists
+  const registryPath = join(ROOT, "patterns", "registry.yaml")
+  const patternPath = join(ROOT, "patterns", `${config.pattern}.md`)
+
+  if (!existsSync(registryPath)) {
+    console.log("Warning: patterns/registry.yaml not found. Pattern validation skipped.")
+  }
+  if (!existsSync(patternPath)) {
+    console.log(`Error: pattern file not found: patterns/${config.pattern}.md`)
+    process.exit(1)
+  }
+
+  // 3. Check budget
+  const budgetPath = join(loopDir, "budget.json")
+  const budget = readJson(budgetPath, { dailyLimit: 500000, spent: 0, resetAt: nextMidnightISO() })
+
+  const now = new Date()
+  const resetAt = new Date(budget.resetAt)
+  if (now >= resetAt) {
+    budget.spent = 0
+    budget.resetAt = nextMidnightISO()
+    writeJson(budgetPath, budget)
+  }
+
+  const remaining = Math.max(0, budget.dailyLimit - budget.spent)
+  if (remaining <= 0) {
+    config.paused = true
+    writeJson(configPath, config)
+    console.log(`Budget exceeded (${budget.spent}/${budget.dailyLimit}). Loop paused.`)
+    console.log("Reset at:", budget.resetAt)
+    process.exit(1)
+  }
+
+  // 3a. Check until-done completion
+  if (config.mode === "until-done" && progress) {
+    const allVerified = progress.items.every((i) => i.status === "verified")
+    if (allVerified) {
+      console.log("===== Design-Audit Complete =====")
+      console.log(`All ${progress.total} pages verified against design system spec.`)
+      console.log("Fix loop finished. No more pages to process.")
+      process.exit(0)
+    }
+  }
+
+  // 4. Record start time
+  const startTime = Date.now()
+
+  // 5. Pattern cost estimate
+  const patternContent = readFileSync(patternPath, "utf8")
+  const costMatch = patternContent.match(/cost:\s*(\d+)/)
+  const estimatedCost = costMatch ? parseInt(costMatch[1]) : 50000
+
+  // 6. Construct prompt
+  let progressContext = ""
+  if (config.mode === "until-done" && progress) {
+    const pending = progress.items.filter((i) => i.status === "pending").length
+    const inProgress = progress.items.filter((i) => i.status === "in-progress").length
+    const byCategory = {}
+    for (const item of progress.items) {
+      const cat = item.category || "uncategorized"
+      byCategory[cat] = (byCategory[cat] || 0) + 1
+    }
+    const catSummary = Object.entries(byCategory).map(([k, v]) => `${k}=${v}`).join(" ")
+    progressContext = `\nProgress: ${progress.verified}/${progress.total} verified, ${pending} pending, ${inProgress} in-progress\nIssues by category: ${catSummary}\nCompletion condition: ${progress.completionCondition}`
+  }
+
+  const prompt = [
+    `[devloom-loop] Running pattern: ${config.pattern}`,
+    `Level: ${config.level}`,
+    `Cadence: ${config.cadence}`,
+    `Mode: ${config.mode || "recurring"}`,
+    `Budget remaining: ${remaining}/${budget.dailyLimit}`,
+    progressContext,
+    "",
+    `Pattern loaded from patterns/${config.pattern}.md.`,
+    `Execute the pattern's agent chain and log results.`,
+  ].join("\n")
+
+  // 7. In headless mode: opencode run "<prompt>"
+  // For now, construct the command and log it
+  const headlessCmd = `opencode run "${prompt.replace(/"/g, '\\"')}"`
+  console.log("===== DevLoom Loop Tick =====")
+  console.log("Pattern:", config.pattern)
+  console.log("Level:", config.level)
+  console.log("Mode:", config.mode || "recurring")
+  if (config.mode === "until-done" && progress) {
+    console.log("Progress:", `${progress.verified}/${progress.total} verified`)
+    const byCat = {}
+    for (const item of progress.items) {
+      const cat = item.category || "uncategorized"
+      byCat[cat] = (byCat[cat] || 0) + 1
+    }
+    console.log("Issues:", Object.entries(byCat).map(([k, v]) => `${k}=${v}`).join(", "))
+  }
+  console.log("Budget remaining:", remaining)
+  console.log("Estimated cost:", estimatedCost)
+  console.log("")
+  console.log("Headless command:")
+  console.log(headlessCmd)
+  console.log("")
+  console.log("===== Prompt =====")
+  console.log(prompt)
+
+  // 8. Record outcome
+  const durationMs = Date.now() - startTime
+  const runLogPath = join(loopDir, "run-log.json")
+  const runLog = readJson(runLogPath, [])
+  runLog.push({
+    timestamp: new Date().toISOString(),
+    pattern: config.pattern,
+    agentsUsed: [],
+    outcome: "success",
+    tokenCost: estimatedCost,
+    durationMs,
+    ...(config.mode === "until-done" && progress ? { progress: `${progress.verified}/${progress.total} verified` } : {}),
+  })
+  writeJson(runLogPath, runLog)
+
+  // 9. Deduct estimated cost from budget
+  budget.spent += estimatedCost
+  writeJson(budgetPath, budget)
+
+  console.log("")
+  console.log("Tick completed in", durationMs, "ms")
+  console.log("Cost deducted:", estimatedCost)
+  console.log("Run log updated")
+}
+
+main().catch((err) => {
+  console.error("Loop runner error:", err.message)
+  process.exit(1)
+})

package/scripts/model-capabilities.mjs

@@ -0,0 +1,194 @@
+// Provider-agnostic model identity, candidate resolution, and capability hints
+// for DevLoom profiles. Pure module: no fs, no child_process, no secrets.
+//
+// Design rules:
+// - Model IDs are conceptually `provider/model` (the model segment may itself
+//   contain slashes, e.g. `lmstudio/google/gemma-4-26b`). Any provider is valid;
+//   availability always comes from `opencode models` at the call site.
+// - MODEL_FAMILIES is the authoritative capability source for known families.
+//   `capabilitiesFor()` falls back to conservative name heuristics for unknown
+//   models — hints only, never a substitute for availability validation.
+// - Nothing here is MiMo-specific; MiMo is simply the first family registered.
+
+/** Conceptual model families with candidate chains + capability declarations. */
+export const MODEL_FAMILIES = {
+  mimoV26Flash: {
+    id: "mimoV26Flash",
+    label: "MiMo V2.6 Flash",
+    // Provider prefix is NOT assumed — resolution picks the first available.
+    candidates: [
+      "mimo/mimo-v2.6-flash",
+      "xiaomi/mimo-v2.6-flash",
+      "opencode-go/mimo-v2.6-flash",
+    ],
+    familyPattern: /(^|\/)mimo-v2\.6/i,
+    capabilities: {
+      vision: true,
+      multimodal: true,
+      coding: "high",
+      reasoning: "high",
+      toolUse: true,
+      longContext: true,
+      speed: "fast",
+      costClass: "low",
+      orchestration: true,
+      verification: "high",
+    },
+  },
+  deepseekV41Flash: {
+    id: "deepseekV41Flash",
+    label: "DeepSeek V4.1 Flash",
+    // Fast lane for general roles. Only verified ids enter the chain; the
+    // family pattern still discovers same-family variants at resolution time.
+    candidates: [
+      "opencode-go/deepseek-v4.1-flash",
+    ],
+    familyPattern: /(^|\/)deepseek-v4\.1/i,
+    capabilities: {
+      vision: false,
+      multimodal: false,
+      coding: "high",
+      reasoning: "high",
+      toolUse: true,
+      longContext: true,
+      speed: "fast",
+      costClass: "low",
+      orchestration: true,
+      verification: "high",
+    },
+  },
+}
+
+/** MiMo V2.6 Flash candidate chain (re-exported for profile manager + tests). */
+export const MIMO_V26_FLASH_CANDIDATES = MODEL_FAMILIES.mimoV26Flash.candidates
+
+/** DeepSeek V4.1 Flash candidate chain (general/fast roles). */
+export const DEEPSEEK_V41_FLASH_CANDIDATES = MODEL_FAMILIES.deepseekV41Flash.candidates
+
+/**
+ * Vision-capable fallbacks used when a vision-required role (vision,
+ * visual-critic) resolves to a text-only model. Ordered by existing DevLoom
+ * convention: Go multimodal models first, free-tier vision model last.
+ */
+export const VISION_FALLBACK_CANDIDATES = [
+  "opencode-go/qwen3.6-plus",
+  "opencode-go/glm-5.3-flash",
+  "opencode-go/deepseek-v4-flash-vision-exp",
+  "opencode-go/minimax-m3",
+  "opencode/mimo-v2.5-free",
+]
+
+/** Roles whose assigned model must accept image input. */
+const VISION_REQUIRED_ROLES = new Set(["vision", "visual-critic"])
+
+const PROVIDER_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._+/-]*$/
+
+/**
+ * True for any well-formed OpenCode model identifier of the form
+ * `provider/model` (the model segment may contain further slashes).
+ * Availability is a separate concern — see findAvailableCandidate().
+ */
+export function isValidModelId(id) {
+  if (typeof id !== "string") return false
+  if (!id || id.length > 256 || /\s/.test(id)) return false
+  const slash = id.indexOf("/")
+  if (slash <= 0 || slash === id.length - 1) return false
+  const provider = id.slice(0, slash)
+  const model = id.slice(slash + 1)
+  if (!PROVIDER_RE.test(provider)) return false
+  if (!MODEL_RE.test(model)) return false
+  if (model.startsWith("/") || model.endsWith("/")) return false
+  return true
+}
+
+/** First candidate present in the available list, or null. */
+export function findAvailableCandidate(candidates, available) {
+  if (!Array.isArray(candidates) || !Array.isArray(available)) return null
+  for (const candidate of candidates) {
+    if (available.includes(candidate)) return candidate
+  }
+  return null
+}
+
+/**
+ * Resolve a candidate chain against the available model list.
+ *
+ * Returns { model, attempted, exact, fallback }:
+ * - exact hit on any declared candidate → exact: true
+ * - optional opts.familyPattern permits a same-family fallback (e.g.
+ *   mimo-v2.6-flash → mimo-v2.6-pro) reported with exact: false so callers
+ *   can surface "requested vs resolved" transparently
+ * - otherwise model: null — callers must fail loudly, never pretend
+ */
+export function resolveModelCandidate(candidates, available, opts = {}) {
+  const attempted = Array.isArray(candidates) ? [...candidates] : []
+  const list = Array.isArray(available) ? available : []
+  const exact = findAvailableCandidate(attempted, list)
+  if (exact) return { model: exact, attempted, exact: true, fallback: null }
+  if (opts.familyPattern instanceof RegExp) {
+    const family = list.find((m) => isValidModelId(m) && opts.familyPattern.test(m))
+    if (family) return { model: family, attempted, exact: false, fallback: family }
+  }
+  return { model: null, attempted, exact: false, fallback: null }
+}
+
+function familyCapabilities(modelId) {
+  for (const family of Object.values(MODEL_FAMILIES)) {
+    if (family.candidates.includes(modelId)) return { ...family.capabilities }
+    if (family.familyPattern instanceof RegExp && family.familyPattern.test(modelId)) {
+      return { ...family.capabilities }
+    }
+  }
+  return null
+}
+
+/**
+ * Capability hints for a model id. Authoritative for registered families;
+ * conservative heuristics otherwise. Callers must not treat `vision: false`
+ * from the heuristic path as proof a model cannot see images — it only means
+ * DevLoom has no evidence, which is the safe direction for routing decisions.
+ */
+export function capabilitiesFor(modelId) {
+  const id = typeof modelId === "string" ? modelId : ""
+  const known = familyCapabilities(id)
+  if (known) return known
+  const caps = {
+    vision: false,
+    multimodal: false,
+    coding: "medium",
+    reasoning: "medium",
+    toolUse: true,
+    longContext: false,
+    speed: "medium",
+    costClass: "unknown",
+    orchestration: false,
+    verification: "medium",
+  }
+  // Known multimodal markers observed in OpenCode catalogs.
+  if (/vision|minimax-m3|qwen3\.6|mimo-v2\.[56]|glm-5\.3/i.test(id)) {
+    caps.vision = true
+    caps.multimodal = true
+  }
+  if (/-free$|big-pickle/.test(id)) caps.costClass = "free"
+  if (/flash/i.test(id)) caps.speed = "fast"
+  if (/pro|max|kimi-k3|glm-5\.2$/.test(id)) {
+    caps.reasoning = "high"
+    caps.coding = "high"
+  }
+  if (/kimi-k2\.7-code|kimi-k3|qwen3\.7|longcat|glm-5\.3$/.test(id)) caps.longContext = true
+  return caps
+}
+
+export function roleRequiresVision(role) {
+  return VISION_REQUIRED_ROLES.has(role)
+}
+
+/** Whether a model satisfies a role's capability requirements. */
+export function modelMeetsRole(modelId, role) {
+  if (!roleRequiresVision(role)) return { ok: true, missing: [] }
+  const caps = capabilitiesFor(modelId)
+  const missing = []
+  if (!caps.vision) missing.push("vision")
+  return { ok: missing.length === 0, missing }
+}

package/scripts/plugin-cache.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+// Shared helpers for keeping the OpenCode plugin cache in sync with the
+// installed DevLoom package.
+//
+// OpenCode installs npm plugins into `~/.cache/opencode/packages/<spec>` with
+// `ignoreScripts: true`, so the package `postinstall` never runs there and the
+// cached copy can silently go stale. These helpers refresh the cached package
+// files (dist, agents, commands, ...) directly from a package source directory.
+import {
+  existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync,
+  copyFileSync, rmSync, statSync,
+} from "fs"
+import { resolve, dirname, join } from "path"
+import { fileURLToPath } from "url"
+import { homedir, platform } from "os"
+import { execFileSync } from "node:child_process"
+
+export function getOpenCodeCacheDir(_platform = platform(), _homedir = homedir(), _env = process.env) {
+  if (_platform === "win32") {
+    return resolve(_env.LOCALAPPDATA ?? _homedir, "cache", "opencode")
+  }
+  if (_platform === "darwin") {
+    const xdg = resolve(_env.XDG_CACHE_HOME ?? join(_homedir, ".cache"), "opencode")
+    const lib = resolve(_homedir, "Library", "Caches", "opencode")
+    // OpenCode uses the XDG cache path on macOS too; only fall back to the
+    // Library path when that is the one present on disk (older builds).
+    if (!existsSync(xdg) && existsSync(lib)) return lib
+    return xdg
+  }
+  return resolve(_env.XDG_CACHE_HOME ?? join(_homedir, ".cache"), "opencode")
+}
+
+// Names of OpenCode plugin cache entries that contain a `devloom` package.
+// Both `devloom` (legacy) and `devloom@latest` (current config spec) exist in
+// the wild; refreshing both is harmless and covers every loader path.
+export function openCodePluginEntries(cacheDir) {
+  const packagesDir = join(cacheDir, "packages")
+  if (!existsSync(packagesDir)) return []
+  let entries = []
+  try {
+    entries = readdirSync(packagesDir)
+  } catch {
+    return []
+  }
+  return entries.filter((entry) => {
+    try {
+      return existsSync(join(packagesDir, entry, "node_modules", "devloom"))
+    } catch {
+      return false
+    }
+  })
+}
+
+function copyDir(src, dest) {
+  if (existsSync(dest) && !statSync(src).isDirectory()) {
+    rmSync(dest, { recursive: true, force: true })
+  }
+  const stat = statSync(src)
+  if (stat.isDirectory()) {
+    mkdirSync(dest, { recursive: true })
+    for (const name of readdirSync(src)) {
+      copyDir(join(src, name), join(dest, name))
+    }
+  } else {
+    mkdirSync(dirname(dest), { recursive: true })
+    copyFileSync(src, dest)
+  }
+}
+
+// Rebuild dist/ from source before it is copied into the OpenCode plugin cache,
+// so a refresh never deploys stale compiled code. Runs the package's declared
+// `build` script (npm run build) when present. Best-effort: never throws —
+// failures are reported in the returned summary and the caller proceeds with
+// whatever dist already exists.
+export function buildPackageDist(sourceDir, exec = execFileSync) {
+  const summary = { built: false, skipped: "", errors: [] }
+  try {
+    const pkg = JSON.parse(readFileSync(join(sourceDir, "package.json"), "utf8"))
+    const build = pkg.scripts && typeof pkg.scripts.build === "string" ? pkg.scripts.build : ""
+    if (!build) {
+      summary.skipped = "no build script in package.json"
+      return summary
+    }
+    exec("npm", ["run", "build"], { cwd: sourceDir, stdio: "ignore", timeout: 120_000 })
+    summary.built = true
+  } catch (err) {
+    summary.errors.push(`build failed: ${err && typeof err.message === "string" ? err.message : String(err)}`)
+  }
+  return summary
+}
+
+// Copy the current package (dist, agents, commands, ... per package.json
+// `files` plus package.json itself) into every existing OpenCode plugin cache
+// entry. Best-effort: never throws, reports per-entry results.
+export function refreshOpenCodePluginCache(sourceDir, cacheDir = getOpenCodeCacheDir(), exec = execFileSync) {
+  const summary = { refreshed: [], skipped: [], errors: [], build: null }
+  // Root-cause guard against the "status ok but stale" class of bugs: the
+  // refresh pipeline must ship freshly built code, not whatever dist happens
+  // to sit in the source tree. Rebuild before copying.
+  const build = buildPackageDist(sourceDir, exec)
+  summary.build = build
+  if (build.errors.length > 0) summary.errors.push(...build.errors)
+  let roots = []
+  try {
+    const pkg = JSON.parse(readFileSync(join(sourceDir, "package.json"), "utf8"))
+    roots = Array.isArray(pkg.files) ? pkg.files : []
+  } catch (err) {
+    summary.errors.push(`cannot read package.json at ${sourceDir}: ${err.message}`)
+    return summary
+  }
+
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) {
+    summary.skipped.push(cacheDir)
+    return summary
+  }
+
+  const toCopy = [...roots, "package.json"]
+  for (const entry of entries) {
+    const destPkg = join(cacheDir, "packages", entry, "node_modules", "devloom")
+    let copied = 0
+    for (const root of toCopy) {
+      const src = join(sourceDir, root)
+      if (!existsSync(src)) continue
+      try {
+        copyDir(src, join(destPkg, root))
+        copied++
+      } catch (err) {
+        summary.errors.push(`${entry}/${root}: ${err.message}`)
+      }
+    }
+    if (copied > 0) summary.refreshed.push(entry)
+  }
+  return summary
+}
+
+// Sync the installed agent files into the cached plugin package so a profile
+// change is reflected even in the cache copy. Best-effort, never throws.
+export function refreshOpenCodePluginAgentFiles(agentsDir, cacheDir = getOpenCodeCacheDir()) {
+  const summary = { refreshed: [], skipped: [], errors: [] }
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) {
+    summary.skipped.push(cacheDir)
+    return summary
+  }
+  for (const entry of entries) {
+    const destAgents = join(cacheDir, "packages", entry, "node_modules", "devloom", "agents")
+    try {
+      mkdirSync(destAgents, { recursive: true })
+      const files = readdirSync(agentsDir).filter((f) => f.startsWith("devloom-") && f.endsWith(".md"))
+      for (const file of files) {
+        copyFileSync(join(agentsDir, file), join(destAgents, file))
+      }
+      summary.refreshed.push(entry)
+    } catch (err) {
+      summary.errors.push(`${entry}: ${err.message}`)
+    }
+  }
+  return summary
+}
+
+// Sync the runtime dependencies of the installed package into every existing
+// cache entry. The TUI plugin (dist/tui.js) imports `@opentui/solid` +
+// `solid-js`, and OpenCode installs plugins with `ignoreScripts` so those deps
+// are not guaranteed to exist in the cache. Running `npm install` inside the
+// cached plugin directory mirrors what a normal package install would do,
+// without touching the cache entry root (no pruning of existing packages).
+// Best-effort: never throws, reports per-entry results.
+export function syncOpenCodePluginDependencies(sourceDir, cacheDir = getOpenCodeCacheDir(), exec = execFileSync) {
+  const summary = { synced: [], skipped: [], errors: [] }
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) {
+    summary.skipped.push(cacheDir)
+    return summary
+  }
+  for (const entry of entries) {
+    const pluginDir = join(cacheDir, "packages", entry, "node_modules", "devloom")
+    try {
+      exec(
+        "npm",
+        [
+          "install", "--prefix", pluginDir,
+          "--no-save", "--ignore-scripts", "--no-audit", "--no-fund",
+          "--no-package-lock", "--omit=dev", "--loglevel=error",
+        ],
+        { stdio: "ignore", timeout: 120_000 }
+      )
+      summary.synced.push(entry)
+    } catch (err) {
+      summary.errors.push(`${entry}: ${err && typeof err.message === "string" ? err.message : String(err)}`)
+    }
+  }
+  return summary
+}
+
+// Per-entry cache health breakdown.
+// "ok"   – every existing cache entry has the config hook that injects DevLoom
+//          agents AND the current feature code (the profile-filter wiring in
+//          dist/agents.js, detected via `agentVariantVisible`). Conservative:
+//          one stale entry makes the whole cache stale.
+// "stale"– at least one cache entry lacks the config hook or the feature code.
+// "missing" – DevLoom was never installed as an OpenCode plugin.
+export function pluginCacheStatusDetail(cacheDir = getOpenCodeCacheDir()) {
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) return { status: "missing", entries: [] }
+  const details = entries.map((entry) => {
+    const base = join(cacheDir, "packages", entry, "node_modules", "devloom")
+    let hook = false
+    let featureCode = false
+    let orchestratorLabel = false
+    try {
+      const pluginJs = join(base, "dist", "plugin.js")
+      if (existsSync(pluginJs)) {
+        hook = readFileSync(pluginJs, "utf8").includes("injectDevloomAgents")
+      }
+    } catch { /* entry treated as stale */ }
+    try {
+      // The profile-filter feature marker: present only in freshly built dist.
+      const agentsJs = join(base, "dist", "agents.js")
+      if (existsSync(agentsJs)) {
+        featureCode = readFileSync(agentsJs, "utf8").includes("agentVariantVisible")
+      }
+    } catch { /* entry treated as stale */ }
+    try {
+      const orchestratorMd = join(base, "agents", "devloom-orchestrator.md")
+      if (existsSync(orchestratorMd)) {
+        orchestratorLabel = /\(profile: [^)]+\)/.test(readFileSync(orchestratorMd, "utf8"))
+      }
+    } catch { /* label unknown -> false */ }
+    return { entry, hook, featureCode, orchestratorLabel }
+  })
+  const status = details.every((detail) => detail.hook && detail.featureCode) ? "ok" : "stale"
+  return { status, entries: details }
+}
+
+export function pluginCacheStatus(cacheDir = getOpenCodeCacheDir()) {
+  return pluginCacheStatusDetail(cacheDir).status
+}
+
+export function runCli(args, cacheDir = getOpenCodeCacheDir()) {
+  const command = args[0] || ""
+  if (command === "status") {
+    const detail = pluginCacheStatusDetail(cacheDir)
+    console.log(`DevLoom plugin cache: ${detail.status}`)
+    if (detail.entries.length === 0) {
+      console.log("  No DevLoom plugin cache entry found.")
+      console.log("  Install the plugin once with: opencode plugin devloom --global")
+      console.log("  then refresh the cache with: npm install -g devloom && node $(npm root -g)/devloom/postinstall.mjs")
+      return detail.status
+    }
+    for (const entry of detail.entries) {
+      const hook = entry.hook ? "yes" : "NO"
+      const feature = entry.featureCode ? "yes" : "NO"
+      const label = entry.orchestratorLabel ? "yes" : "no"
+      console.log(`  ${entry.entry}: config-hook=${hook} feature-code=${feature} orchestrator-profile-label=${label}`)
+    }
+    if (detail.status !== "ok") {
+      console.log("  Fix: run /devloom-refresh, then restart opencode (or: opencode --continue).")
+    }
+    return detail.status
+  }
+  console.log("DevLoom plugin cache helpers")
+  console.log("Commands:")
+  console.log("  devloom plugin-cache status  — print cache health (ok/stale/missing) + per-entry info")
+  return null
+}
+
+const isMain = process.argv[1] ? fileURLToPath(import.meta.url) === resolve(process.argv[1]) : false
+if (isMain) runCli(process.argv.slice(2))