pantheon-opencode 1.3.4 → 1.3.5-beta.57.2e03676

package/README.md

@@ -183,6 +183,39 @@ export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 opencode
 ```
 
+### OpenCode V1/V2 — Dual Version
+
+Pantheon's shared config is **V1-shaped and valid under both OpenCode versions**:
+
+| | V1 | V2 (beta) |
+|---|---|---|
+| Binary | `opencode` (1.18.18) | `opencode2` (v0.0.0-next-17444) |
+| Config locations | `~/.config/opencode/`, `<project>/opencode.json`, `.opencode/` | Same — V2 reads the same locations |
+| Config handling | Loads V1 shape directly | Normalizes V1 fields **in memory** — no rewrite, no native V2 conversion |
+| State DB | `~/.local/share/opencode/opencode.db` | `~/.local/share/opencode/opencode-v2.db` (isolated via `OPENCODE_DB`) |
+| Service port | 49374 | 49375 (must differ from V1) |
+
+The `pantheon_cost` report preserves the V1 database default. Set
+`PANTHEON_OPENCODE_VERSION=v1` or `v2` to select the corresponding state DB
+explicitly (`opencode.db` or `opencode-v2.db`). For custom installations,
+`PANTHEON_COST_DB=/absolute/path/to/opencode.db` takes precedence over the
+version selector; an explicit `dbPath` supplied by the tool caller takes
+precedence over both. The resolver never probes the other version's database,
+and reports an actionable error when the selected DB is missing or has an
+incompatible schema.
+
+**What changed for V2 compatibility (Phase 3):**
+
+- `subagent_depth` moved from top-level to `experimental.subagent_depth` — V2 silently ignores the top-level key. The installer migrates existing configs automatically.
+- Instruction content consolidated into `AGENTS.md` (generated by `scripts/build-agents-md.mjs` from `src/instructions/*.instructions.md`) — V2 accepts but does **not** load the `instructions` config key; both versions auto-load `AGENTS.md`.
+- `npx pantheon-opencode init --version v2` labels an install for V2 (informational — the config is shared).
+
+**Known V2 beta gaps:**
+
+- `instructions` config key accepted but not loaded → content lives in `AGENTS.md`.
+- `formatter` / `lsp` config not executed.
+- `--subtask` delegation flag is a no-op.
+
 ### Background Delegation
 
 Zeus (and other root sessions) can dispatch agents as **background child sessions**
@@ -221,6 +254,25 @@ transition.
 **Timeout:** `background_delegation.timeout_ms` (default `900000` = 15 min). A job
 that has not reached a terminal state is finalized as `error`/`timedOut`.
 
+**Runtime delegation environment variables:**
+
+| Variable | Default | Scope and behavior |
+|---|---:|---|
+| `PANTHEON_ATHENA_APOLLO_BUDGET` | `5` dispatches | In-memory per `createDelegationTools()` factory/process instance and parent session, for the `athena → apollo` read-only exception. |
+| `PANTHEON_HERMES_APOLLO_BUDGET` | `5` dispatches | In-memory per `createDelegationTools()` factory/process instance and parent session, for the `hermes → apollo` read-only exception. |
+| `PANTHEON_DELEGATION_TIMEOUT_MS` | `900000` ms (15 min) | Per delegated child wall-clock timeout. The value is read when the plugin factory is created; unset or invalid values use the default. |
+
+Budgets are reserved before asynchronous child-session creation, so real
+concurrent calls cannot overshoot them. They reset when the factory/process
+restarts. If `ToolContext.agent` is missing, the default runtime matrix rejects
+the delegation (fail-closed); no caller identity or budget is inferred from the
+target, prompt, or session state. An explicitly legacy host using
+`enforceRuntimeMatrix: false` skips the budget because the caller cannot be
+identified and emits a warning. These budgets are separate from
+`background_delegation.max_concurrent_per_agent`: concurrency limits the number
+of currently running children, while an exception budget limits total dispatch
+reservations for that parent session during the factory lifetime.
+
 **Read-only enforcement:** delegating with `read_only: true`, or delegating to an
 agent in `background_delegation.read_only_agents` (`apollo`, `gaia`), registers
 the child session as read-only — the `tool.execute.before` guard denies
@@ -853,9 +905,18 @@ to Mnemosyne so counts stay accurate and consistent.
 
 ### What CI enforces automatically
 
-`release.yml` validates version consistency across all manifests (`package.json`,
-`plugin.json`, `CHANGELOG.md`, and the README badge) before publishing. If they diverge,
-the release is blocked until Mnemosyne reconciles them.
+`release.yml` validates version consistency across the package manifests
+(`package.json`, `plugin.json`, `pyproject.toml`, and the TUI package) before
+publishing. If they diverge, the release is blocked until they are reconciled.
+
+Beta releases are calculated from npm's published `latest` at workflow runtime:
+the default is the next patch, formatted as
+`<next-stable>-beta.<PR>.<short-sha>`. Only the exact `release:beta` label
+triggers this path; alternate label variants do not trigger it. Beta recovery
+requires an explicit `workflow_dispatch` with its recovery inputs; a normal
+push does not republish beta. The workflow owns the manifest update, tag, and
+publish, creates the GitHub Release as `Pantheon <version>`, and does not create
+PR comments.
 
 ### Anti-patterns
 

package/bin/pantheon-init.mjs

@@ -6,6 +6,13 @@
  *
  * Thin CLI wrapper that parses arguments and delegates to
  * installOpenCode() from scripts/install/opencode.mjs.
+ *
+ * Dual-version install (Phase 3): the generated config is V1-shaped and valid
+ * under BOTH OpenCode V1 (`opencode` 1.18.x) and V2 (`opencode2`
+ * v0.0.0-next-17444). V2 reads the same config locations and normalizes V1
+ * fields in memory — no native V2 conversion. `--version v2` labels the
+ * install for the operator; state isolation is a runtime concern
+ * (OPENCODE_DB ~/.local/share/opencode/opencode-v2.db, service port 49375).
  */
 import fs from 'fs'
 import os from 'os'
