pantheon-opencode 1.6.0-beta.6 → 1.6.0-beta.7

package/scripts/build-agents-md.mjs

@@ -8,11 +8,11 @@
  * across both versions without duplication, this script consolidates:
  *
  *   (a) a static header (project description + agent table + setup notes)
- *   (b) every src/instructions/*.instructions.md body, embedded under a
- *       `## <name>` section marker (name taken from frontmatter)
+ *   (b) shared instruction bodies embedded under a `## <name>` section marker;
+ *       agent-scoped bodies are rendered into only their matching agent prompt
  *
- * into one generated AGENTS.md. src/instructions/*.instructions.md remains
- * the source of truth — AGENTS.md is a committed build artifact, never
+ * into AGENTS.md plus selective agent prompt content. The instruction files
+ * remain the source of truth; AGENTS.md is a committed build artifact, never
  * hand-edited.
  *
  * Usage:
@@ -22,8 +22,8 @@
  * No runtime dependencies (Node >= 18, stdlib only). Idempotent: running it
  * twice produces byte-identical output.
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -44,19 +44,19 @@ This project uses the Pantheon multi-agent framework with 14 specialized agents.
 
 | Agent | Role |
 |-------|------|
-| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Calls apollo for discovery, sends to themis for review. |
+| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Uses discovery/review proportionally to scope and risk. |
 | @apollo | Read-only investigation scout — 3–10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands. |
 | @athena | Strategic planner & architect — research-first, plan-only, never implements. Plans include quality gates (ruff/Biome, dep detection, LTS policy). Calls apollo for discovery. |
-| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Calls apollo for discovery, sends to themis. |
+| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Preserves review gates for schema/data changes. |
 | @gaia | Remote sensing domain specialist — satellite image processing, spectral analysis, SAR, change detection, time series, ML/DL classification. Read-only analysis of geospatial data. |
 | @hephaestus | AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Calls apollo, sends to themis. |
-| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Calls apollo for discovery, sends to themis. |
+| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Uses discovery/review proportionally to scope and risk. |
 | @iris | GitHub operations specialist — branches, pull requests, issues, releases, tags. Called by zeus after review. Never pushes or merges without explicit human approval. Integrates with VS Code GitHub Pull Requests extension. |
 | @mnemosyne | Memory bank quality owner — initializes .pantheon/memory-bank/, writes ADRs and task records on explicit request. Called by zeus. Never invoked automatically after phases. |
 | @nyx | Observability & monitoring specialist — OpenTelemetry tracing, token/cost tracking, agent performance analytics, LangSmith integration. Calls apollo for discovery, sends to themis. |
 | @prometheus | Infrastructure + model provider specialist — Docker, CI/CD, multi-model routing, cost optimization, provider abstraction |
 | @talos | Hotfix express lane — direct fixes for small bugs, CSS, typos, minor logic. No TDD ceremony, no orchestration overhead. Standalone, no subagents. Escalates complex issues to zeus. |
-| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, coverage >80%, correctness, deprecation audit. Called by implementers; escalates blockers to zeus. |
+| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, applicable coverage requirements, correctness, deprecation audit. Reviews material/sensitive changes. |
 | @zeus | Central orchestrator — never implements. Delegates to: athena, apollo, hermes, aphrodite, demeter, prometheus, themis, iris, mnemosyne, talos, hephaestus, nyx |
 
 ## OpenCode Setup
@@ -73,13 +73,14 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 
 - Rodar: \`bash ~/pantheon-sandbox/run-test.sh\` (opencode mcp list 5/5 connected + doctor 0 erros + abre TUI isolado)
 - Regra para agentes: ao validar instalação global (npm pack, \`init\`, MCPs, hooks), usar o sandbox — NUNCA testar no ambiente de dev
-- Descarte: \`rm -rf ~/pantheon-sandbox\`
-- Detalhes: ver \`~/pantheon-sandbox/README.md\`
+- Prepare/atualize com \`bash scripts/test-opencode-v2-sandbox.sh --prepare\`; isso gera \`run-test.sh\`, \`start-pantheon.sh\` e o README do sandbox
+- Descarte somente pelo reset com guardas: \`bash scripts/test-opencode-v2-sandbox.sh --reset\` (nunca use \`rm -rf\` manualmente)
+- Detalhes: ver \`~/pantheon-sandbox/README.md\` após o prepare
 
 ## Conventions
 
-- TDD: Write failing test first, then implement
-- Coverage minimum: 80%
+- TDD: RED→GREEN→REFACTOR for testable behavior; use focused checks for micro-edits
+- Honor repository coverage thresholds when relevant; preserve stronger auth/security/data-integrity gates
 - Async/await on all I/O
 - Type hints on all functions
 - PRs always update the README — every pull request must document newly added features, behaviors, env vars, or commands in the README before being opened.
@@ -92,20 +93,41 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 /**
  * Parse YAML-ish frontmatter from an instruction file.
  *
- * Only the `name` field is extracted (single-line scalar). The frontmatter
- * block itself is stripped from the embedded body.
+ * Preserve the file-scope `applyTo` glob separately from the explicit
+ * `agents` selectors. In particular, a Python workspace glob is never
+ * interpreted as an agent name. The frontmatter block is stripped from
+ * the embedded body.
  *
  * @param {string} content - Raw file content
- * @returns {{ name: string, body: string } | null}
+ * @returns {{ name: string, body: string, applyTo: string | null,
+ *   agents: string[], fallback: string | null, appliesToAgent: (name: string) => boolean } | null}
  */