@@ -43,6 +50,7 @@ function printUsage() {
   console.log('  npx pantheon-opencode init --interactive  # Force interactive TUI mode')
   console.log('  npx pantheon-opencode init --headless     # Force non-interactive mode')
   console.log('  npx pantheon-opencode init -y             # Skip confirmations, use defaults')
+  console.log('  npx pantheon-opencode init --version v2    # Label install for OpenCode V2 (beta)')
   console.log('  npx pantheon-opencode init --preset <name> # Install and activate model preset')
   console.log('  npx pantheon-opencode set-tier <name>      # Set active model preset (global)')
   console.log(
@@ -182,6 +190,14 @@ async function main() {
     const autoYes = args.includes('--yes') || args.includes('-y')
     const presetIndex = args.indexOf('--preset')
     const presetOpt = presetIndex >= 0 ? (args[presetIndex + 1] ?? null) : null
+    // --version v1|v2 labels the install target (informational; the config is
+    // shared and V1-shaped under both versions). Invalid values fail fast.
+    const versionIndex = args.indexOf('--version')
+    const versionOpt = versionIndex >= 0 ? (args[versionIndex + 1] ?? null) : null
+    if (versionOpt !== null && versionOpt !== 'v1' && versionOpt !== 'v2') {
+      console.error(`❌ Invalid --version "${versionOpt}" — expected v1 or v2`)
+      process.exit(1)
+    }
 
     const components = ['agents', 'skills', 'instructions', 'commands', 'plugins']
     if (!skipMCP) components.push('runtime')
@@ -203,6 +219,7 @@ async function main() {
         headless: forceHeadless,
         yes: autoYes,
         preset: presetOpt,
+        version: versionOpt ?? 'v1',
       })
     } catch (err) {
       console.error(

package/opencode.json

@@ -11,7 +11,9 @@
     }
   },
   "default_agent": "zeus",
-  "subagent_depth": 2,
+  "experimental": {
+    "subagent_depth": 2
+  },
   "model": "opencode-go/deepseek-v4-flash",
   "small_model": "opencode-go/deepseek-v4-flash",
   "permission": {
@@ -28,7 +30,6 @@
       "pip *": "allow"
     }
   },