-function parseInstruction(content) {
+export function parseInstruction(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
   if (!match) return null
   const fm = match[1]
   const nameMatch = fm.match(/^name:\s*["']?([^"'\r\n]+)["']?\s*$/m)
   if (!nameMatch) return null
+  const applyToMatch = fm.match(/^applyTo:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  const agentsMatch = fm.match(/^agents:\s*\[([^\]\r\n]*)\]\s*$/m)
+  const agents = agentsMatch
+    ? agentsMatch[1]
+        .split(',')
+        .map((agent) => agent.trim().replace(/^(["'])(.*)\1$/, '$2'))
+        .filter(Boolean)
+    : fm.match(/^agents:/m)
+      ? [] // Malformed explicit selector: fail closed; never make it global.
+      : applyToMatch
+        ? [] // File-scoped instructions need an explicit agent association.
+        : ['*'] // Legacy instructions without selectors remain shared.
+  const fallbackMatch = fm.match(/^fallback:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  const appliesToAgent = (agent) => agents.includes('*') || agents.includes(agent)
   return {
     name: nameMatch[1].trim(),
+    applyTo: applyToMatch?.[1].trim() ?? null,
+    agents,
+    fallback: fallbackMatch?.[1].trim() ?? null,
+    appliesToAgent,
     body: `${content.slice(match[0].length).trimEnd()}\n`,
   }
 }
@@ -114,7 +136,8 @@ function parseInstruction(content) {
  * Read all src/instructions/*.instructions.md files, sorted by filename for
  * deterministic output.
  *
- * @returns {Array<{ file: string, name: string, body: string }>}
+ * @returns {Array<{ file: string, name: string, body: string, applyTo: string | null,
+ *   agents: string[], fallback: string | null, appliesToAgent: (name: string) => boolean }>}
  */
 export function readInstructions() {
   if (!existsSync(INSTRUCTIONS_DIR)) return []
@@ -137,10 +160,13 @@ export function readInstructions() {
 /**
  * Generate the full AGENTS.md content.
  *
- * @param {Array<{ file: string, name: string, body: string }>} instructions
+ * @param {Array<{ file: string, name: string, body: string, agents?: string[] }>} instructions
  * @returns {string}
  */
 export function generateAgentsMd(instructions) {
+  const sharedInstructions = instructions.filter(
+    (instr) => !instr.agents || instr.agents.includes('*'),
+  )
   const sections = [
     '<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->',
     '<!-- Source of truth: src/instructions/*.instructions.md (AGENTS.md is a committed build artifact). -->',
@@ -153,10 +179,11 @@ export function generateAgentsMd(instructions) {
     '',
     'The following sections are consolidated from `src/instructions/*.instructions.md`',
     'so both OpenCode V1 (auto-loads AGENTS.md) and V2 (loads AGENTS.md, ignores the',
-    '`instructions` config key) receive identical instruction content.',
+    '`instructions` config key) receive identical shared rules. Agent-scoped rules',
+    'are rendered into only the matching installed agent prompts.',
     '',
   ]
-  for (const instr of instructions) {
+  for (const instr of sharedInstructions) {
     sections.push(
       `<!-- Source: src/instructions/${instr.file} -->`,
       `## ${instr.name}`,
@@ -168,6 +195,110 @@ export function generateAgentsMd(instructions) {
   return `${sections.join('\n').trimEnd()}\n`
 }
 
+const GENERATED_AGENT_BLOCK =
+  /\n?<!-- Pantheon selective instructions: generated -->[\s\S]*?<!-- \/Pantheon selective instructions -->\n?/g
+
+/**
+ * Render the agent-specific instruction set into the supported agent prompt.
+ * The shared rules remain in AGENTS.md; file globs are retained as scope
+ * guidance and are never used as agent selectors.
+ *
+ * @param {string} agentName - Canonical agent name from the prompt filename
+ * @param {string} prompt - Canonical source agent prompt
+ * @param {Array<{ file: string, name: string, body: string, applyTo?: string | null,
+ *   agents?: string[], fallback?: string | null }>} instructions
+ * @returns {string}
+ */
+export function generateAgentPrompt(agentName, prompt, instructions = readInstructions()) {
+  const basePrompt = prompt.replace(GENERATED_AGENT_BLOCK, '').trimEnd()
+  const selected = instructions.filter(
+    (instr) => instr.agents && !instr.agents.includes('*') && instr.agents.includes(agentName),
+  )
+  if (selected.length === 0) {
+    return [
+      basePrompt,
+      '',
+      '<!-- Pantheon selective instructions: generated -->',
+      'No agent-specific instructions are assigned; follow the shared rules in AGENTS.md.',
+      '<!-- /Pantheon selective instructions -->',
+      '',
+    ].join('\n')
+  }
+
+  const sections = selected.map((instr) => {
+    const scope = instr.applyTo
+      ? `\n\n> Apply only when a target workspace file matches \`${instr.applyTo}\`.`
+      : ''
+    const fallback =
+      instr.fallback === 'shared'
+        ? '\n\n> For work outside this scope, use the shared rules in AGENTS.md.'
+        : ''
+    return [
+      `<!-- Source: src/instructions/${instr.file} -->`,
+      `## ${instr.name}${scope}`,
+      '',
+      `${instr.body.trimEnd()}${fallback}`,
+    ].join('\n')
+  })
+  return [
+    basePrompt,
+    '',
+    '<!-- Pantheon selective instructions: generated -->',
+    sections.join('\n\n'),
+    '<!-- /Pantheon selective instructions -->',
+    '',
+  ].join('\n')
+}
+
+/**
+ * Copy agent prompts with scoped instructions embedded in each actual prompt.
+ * Used by both init and postinstall sync so the installed runtime receives the
+ * same selection without a per-turn injection hook.
+ *
+ * @param {string} sourceDir - Canonical src/agents directory
+ * @param {string} targetDir - OpenCode agents directory
+ * @param {boolean} dryRun - Do not write when true
+ * @param {boolean} existingOnly - Refresh installed prompts without adding missing agents
+ * @returns {{ created: number, skipped: number }}
+ */
+export function copyAgentPrompts(sourceDir, targetDir, dryRun = false, existingOnly = false) {
+  const instructions = readInstructions()
+  if (!dryRun && !existingOnly) mkdirSync(targetDir, { recursive: true })
+  let created = 0
+  let skipped = 0
+  for (const file of readdirSync(sourceDir)
+    .filter((entry) => entry.endsWith('.md'))
+    .sort()) {
+    if (file.toLowerCase() === 'readme.md') continue
+    const sourcePath = join(sourceDir, file)
+    if (!statSync(sourcePath).isFile()) continue
+    const agentName = file.replace(/\.md$/, '')
+    const output = generateAgentPrompt(agentName, readFileSync(sourcePath, 'utf8'), instructions)
+    const targetPath = join(targetDir, file)
+    if (existingOnly && !existsSync(targetPath)) continue
+    const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf8') : null
+    if (existing === output) {
+      skipped++
+    } else {
+      if (!dryRun) writeFileSync(targetPath, output, 'utf8')
+      created++
+    }
+  }
+  return { created, skipped }
+}
+
+/**
+ * Count LF-delimited logical lines without assuming a trailing newline.
+ *
+ * @param {string} content - File content
+ * @returns {number}
+ */
+export function logicalLineCount(content) {
+  if (content.length === 0) return 0
+  const separators = content.match(/\n/g)?.length ?? 0
+  return separators + (content.endsWith('\n') ? 0 : 1)
+}
+
 // ---------------------------------------------------------------------------
 // CLI entry point
 // ---------------------------------------------------------------------------
@@ -175,6 +306,9 @@ export function generateAgentsMd(instructions) {
 function main() {
   const checkOnly = process.argv.includes('--check')
   const instructions = readInstructions()
+  const sharedCount = instructions.filter(
+    (instr) => !instr.agents || instr.agents.includes('*'),
+  ).length
   const content = generateAgentsMd(instructions)
 
   if (checkOnly) {
@@ -183,15 +317,15 @@ function main() {
       console.error(`❌ AGENTS.md is stale — run: node scripts/build-agents-md.mjs`)
       process.exit(1)
     }
-    console.log(`✅ AGENTS.md is up to date (${instructions.length} instruction sections)`)
+    console.log(`✅ AGENTS.md is up to date (${sharedCount} shared instruction sections)`)
     return
   }
 
   writeFileSync(AGENTS_MD_PATH, content, 'utf8')
-  const lines = content.split('\n').length
-  console.log(
-    `✅ Generated AGENTS.md (${instructions.length} instruction sections, ${lines} lines)`,
-  )
+  const lines = logicalLineCount(content)
+  console.log(`✅ Generated AGENTS.md (${sharedCount} shared instruction sections, ${lines} lines)`)
 }
 
-main()
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+}

package/scripts/doctor.mjs

@@ -1200,33 +1200,58 @@ export function resolveMcpCwd(entry, configPath = '') {
 // ---------------------------------------------------------------------------
 
 /**
- * Prerelease-aware comparison for pantheon versions (X.Y.Z or X.Y.Z-beta.N).
- * A stable release outranks any beta of the same core version. Returns
+ * Prerelease-aware comparison for pantheon versions (X.Y.Z with an optional
+ * semver prerelease suffix: `-beta.9`, `-rc.1`, ...). A stable release
+ * outranks any prerelease of the same core version; two prereleases compare
+ * identifier by identifier, numeric identifiers numerically. Returns
  * <0, 0, >0 (a - b). The shared compareVersions/parseVersion above ignores
- * the `-beta.N` suffix (it only reads 4 numeric groups), which would make
- * every beta pair compare equal.
+ * the prerelease suffix (it only reads 4 numeric groups), which would make
+ * every prerelease pair compare equal.
  */
 function comparePantheonVersions(a, b) {
   const parse = (v) => {
     const m = String(v)
       .trim()
-      .match(/^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/)
+      .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/)
     if (!m) return null
     return {
       core: [+m[1], +m[2], +m[3]],
-      beta: m[4] === undefined ? Number.POSITIVE_INFINITY : +m[4],
+      prerelease: m[4] === undefined ? null : m[4].split('.'),
     }
   }
+  // Per semver precedence: numeric identifiers compare numerically and rank
+  // below alphanumeric ones; a shorter identifier list ranks below a longer
+  // one sharing its prefix; a version WITHOUT a prerelease outranks any
+  // prerelease of the same core version.
+  const comparePrerelease = (pa, pb) => {
+    if (pa === null && pb === null) return 0
+    if (pa === null) return 1
+    if (pb === null) return -1
+    const length = Math.max(pa.length, pb.length)
+    for (let i = 0; i < length; i++) {
+      const x = pa[i]
+      const y = pb[i]
+      if (x === undefined) return -1
+      if (y === undefined) return 1
+      const xNumeric = /^\d+$/.test(x)
+      const yNumeric = /^\d+$/.test(y)
+      if (xNumeric && yNumeric) {
+        if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1
+      } else if (xNumeric !== yNumeric) {
+        return xNumeric ? -1 : 1
+      } else if (x !== y) {
+        return x < y ? -1 : 1
+      }
+    }
+    return 0
+  }
   const pa = parse(a)
   const pb = parse(b)
   if (!pa || !pb) return 0
   for (let i = 0; i < 3; i++) {
     if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i]
   }
-  // Infinity - Infinity is NaN, which would make equal stable versions compare
-  // as drift for any caller using a strict === 0 check.
-  if (pa.beta === pb.beta) return 0
-  return pa.beta < pb.beta ? -1 : 1
+  return comparePrerelease(pa.prerelease, pb.prerelease)
 }
 
 /**
@@ -1292,8 +1317,24 @@ export function checkInstallVersionDrift(args) {
 // registered plugin points into against this package's own version. Without
 // network access the "latest" version IS the running package's version.
 
+// Single source of truth: the package name is read from package.json, the same
+// way scripts/install/opencode.mjs derives the V2 pin spec. The fallback keeps
+// the doctor usable on a broken manifest.
+const PACKAGE_MANIFEST = readJson(join(ROOT, 'package.json'))
+const PANTHEON_PACKAGE_NAME =
+  typeof PACKAGE_MANIFEST?.name === 'string' && PACKAGE_MANIFEST.name
+    ? PACKAGE_MANIFEST.name
+    : 'pantheon-opencode'
+// Matches the exact version-pinned V2 spec the installer writes
+// (`<name>@X.Y.Z` plus any semver prerelease suffix). The name is escaped
+// because package names may contain regex-significant characters (`.` in
+// unscoped names, `/` in scoped ones).
+const PINNED_PLUGIN_SPEC_PATTERN = new RegExp(
+  `^${PANTHEON_PACKAGE_NAME.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&')}@(\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?)$`,
+)
+
 /** Locates an installed copy of this package inside a dependency tree. */
-const INSTALLED_PACKAGE_MARKER = '/node_modules/pantheon-opencode/'
+const INSTALLED_PACKAGE_MARKER = `/node_modules/${PANTHEON_PACKAGE_NAME}/`
 
 /**
  * Return the installed-package root containing a plugin path, or null when the
@@ -1362,8 +1403,10 @@ export function collectRegisteredPluginRefs(configs) {
         if (typeof ref === 'string') {
           refs.push({ path: ref, configPath: cfg.path, configLabel: cfg.label })
         } else if (ref && typeof ref === 'object') {
-          // Object-shaped entries carry their path under `path`/`source`.
-          const objectPath = ['path', 'source', 'id', 'name'].find(
+          // npm plugin entries carry their identity under `package`; local
+          // entries use `path`/`source`. Preserve either so H3 can inspect the
+          // exact pinned npm version as well as installed filesystem copies.
+          const objectPath = ['package', 'path', 'source', 'id', 'name'].find(
             (k) => typeof ref[k] === 'string',
           )
           if (objectPath) {
@@ -1376,6 +1419,20 @@ export function collectRegisteredPluginRefs(configs) {
   return refs
 }
 
+/**
+ * Read an exact version from the package-root plugin syntax written by the
+ * V2 installer (`pantheon-opencode@1.6.0`), including ANY semver prerelease
+ * suffix (`-beta.11`, `-rc.1`, ...). Unpinned and unrelated packages
+ * deliberately return null: H3 cannot infer their resolved npm cache version.
+ * @param {string} pluginRef
+ * @returns {string|null}
+ */
+function readPinnedPantheonPluginVersion(pluginRef) {
+  if (typeof pluginRef !== 'string') return null
+  const match = pluginRef.match(PINNED_PLUGIN_SPEC_PATTERN)
+  return match?.[1] ?? null
+}
+
 /**
  * Compare the version of the package each registered plugin points into (when
  * it is an installed copy under node_modules/pantheon-opencode) against this
@@ -1404,6 +1461,21 @@ export function checkPluginVersionDrift(args) {
   let compared = 0
   let driftReported = false
   for (const ref of refs) {
+    const pinnedNpmVersion = readPinnedPantheonPluginVersion(ref.path)
+    if (pinnedNpmVersion) {
+      const identity = `npm:${PANTHEON_PACKAGE_NAME}@${pinnedNpmVersion}`
+      if (seen.has(identity)) continue
+      seen.add(identity)
+      compared++
+
+      if (classifyPluginVersionDrift(pinnedNpmVersion, packageVersion) !== 'drift') continue
+      driftReported = true
+      warn(
+        `${ref.configLabel}: V2 plugin is pinned to ${PANTHEON_PACKAGE_NAME}@${pinnedNpmVersion}, but this package is v${packageVersion} — the registered tool surface may be stale. Run \`npx pantheon-opencode init\` to realign the pinned plugin version`,
+      )
+      continue
+    }
+
     const absolute = isAbsolute(ref.path) ? ref.path : resolve(dirname(ref.configPath), ref.path)
     const installed = readInstalledPluginVersion(absolute)
     if (!installed) continue
@@ -1442,21 +1514,29 @@ export function checkPluginVersionDrift(args) {
  * The V2 contract is the PLURAL `plugins` key; V1 is the singular `plugin` key.
  * So the key alone is not the test — a config can legitimately carry a
  * third-party entry in `plugins`. What identifies the generation is a Pantheon
- * V2 entry inside it. Matched on the `plugin-v2` marker so all three real
- * spellings are recognised: the canonical DIRECTORY (`src/plugin-v2`), an
- * absolute path to it, and the package export (`pantheon-opencode/plugin-v2`).
+ * V2 entry inside it. Recognises the canonical directory, an absolute path,
+ * the package subpath export, and the version-pinned package-root entry emitted
+ * by the installer. The exact package name is checked to avoid matching
+ * similarly named third-party plugins.
  *
  * @param {unknown} ref
  * @returns {boolean}
  */
 function isV2PluginRef(ref) {
-  const candidate =
+  const candidates =
     typeof ref === 'string'
-      ? ref
+      ? [ref]
       : ref && typeof ref === 'object'
-        ? (ref.path ?? ref.source ?? ref.id ?? ref.name)
-        : undefined
-  return typeof candidate === 'string' && candidate.includes('plugin-v2')
+        ? ['package', 'path', 'source', 'id', 'name']
+            .map((key) => ref[key])
+            .filter((value) => typeof value === 'string')
+        : []
+  return candidates.some(
+    (candidate) =>
+      candidate.includes('plugin-v2') ||
+      candidate === PANTHEON_PACKAGE_NAME ||
+      candidate.startsWith(`${PANTHEON_PACKAGE_NAME}@`),
+  )
 }
 
 /**
@@ -1832,7 +1912,9 @@ export function classifyNodeSqliteProbe(probe) {
   if (probe.available) {
     return {
       status: 'ok',
-      message: `node:sqlite available on ${probe.version} — pantheon_cost read-only backend supported`,
+      message:
+        `node:sqlite available on ${probe.version} — read-only SQLite backend prerequisite satisfied; ` +
+        'doctor does not verify pantheon_cost tool registration',
     }
   }
   return {

package/scripts/install/agents-md.mjs

@@ -2,7 +2,7 @@
 /**
  * agents-md.mjs — Dynamic AGENTS.md generator from canonical agent frontmatter
  *
- * Reads all agents/*.agent.md files, extracts name + description from frontmatter,
+ * Reads all canonical src/agents/*.md files, extracts name + description from frontmatter,
  * and generates AGENTS.md content dynamically. Eliminates hardcoded agent tables
  * in platform installers (claude.mjs, cursor.mjs, windsurf.mjs, cline.mjs, etc.).
  *
@@ -64,7 +64,7 @@ function parseAgentFrontmatter(content) {
 // ---------------------------------------------------------------------------
 
 /**
- * Read all canonical agents/*.agent.md files, parse frontmatter,
+ * Read all canonical src/agents/*.md files, parse frontmatter,
  * and return an array of agent metadata objects sorted alphabetically by name.
  *
  * Skips files that don't match the `*.agent.md` pattern, files without