-  "instructions": ["AGENTS.md", "src/instructions/*.instructions.md"],
   "mcp": {
     "bifrost": {
       "type": "remote",
@@ -37,15 +38,6 @@
     }
   },
   "agent": {
-    "athena": {
-      "model": "opencode-go/kimi-k3"
-    },
-    "themis": {
-      "model": "opencode-go/deepseek-v4-pro"
-    },
-    "hephaestus": {
-      "model": "opencode-go/deepseek-v4-pro"
-    },
     "talos": {
       "permission": {
         "edit": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.3.4",
+  "version": "1.3.5-beta.57.2e03676",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
@@ -10,6 +10,7 @@
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "husky",
     "setup": "node bin/pantheon-init.mjs init",
+    "build:agents-md": "node scripts/build-agents-md.mjs",
     "setup:lite": "node bin/pantheon-init.mjs init --clean --components agents,skills,instructions",
     "doctor": "node scripts/doctor.mjs",
     "prune": "node scripts/prune.mjs",

package/scripts/build-agents-md.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * build-agents-md.mjs — Generate the repo AGENTS.md from canonical sources.
+ *
+ * AGENTS.md is the single instruction file BOTH OpenCode V1 and V2 load
+ * (V1 auto-discovers it, V2 loads it explicitly; the `instructions` config
+ * key is accepted-but-ignored by V2). To keep instruction content in parity
+ * 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)
+ *
+ * into one generated AGENTS.md. src/instructions/*.instructions.md remains
+ * the source of truth — AGENTS.md is a committed build artifact, never
+ * hand-edited.
+ *
+ * Usage:
+ *   node scripts/build-agents-md.mjs            # write AGENTS.md to repo root
+ *   node scripts/build-agents-md.mjs --check    # exit 1 if AGENTS.md is stale
+ *
+ * No runtime dependencies (Node >= 18, stdlib only). Idempotent: running it
+ * twice produces byte-identical output.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const ROOT = join(__dirname, '..')
+const INSTRUCTIONS_DIR = join(ROOT, 'src', 'instructions')
+const AGENTS_MD_PATH = join(ROOT, 'AGENTS.md')
+
+// ---------------------------------------------------------------------------
+// Static header — preserved verbatim from the original AGENTS.md (agent table,
+// setup notes, sandbox rules, conventions). Backticks are escaped for the
+// template literal.
+// ---------------------------------------------------------------------------
+const STATIC_HEADER = `# Pantheon Agent System — OpenCode
+
+This project uses the Pantheon multi-agent framework with 14 specialized agents.
+
+## Available 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. |
+| @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. |
+| @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. |
+| @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. |
+| @zeus | Central orchestrator — never implements. Delegates to: athena, apollo, hermes, aphrodite, demeter, prometheus, themis, iris, mnemosyne, talos, hephaestus, nyx |
+
+## OpenCode Setup
+
+See [INSTALLATION.md](docs/INSTALLATION.md) for setup instructions.
+
+- Build: \`npm test\`
+- Test: \`npm test\`
+- Lint: \`npm run lint\`
+
+## Teste de Instalação Global (sandbox)
+
+Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO REAL, use o sandbox isolado em \`~/pantheon-sandbox/\` (fora do repo, HOME + prefix npm + venv próprios). O ambiente de dev mistura 3 instalações + config global + venv — NÃO serve para testar instalação/empacotamento.
+
+- 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\`
+
+## Conventions
+
+- TDD: Write failing test first, then implement
+- Coverage minimum: 80%
+- 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.
+`
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing (stdlib only — no yaml dependency)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ *
+ * @param {string} content - Raw file content
+ * @returns {{ name: string, body: string } | null}
+ */
+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
+  return {
+    name: nameMatch[1].trim(),
+    body: content.slice(match[0].length).trimEnd() + '\n',
+  }
+}
+
+/**
+ * Read all src/instructions/*.instructions.md files, sorted by filename for
+ * deterministic output.
+ *
+ * @returns {Array<{ file: string, name: string, body: string }>}
+ */
+export function readInstructions() {
+  if (!existsSync(INSTRUCTIONS_DIR)) return []
+  const files = readdirSync(INSTRUCTIONS_DIR)
+    .filter((f) => f.endsWith('.instructions.md'))
+    .sort()
+  const out = []
+  for (const file of files) {
+    const content = readFileSync(join(INSTRUCTIONS_DIR, file), 'utf8')
+    const parsed = parseInstruction(content)
+    if (parsed) out.push({ file, ...parsed })
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate the full AGENTS.md content.
+ *
+ * @param {Array<{ file: string, name: string, body: string }>} instructions
+ * @returns {string}
+ */
+export function generateAgentsMd(instructions) {
+  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). -->',
+    '',
+    STATIC_HEADER.trimEnd(),
+    '',
+    '---',
+    '',
+    '# Agent 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.',
+    '',
+  ]
+  for (const instr of instructions) {
+    sections.push(
+      `<!-- Source: src/instructions/${instr.file} -->`,
+      `## ${instr.name}`,
+      '',
+      instr.body.trimEnd(),
+      '',
+    )
+  }
+  return sections.join('\n').trimEnd() + '\n'
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+function main() {
+  const checkOnly = process.argv.includes('--check')
+  const instructions = readInstructions()
+  const content = generateAgentsMd(instructions)
+
+  if (checkOnly) {
+    const existing = existsSync(AGENTS_MD_PATH) ? readFileSync(AGENTS_MD_PATH, 'utf8') : ''
+    if (existing !== content) {
+      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)`)
+    return
+  }
+
+  writeFileSync(AGENTS_MD_PATH, content, 'utf8')
+  const lines = content.split('\n').length
+  console.log(`✅ Generated AGENTS.md (${instructions.length} instruction sections, ${lines} lines)`)
+}
+
+main()

package/scripts/cost.mjs

@@ -26,6 +26,22 @@ function fail(message) {
   process.exitCode = 1
 }
 
+function assertCompatibleSchema(db) {
+  const table = db
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'message'")
+    .get()
+  if (!table)
+    throw new Error('incompatible opencode.db schema: required "message" table is missing')
+  const columns = db.prepare('PRAGMA table_info(message)').all()
+  const names = new Set(columns.map((column) => column.name))
+  const missing = ['data', 'time_created'].filter((name) => !names.has(name))
+  if (missing.length > 0) {
+    throw new Error(
+      `incompatible opencode.db schema: message table is missing ${missing.join(', ')}; select the matching V1/V2 database`,
+    )
+  }
+}
+
 function main() {
   const [, , dbPath, daysArg] = process.argv
   const days = Number(daysArg ?? '7')
@@ -35,6 +51,7 @@ function main() {
 
   try {
     const db = new DatabaseSync(dbPath, { readOnly: true })
+    assertCompatibleSchema(db)
     const since = Date.now() - days * 86_400_000
     const rows = db.prepare('SELECT data FROM message WHERE time_created >= ?').all(since)
     db.close()

package/scripts/doctor.mjs

@@ -757,7 +757,7 @@ function checkPermissionMismatches(args) {
 // Check D: Sync Status
 // ---------------------------------------------------------------------------
 
-function checkSyncStatus(args) {
+function checkSyncStatus(_args) {
   section('D. Sync Status')
 
   // Platform sync removed in v1.0 (OpenCode-only)
@@ -979,9 +979,207 @@ function checkVenvLayer(args) {
 }
 
 // ---------------------------------------------------------------------------
-// Summary
+// Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
 
+/**
+ * Check AGENTS.md only where the repository's generator can provide a real
+ * source-of-truth comparison. Installed targets have no canonical instruction
+ * sources available to this process, so their freshness is deliberately not
+ * guessed from file age.
+ */
+function checkAgentsMdFreshness(args) {
+  section('G. AGENTS.md Freshness')
+
+  const agentsMdPath = join(args.target, 'AGENTS.md')
+  if (args.target !== ROOT) {
+    const outcome = classifyAgentsMdFreshness({
+      targetIsRoot: false,
+      agentsMdExists: existsSync(agentsMdPath),
+      generatorExists: false,
+    })
+    if (outcome === 'unverified') {
+      info(
+        'AGENTS.md is present; freshness was not checked because the canonical generator sources are not available in an installed target',
+      )
+    } else {
+      warn(
+        'AGENTS.md is not present; freshness cannot be verified for this installed target — run `pantheon-opencode init --components instructions`',
+      )
+    }
+    return
+  }
+
+  const generator = join(ROOT, 'scripts', 'build-agents-md.mjs')
+  if (!existsSync(generator)) {
+    info('AGENTS.md freshness skipped — canonical generator is not available')
+    return
+  }
+
+  const result = spawn(process.execPath, [generator, '--check'], ROOT)
+  const outcome = classifyAgentsMdFreshness({
+    targetIsRoot: true,
+    agentsMdExists: existsSync(agentsMdPath),
+    generatorExists: true,
+    generatorStatus: result.status,
+  })
+  if (outcome === 'pass') {
+    pass('AGENTS.md matches the canonical generated instructions')
+  } else if (outcome === 'unverified' && !existsSync(agentsMdPath)) {
+    warn(
+      'AGENTS.md is missing — run `node scripts/build-agents-md.mjs` or `pantheon-opencode init`',
+    )
+  } else if (outcome === 'stale') {
+    warn('AGENTS.md is stale — run `node scripts/build-agents-md.mjs` to refresh it')
+  } else {
+    warn(
+      `AGENTS.md freshness could not be verified (generator exited ${result.status ?? 'unknown'})`,
+    )
+  }
+}
+
+/**
+ * Classify the generator result without relying on timestamps or fragile
+ * process mocks. The doctor CLI uses the same result contract internally.
+ *
+ * @param {{ targetIsRoot: boolean; agentsMdExists: boolean; generatorExists: boolean; generatorStatus?: number | null }} input
+ * @returns {'pass' | 'missing' | 'stale' | 'skipped' | 'unverified'}
+ */
+export function classifyAgentsMdFreshness(input) {
+  if (!input.targetIsRoot) return input.agentsMdExists ? 'unverified' : 'missing'
+  if (!input.generatorExists) return 'skipped'
+  if (input.generatorStatus === 0) return 'pass'
+  if (input.generatorStatus === 1 && input.agentsMdExists) return 'stale'
+  return 'unverified'
+}
+
+// ---------------------------------------------------------------------------
+// Check H: Config migration — no top-level subagent_depth
+// ---------------------------------------------------------------------------
+
+function checkSubagentDepthPlacement(args) {
+  section('H. Config Migration')
+
+  const configs = collectMcpConfigs(args)
+  if (configs.length === 0) {
+    info('subagent_depth placement check skipped — no opencode.json was found')
+    return
+  }
+  for (const cfg of configs) {
+    if (cfg.data.subagent_depth !== undefined) {
+      error(
+        `${cfg.label}: top-level "subagent_depth" is unsupported — run \`pantheon-opencode init\` to migrate it to "experimental.subagent_depth"`,
+      )
+    } else if (
+      cfg.data.experimental &&
+      typeof cfg.data.experimental === 'object' &&
+      cfg.data.experimental.subagent_depth !== undefined
+    ) {
+      pass(`${cfg.label}: experimental.subagent_depth = ${cfg.data.experimental.subagent_depth}`)
+    } else {
+      info(
+        `${cfg.label}: experimental.subagent_depth is not configured (older/custom config may omit it)`,
+      )
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check J: Agent permission.task presence
+// ---------------------------------------------------------------------------
+
+/** @param {string} content @returns {boolean} */
+export function hasPermissionTask(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return false
+  const permission = match[1].match(/(?:^|\r?\n)permission:\s*\r?\n([\s\S]*?)(?=\r?\n\S|$)/)
+  return Boolean(permission && /^\s+task:\s*/m.test(permission[1]))
+}
+
+/**
+ * Derive installed agent files from the paths already declared by configs.
+ * This supports both global flat and project .opencode layouts without
+ * assuming a user home directory.
+ *
+ * @param {{path: string, data: object}[]} configs
+ * @returns {string[]}
+ */
+export function deriveInstalledAgentFiles(configs) {
+  const directories = new Set()
+  for (const cfg of configs) {
+    for (const agent of Object.values(cfg.data.agent ?? {})) {
+      const source = agent && typeof agent === 'object' ? agent.source : undefined
+      if (typeof source !== 'string' || !source.includes('/')) continue
+      const filePath = resolve(dirname(cfg.path), source)
+      if (filePath.startsWith(`${AGENTS_DIR}/`)) continue
+      if (existsSync(filePath)) directories.add(dirname(filePath))
+    }
+  }
+
+  const files = []
+  for (const directory of directories) {
+    let entries
+    try {
+      entries = readdirSync(directory, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.md')) files.push(join(directory, entry.name))
+    }
+  }
+  return [...new Set(files)].sort()
+}
+
+function checkPermissionTaskPresence(args) {
+  section('J. Installed Agent permission.task')
+
+  if (args.profile === 'lite') {
+    info(
+      'Installed agent permission.task check skipped (lite profile does not require managed agents)',
+    )
+    return
+  }
+
+  const installedFiles = deriveInstalledAgentFiles(collectMcpConfigs(args))
+  if (installedFiles.length === 0) {
+    info(
+      'Installed agent permission.task check skipped — no agent source directory could be derived from available config',
+    )
+    return
+  }
+
+  const missing = findMissingPermissionTask(installedFiles)
+  if (classifyPermissionTaskCheck(args.profile, installedFiles.length, missing.length) === 'pass') {
+    pass(`All ${installedFiles.length} installed agents have permission.task`)
+    return
+  }
+
+  for (const filePath of missing) {
+    error(
+      `${basename(filePath)}: missing permission.task in managed agent — run \`pantheon-opencode init\` to update installed agents`,
+    )
+  }
+}
+
+/** @param {string[]} filePaths @returns {string[]} */
+export function findMissingPermissionTask(filePaths) {
+  return filePaths.filter((filePath) => !hasPermissionTask(readFileSync(filePath, 'utf8')))
+}
+
+/**
+ * Classify the installed-agent permission.task layer for a doctor profile.
+ *
+ * @param {string} profile
+ * @param {number} installedCount
+ * @param {number} missingCount
+ * @returns {'skip' | 'pass' | 'error'}
+ */
+export function classifyPermissionTaskCheck(profile, installedCount, missingCount) {
+  if (profile === 'lite' || installedCount === 0) return 'skip'
+  return missingCount === 0 ? 'pass' : 'error'
+}
+
 /**
  * Return the final doctor status message without masking blocking errors.
  * @param {{ error: number; warn: number }} summaryCounts
@@ -1069,6 +1267,9 @@ async function main() {
   checkPermissionMismatches(args)
   checkSyncStatus(args)
   checkGitStatus(args)
+  checkAgentsMdFreshness(args)
+  checkSubagentDepthPlacement(args)
+  checkPermissionTaskPresence(args)
 
   printSummary(args.target)