pantheon-opencode 2.1.2 → 2.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/AGENTS.global.md +7 -7
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +77 -0
  4. package/README.md +10 -0
  5. package/package.json +7 -4
  6. package/plugin.json +1 -1
  7. package/pyproject.toml +1 -1
  8. package/scripts/build-plugin.mjs +35 -9
  9. package/scripts/build-roster.mjs +139 -0
  10. package/scripts/doctor.mjs +111 -2
  11. package/scripts/install/opencode.mjs +16 -0
  12. package/scripts/sync-tui.mjs +2 -0
  13. package/scripts/test-slice.mjs +352 -0
  14. package/skills-lock.json +1 -1
  15. package/src/agents/aphrodite.md +8 -6
  16. package/src/agents/apollo.md +9 -7
  17. package/src/agents/athena.md +21 -18
  18. package/src/agents/demeter.md +7 -5
  19. package/src/agents/gaia.md +7 -8
  20. package/src/agents/hephaestus.md +7 -5
  21. package/src/agents/hermes.md +20 -16
  22. package/src/agents/iris.md +10 -8
  23. package/src/agents/mnemosyne.md +17 -19
  24. package/src/agents/nyx.md +7 -5
  25. package/src/agents/prometheus.md +7 -5
  26. package/src/agents/talos.md +11 -5
  27. package/src/agents/themis.md +11 -4
  28. package/src/agents/zeus.md +23 -2
  29. package/src/instructions/agent-return-format.instructions.md +1 -1
  30. package/src/instructions/test-economy.instructions.md +6 -6
  31. package/src/mcp/pantheon_vision.py +24 -0
  32. package/src/pantheon/auto-permissions.ts +328 -0
  33. package/src/pantheon/deepwork/deepwork-tool.ts +14 -0
  34. package/src/pantheon/delegation-enforce.ts +43 -12
  35. package/src/pantheon/native-vision.ts +54 -2
  36. package/src/pantheon/tools.ts +102 -3
  37. package/src/plugin/index.js +342 -16
  38. package/src/plugin.ts +7 -0
  39. package/src/plugins/tui/dist/tui.js +5 -5
  40. package/src/plugins/tui/package-lock.json +2 -2
  41. package/src/plugins/tui/package.json +1 -1
  42. package/src/skills/test-slicing/SKILL.md +44 -15
package/AGENTS.global.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
2
2
  <!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
3
3
  <!-- Source of truth: src/instructions/*.instructions.md + the static sections in this script. -->
4
- <!-- pantheon:agents-md v2 artifact=global generated-at=2026-11-13T10:55:59-03:00 sha=7d3bb91 -->
4
+ <!-- pantheon:agents-md v2 artifact=global generated-at=2026-11-14T10:35:21-03:00 sha=0200775 -->
5
5
 
6
6
  # Pantheon Agent System — OpenCode
7
7
 
@@ -37,7 +37,7 @@ All agents check each result against the request and evidence; remove unrelated
37
37
  ## subtask_summary
38
38
  **files_changed:** [list of file paths, one per line]
39
39
  **summary:** What was done, in 2-3 sentences
40
- **tests:** [PASS] All passing / [WARN] X failing / [FAIL] Not run (reason)
40
+ **tests:** [PASS | WARN | FAIL] `<command>` (targets: N, duration: <X>s, selection: <reason>)
41
41
  **coverage:** X% (if applicable)
42
42
  **tokens:** ~N input / ~M output (estimated)
43
43
  **status:** complete | partial (reason) | escalated (reason)
@@ -90,11 +90,11 @@ Required: position, reasoning, trade_offs, risks, confidence. Optional `agreemen
90
90
 
91
91
  Write one focused test per behavior; do not duplicate coverage.
92
92
 
93
- - Prefer unit/integration checks; use E2E, install, or network tests only when a change affects that path.
94
- - Avoid assertions on copy/formatting or tests that merely restate the implementation.
95
- - Default to focused tests; run the full suite only for scope, risk, or CI/release gates. Bug fixes need one regression test unless existing coverage catches them.
96
- - Test slicing: In dev loops, run ONLY the test slice for the changed file (`node --test tests/foo.test.mjs`, `pytest -k <func>`); avoid full suites.
97
- - Keep slow install/E2E suites opt-in, never per edit or phase; reserve them for release gates.
93
+ - **Test Slicing**: In dev loops, run ONLY the narrowest slice (<10s) for changed code (`node --test <slice>`, `pytest -k`); avoid unconstrained suites.
94
+ - **Repo Selector & Receipt**: Prefer repo selectors (`test:quick`, `test:slice`); record command, targets, duration, and selection reason in `subtask_summary`.
95
+ - **Failure/Fix Loops**: Rerun ONLY failed checks; never rerun passing tests without code changes.
96
+ - **Mapping Gaps**: If a file lacks tests, run static check fallback plus nearest slice.
97
+ - Slow install/E2E suites are opt-in, never per edit; reserve for release gates.
98
98
  - Test economy does NOT weaken stronger gates: auth, security, data-integrity, and required coverage.
99
99
 
100
100
  <!-- Source: src/instructions/yagni.instructions.md -->
package/AGENTS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
2
2
  <!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
3
3
  <!-- Source of truth: project sections in scripts/build-agents-md.mjs. -->
4
- <!-- pantheon:agents-md v2 artifact=project generated-at=2026-11-13T10:55:59-03:00 sha=7d3bb91 -->
4
+ <!-- pantheon:agents-md v2 artifact=project generated-at=2026-11-14T10:35:21-03:00 sha=0200775 -->
5
5
 
6
6
  # Pantheon — Repository Setup
7
7
 
package/CHANGELOG.md CHANGED
@@ -13,6 +13,59 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
13
13
  `node scripts/versioning.mjs apply --notes` pre-fills the generated sections from conventional commits.
14
14
  Running apply will move this section to a versioned entry and reset the template below. -->
15
15
 
16
+ ## [v2.1.4] - 2026-11-14
17
+
18
+ ### 🆕 What's New
19
+
20
+ - **Global Install Shadowing (#424)**: Doctor check (H2b) detects multiple global binaries, dangling symlinks, and prefix skew.
21
+ - **Strict Test Slice Ordering (#442)**: Fixed `--test-name-pattern` flag ordering in `test:slice` so regex filters work during fix loops.
22
+ - **Security Boundaries (#441)**: Hardened `auto-permissions` and `zeusReadGuard` to exclude `.git/` and `node_modules/` from reads.
23
+ - **Universal Session Todos (#439)**: Granted `todowrite` and `todoread` across all 14 specialist agent manifests.
24
+ - **Session Auto-Discovery (#440)**: Automated active session discovery from environment and SQLite `opencode.db` for vision.
25
+
26
+ ### Fixed
27
+
28
+ - **install (#424)** — added doctor check (H2b) for PATH shadowing, version skew check in `resolveStablePantheonRoot`, and sanitized npm env in `sync-tui.mjs`.
29
+ - **tests (#442)** — reordered `--test-name-pattern` before test path in `scripts/test-slice.mjs` so Node's test runner enforces filters during fix loops.
30
+ - **security (#441)** — enforced deterministic path checks in `auto-permissions.ts` and `zeusReadGuard` denying `.git/**`, `node_modules/**`, and traversal.
31
+ - **tools (#439)** — granted `todowrite` and `todoread` across all 14 specialist agent manifests in `src/agents/roster.json` and registered tool capabilities.
32
+ - **vision (#440)** — automated session ID resolution from `OPENCODE_SESSION_ID` and SQLite `opencode.db` (`session_v2`) for `vision_describe`.
33
+
34
+ ### ✅ Closed Issues
35
+
36
+ - #424 - detect and prevent global install shadowing and prefix version skew
37
+ - #439 - expose todowrite and todoread across specialist agents
38
+ - #440 - auto-discover OpenCode session ID for vision_describe
39
+ - #441 - enforce .git and node_modules exclusion in auto-permissions and guards
40
+ - #442 - reorder test-name-pattern filter before file path in test:slice
41
+
42
+ ## [v2.1.3] - 2026-11-14
43
+
44
+ ### 🆕 What's New
45
+
46
+ - **Enforceable Test Slicing (#437)**: Added `test:slice` with selector discovery, duration tracking, and loop interception.
47
+ - **Workspace Auto-Permissions**: Scope governance auto-approves safe commands while preserving strict security boundaries.
48
+ - **Complete Todo Suite**: Activated `todoread` alongside `todowrite` with real-time TUI sidebar synchronization.
49
+ - **Declarative Agent Roster**: Centralized manifest `src/agents/roster.json` mechanically compiling all 14 specialist prompts.
50
+ - **Runtime Bug Fixes**: Added `shell` tool alias for OpenCode `bash` and removed wildcard restrictions in `zeusReadGuard`.
51
+
52
+ ### Added
53
+
54
+ - **skills** — upgraded `test-slicing` skill with repo-first selector discovery, scope escalation protocol, failure/fix loop rules, and observable task receipts.
55
+ - **scripts** — added `scripts/test-slice.mjs` CLI (`npm run test:slice`) and `scripts/build-roster.mjs` compiler (`npm run build:roster`, `npm run check:roster`).
56
+ - **pantheon** — added `shell` execution tool alias and `todoread` session tool with status filtering in `src/pantheon/tools.ts`.
57
+ - **auto-permissions** — added `src/pantheon/auto-permissions.ts` with unconstrained test suite interception (`isUnconstrainedTestSuite`).
58
+
59
+ ### Changed
60
+
61
+ - **agents** — synchronized all 14 agent prompts from typed `src/agents/roster.json` manifest.
62
+ - **instructions** — updated `test-economy.instructions.md` and `agent-return-format.instructions.md` to require observable test execution receipts.
63
+ - **roadmap** — updated `ROADMAP.md` reflecting 2.1.3 active deliveries and 2.2.0 horizons.
64
+
65
+ ### Fixed
66
+
67
+ - **tools** — added `shell` tool alias in V2 tools to eliminate `No tool named "shell" is currently available`.
68
+ - **guards** — replaced `hasGlobMeta` with semantic `isDeniedGlobPattern` in `zeusReadGuard` to allow `glob("*")` and `glob("**/package.json")` while strictly defending code roots.
16
69
  ## [v2.1.2] - 2026-11-14
17
70
 
18
71
  ### 🆕 What's New
@@ -227,6 +280,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
227
280
 
228
281
  ## [Unreleased]
229
282
 
283
+ ### 🆕 What's New
284
+
285
+ - **Global Install Shadowing (#424)**: Doctor check (H2b) detects multiple global binaries, dangling symlinks, and prefix skew.
286
+ - **Strict Test Slice Ordering (#442)**: Fixed `--test-name-pattern` flag ordering in `test:slice` so regex filters work during fix loops.
287
+ - **Security Boundaries (#441)**: Hardened `auto-permissions` and `zeusReadGuard` to exclude `.git/` and `node_modules/` from reads.
288
+ - **Universal Session Todos (#439)**: Granted `todowrite` and `todoread` across all 14 specialist agent manifests.
289
+ - **Session Auto-Discovery (#440)**: Automated active session discovery from environment and SQLite `opencode.db` for vision.
290
+
291
+ ### Fixed
292
+
293
+ - **install (#424)** — added doctor check (H2b) for PATH shadowing, version skew check in `resolveStablePantheonRoot`, and sanitized npm env in `sync-tui.mjs`.
294
+ - **tests (#442)** — reordered `--test-name-pattern` before test path in `scripts/test-slice.mjs` so Node's test runner enforces filters during fix loops.
295
+ - **security (#441)** — enforced deterministic path checks in `auto-permissions.ts` and `zeusReadGuard` denying `.git/**`, `node_modules/**`, and traversal.
296
+ - **tools (#439)** — granted `todowrite` and `todoread` across all 14 specialist agent manifests in `src/agents/roster.json` and registered tool capabilities.
297
+ - **vision (#440)** — automated session ID resolution from `OPENCODE_SESSION_ID` and SQLite `opencode.db` (`session_v2`) for `vision_describe`.
298
+
299
+ ### ✅ Closed Issues
300
+
301
+ - #424 - detect and prevent global install shadowing and prefix version skew
302
+ - #439 - expose todowrite and todoread across specialist agents
303
+ - #440 - auto-discover OpenCode session ID for vision_describe
304
+ - #441 - enforce .git and node_modules exclusion in auto-permissions and guards
305
+ - #442 - reorder test-name-pattern filter before file path in test:slice
306
+
230
307
  <!-- Add new changes here.
231
308
  Canonical sections (docs/RELEASING.md): ### 🆕 What's New (curated highlights, ≤6 bullets ≤140 chars) →
232
309
  ### Added / Changed / Deprecated / Removed / Fixed / Security → ### ⚠️ Known Issues / ### ✅ Closed Issues.
package/README.md CHANGED
@@ -225,6 +225,16 @@ Working runnable reference projects demonstrating Pantheon orchestration in prac
225
225
 
226
226
  ---
227
227
 
228
+ ## What's New in v2.1.4
229
+
230
+ - **Global Install Shadowing & PATH Hygiene (#424):** Doctor check (H2b) detects multiple global binaries, dangling symlinks, and prefix skew. Version skew validation prevents `_npx` from binding to older global packages.
231
+ - **Strict Test Slice Ordering (#442):** Reordered `--test-name-pattern` flag ahead of the test file path in `scripts/test-slice.mjs` so Node's native test runner filters tests during failure/fix loops.
232
+ - **Security Boundaries on Internal Folders (#441):** Hardened `auto-permissions` and `zeusReadGuard` to exclude `.git/` and `node_modules/` from autonomous reads.
233
+ - **Universal Session Todo Tool Availability (#439):** Granted `todowrite` and `todoread` across all 14 specialist agent manifests.
234
+ - **Session Auto-Discovery for Zen Vision (#440):** Automated active session discovery from environment (`OPENCODE_SESSION_ID`) and SQLite `opencode.db` (`session_v2`) for `vision_describe`.
235
+
236
+ ---
237
+
228
238
  ## What's New in v2.0.1
229
239
 
230
240
  - **Bilingual TUI Settings (PT-BR / EN):** Visual localization for Decision Router, Autonomy & Budgets, and J1 Safety Gate tabs, with intelligent system locale auto-detection (`LANG` / `LC_ALL`) and manual preference cycling (`auto`, `pt-BR`, `en`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pantheon-opencode",
3
- "version": "2.1.2",
3
+ "version": "2.1.4",
4
4
  "description": "Multi-agent orchestration for OpenCode \u2014 14 specialized agents, TDD, Themis review gates.",
5
5
  "type": "module",
6
6
  "workspaces": [
@@ -19,6 +19,8 @@
19
19
  "prepare": "git rev-parse --is-inside-work-tree >/dev/null 2>&1 && husky",
20
20
  "setup": "node scripts/setup.mjs",
21
21
  "build:agents-md": "node scripts/build-agents-md.mjs",
22
+ "build:roster": "node scripts/build-roster.mjs",
23
+ "check:roster": "node scripts/build-roster.mjs --check",
22
24
  "build:decision-router": "node scripts/build-decision-router.mjs",
23
25
  "build:plugin": "node scripts/build-plugin.mjs",
24
26
  "check:decision-router": "node scripts/build-decision-router.mjs --check",
@@ -29,8 +31,8 @@
29
31
  "init": "node bin/pantheon-init.mjs init --yes",
30
32
  "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
31
33
  "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
32
- "prepack": "npm run build:plugin && npm run check:decision-router",
33
- "prepublishOnly": "node scripts/validate-routing.mjs && npm run build:plugin && npm run check:decision-router",
34
+ "prepack": "npm run build:plugin && npm run check:decision-router && npm run check:roster",
35
+ "prepublishOnly": "node scripts/validate-routing.mjs && npm run build:plugin && npm run check:decision-router && npm run check:roster",
34
36
  "postpublish": "node -e \"console.log('\u2705 Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
35
37
  "version:status": "node scripts/versioning.mjs status",
36
38
  "version:apply": "node scripts/versioning.mjs apply",
@@ -49,7 +51,8 @@
49
51
  "hooks:install": "pre-commit install",
50
52
  "hooks:update": "pre-commit autoupdate",
51
53
  "test:security": "npm run secret-scan",
52
- "test:quick": "node --test tests/skill-decision-proactive.test.mjs tests/plan-visibility-contract.test.mjs tests/proportional-execution-contract.test.mjs tests/memory-delegation-prompt.test.mjs tests/tui-settings-draft.test.mjs tests/tui-settings-i18n.test.mjs",
54
+ "test:quick": "node --test tests/skill-decision-proactive.test.mjs tests/plan-visibility-contract.test.mjs tests/proportional-execution-contract.test.mjs tests/memory-delegation-prompt.test.mjs tests/tui-settings-draft.test.mjs tests/tui-settings-i18n.test.mjs tests/test-slicing-contract.test.mjs",
55
+ "test:slice": "node scripts/test-slice.mjs",
53
56
  "test:node": "node scripts/run-node-tests.mjs --label 'test:node' --exclude 'tests/install-opencode.test.mjs' --exclude 'tests/install-e2e.test.mjs' 'tests/*.mjs' 'tests/pantheon/*.mjs' 'tests/eval/*.mjs'",
54
57
  "test:install": "PANTHEON_RUN_INSTALL_TESTS=1 node scripts/run-node-tests.mjs --label 'test:install' 'tests/install-opencode.test.mjs' 'tests/install-e2e.test.mjs'",
55
58
  "coverage": "echo 'Node coverage (report-only, NO threshold is enforced).' && echo 'Covers: the .mjs/.js modules under scripts/, src/ and bin/ that test:node exercises.' && echo 'Does NOT cover: test:ts (hand-rolled tsx loop, no node --test runner) and test:ci (pytest).' && echo ' TypeScript under src/ (41 files) is therefore entirely unmeasured here.' && echo '' && node scripts/run-node-tests.mjs --label 'coverage' --exclude 'tests/install-opencode.test.mjs' --exclude 'tests/install-e2e.test.mjs' -- --experimental-test-coverage --test-coverage-include='scripts/**/*.mjs' --test-coverage-include='src/**/*.mjs' --test-coverage-include='src/**/*.js' --test-coverage-include='bin/**/*.mjs' 'tests/*.mjs' 'tests/pantheon/*.mjs'",
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pantheon",
3
3
  "publisher": "ils15",
4
- "version": "2.1.2",
4
+ "version": "2.1.4",
5
5
  "displayName": "Pantheon",
6
6
  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 25 skills, and OpenCode support.",
7
7
  "agents": "./src/agents",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
4
4
 
5
5
  [project]
6
6
  name = "pantheon"
7
- version = "2.1.2"
7
+ version = "2.1.4"
8
8
  description = "Multi-agent orchestration framework"
9
9
  requires-python = ">=3.11"
10
10
  # Python sources under src/mcp/ import fastmcp/pydantic at runtime, but those
@@ -7,20 +7,46 @@
7
7
  * without triggering ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING on Node 22+.
8
8
  */
9
9
 
10
+ import { execFileSync } from 'node:child_process'
11
+ import { existsSync } from 'node:fs'
10
12
  import { dirname, join } from 'node:path'
11
13
  import { fileURLToPath } from 'node:url'
12
- import { buildSync } from 'esbuild'
13
14
 
14
15
  const __dirname = dirname(fileURLToPath(import.meta.url))
15
16
  const root = join(__dirname, '..')
17
+ const entry = join(root, 'src', 'plugin.ts')
18
+ const outfile = join(root, 'src', 'plugin', 'index.js')
16
19
 
17
- buildSync({
18
- entryPoints: [join(root, 'src', 'plugin.ts')],
19
- outfile: join(root, 'src', 'plugin', 'index.js'),
20
- bundle: true,
21
- platform: 'node',
22
- format: 'esm',
23
- packages: 'external',
24
- })
20
+ let built = false
21
+ try {
22
+ const { buildSync } = await import('esbuild')
23
+ buildSync({
24
+ entryPoints: [entry],
25
+ outfile,
26
+ bundle: true,
27
+ platform: 'node',
28
+ format: 'esm',
29
+ packages: 'external',
30
+ })
31
+ built = true
32
+ } catch {
33
+ // Fallback to local node_modules binary
34
+ const localBin = join(root, 'node_modules', '.bin', 'esbuild')
35
+ if (existsSync(localBin)) {
36
+ execFileSync(localBin, [
37
+ entry,
38
+ `--outfile=${outfile}`,
39
+ '--bundle',
40
+ '--platform=node',
41
+ '--format=esm',
42
+ '--packages=external',
43
+ ])
44
+ built = true
45
+ }
46
+ }
47
+
48
+ if (!built) {
49
+ throw new Error('Could not find esbuild to bundle src/plugin.ts')
50
+ }
25
51
 
26
52
  console.log('Built src/plugin/index.js via esbuild.')
@@ -0,0 +1,139 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * build-roster.mjs — Declarative Roster Generator.
4
+ *
5
+ * Compiles specialist agent markdown files (`src/agents/*.md`) mechanically
6
+ * from the single source of truth: `src/agents/roster.json`.
7
+ *
8
+ * Eliminates copy-paste drift, ensures frontmatter conformance, and enables
9
+ * centralized governance over permissions, model reasoning effort, and skills.
10
+ *
11
+ * Usage:
12
+ * node scripts/build-roster.mjs # compiles all agents
13
+ * node scripts/build-roster.mjs --check # verifies zero drift; exits 1 if stale
14
+ */
15
+
16
+ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
17
+ import { dirname, join } from 'node:path'
18
+ import { fileURLToPath } from 'node:url'
19
+
20
+ const __dirname = dirname(fileURLToPath(import.meta.url))
21
+ const ROOT = join(__dirname, '..')
22
+ const ROSTER_PATH = join(ROOT, 'src', 'agents', 'roster.json')
23
+ const AGENTS_DIR = join(ROOT, 'src', 'agents')
24
+
25
+ export function formatFrontmatter(agent) {
26
+ const lines = ['---']
27
+
28
+ if (agent.name) lines.push(`name: ${agent.name}`)
29
+ if (agent.description) {
30
+ lines.push(`description: ${JSON.stringify(agent.description)}`)
31
+ }
32
+ if (agent.mode) lines.push(`mode: ${agent.mode}`)
33
+ if (agent.reasoning_effort) lines.push(`reasoning_effort: ${agent.reasoning_effort}`)
34
+ if (agent.temperature !== undefined && agent.temperature !== null) {
35
+ lines.push(`temperature: ${agent.temperature}`)
36
+ }
37
+
38
+ if (agent.permission && Object.keys(agent.permission).length > 0) {
39
+ lines.push('permission:')
40
+ for (const [key, val] of Object.entries(agent.permission)) {
41
+ if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
42
+ lines.push(` ${key}:`)
43
+ for (const [subKey, subVal] of Object.entries(val)) {
44
+ const formattedSubVal =
45
+ typeof subVal === 'string' && subVal.includes('*') ? `"${subVal}"` : subVal
46
+ const formattedSubKey = subKey.includes('*') ? `"${subKey}"` : subKey
47
+ lines.push(` ${formattedSubKey}: ${formattedSubVal}`)
48
+ }
49
+ } else {
50
+ lines.push(` ${key}: ${val}`)
51
+ }
52
+ }
53
+ }
54
+
55
+ if (agent.mcp_tools && Object.keys(agent.mcp_tools).length > 0) {
56
+ lines.push('mcp_tools:')
57
+ for (const [server, tools] of Object.entries(agent.mcp_tools)) {
58
+ if (Array.isArray(tools)) {
59
+ if (server === 'pantheon-memory' && tools.length > 2) {
60
+ lines.push(` ${server}:`)
61
+ for (const t of tools) {
62
+ lines.push(` - ${t}`)
63
+ }
64
+ } else {
65
+ lines.push(` ${server}: [${tools.join(', ')}]`)
66
+ }
67
+ } else {
68
+ lines.push(` ${server}: ${tools}`)
69
+ }
70
+ }
71
+ }
72
+
73
+ if (Array.isArray(agent.skills) && agent.skills.length > 0) {
74
+ lines.push('skills:')
75
+ for (const skill of agent.skills) {
76
+ lines.push(` - ${skill}`)
77
+ }
78
+ }
79
+
80
+ lines.push('---')
81
+ return lines.join('\n')
82
+ }
83
+
84
+ export function generateAgentMarkdown(agent) {
85
+ const fm = formatFrontmatter(agent)
86
+ const body = (agent.body ?? '').trim()
87
+ return `${fm}\n\n${body}\n`
88
+ }
89
+
90
+ export function buildRoster({ check = false } = {}) {
91
+ if (!existsSync(ROSTER_PATH)) {
92
+ console.error(`Roster manifest not found at ${ROSTER_PATH}`)
93
+ process.exit(1)
94
+ }
95
+
96
+ const raw = readFileSync(ROSTER_PATH, 'utf8')
97
+ const manifest = JSON.parse(raw)
98
+ const agents = manifest.agents ?? {}
99
+ const agentKeys = Object.keys(agents).sort()
100
+
101
+ let hasDrift = false
102
+
103
+ for (const key of agentKeys) {
104
+ const agent = agents[key]
105
+ const targetFile = join(AGENTS_DIR, `${key}.md`)
106
+ const expected = generateAgentMarkdown(agent)
107
+
108
+ if (check) {
109
+ if (!existsSync(targetFile)) {
110
+ console.error(`[DRIFT] Missing agent file: ${targetFile}`)
111
+ hasDrift = true
112
+ continue
113
+ }
114
+ const actual = readFileSync(targetFile, 'utf8')
115
+ if (actual.trim() !== expected.trim()) {
116
+ console.error(`[DRIFT] Content mismatch in: ${key}.md`)
117
+ hasDrift = true
118
+ }
119
+ } else {
120
+ writeFileSync(targetFile, expected, 'utf8')
121
+ }
122
+ }
123
+
124
+ if (check) {
125
+ if (hasDrift) {
126
+ console.error('\n❌ Roster drift detected. Run `npm run build:roster` to synchronize.')
127
+ process.exit(1)
128
+ } else {
129
+ console.log(`[OK] All ${agentKeys.length} agents are synchronized with roster.json.`)
130
+ }
131
+ } else {
132
+ console.log(`[OK] Successfully compiled ${agentKeys.length} agents from roster.json.`)
133
+ }
134
+ }
135
+
136
+ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
137
+ const check = process.argv.includes('--check')
138
+ buildRoster({ check })
139
+ }
@@ -22,9 +22,17 @@
22
22
  * Exit codes: 0 = no blocking errors (warnings are allowed), 2 = errors.
23
23
  */
24
24
 
25
- import { spawn as spawnAsync, spawnSync } from 'node:child_process'
25
+ import { execSync, spawn as spawnAsync, spawnSync } from 'node:child_process'
26
26
  import { createHash } from 'node:crypto'
27
- import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs'
27
+ import {
28
+ existsSync,
29
+ lstatSync,
30
+ mkdirSync,
31
+ readdirSync,
32
+ readFileSync,
33
+ realpathSync,
34
+ statSync,
35
+ } from 'node:fs'
28
36
  import { homedir } from 'node:os'
29
37
  import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
30
38
  import { fileURLToPath } from 'node:url'
@@ -1514,6 +1522,106 @@ export function checkInstallVersionDrift(args) {
1514
1522
  return 'sync'
1515
1523
  }
1516
1524
 
1525
+ // ---------------------------------------------------------------------------
1526
+ // Check H2b: PATH shadowing across global npm prefixes (Issue #424)
1527
+ // ---------------------------------------------------------------------------
1528
+
1529
+ /**
1530
+ * Check H2b: PATH shadowing across global npm prefixes.
1531
+ *
1532
+ * When multiple copies of pantheon-opencode are installed globally (e.g. across nvm,
1533
+ * ~/.npm-global, /usr/local), PATH may resolve an older or different version than the
1534
+ * package running doctor or OpenCode.
1535
+ */
1536
+ export function checkPathShadowing(args = {}) {
1537
+ section('H2b. PATH Shadowing & Binary Resolution')
1538
+ const env = args.env ?? process.env
1539
+ const isWindows = process.platform === 'win32'
1540
+ const whichCmd = isWindows ? 'where pantheon-opencode' : 'which -a pantheon-opencode'
1541
+
1542
+ let raw = ''
1543
+ try {
1544
+ raw = execSync(whichCmd, {
1545
+ env,
1546
+ encoding: 'utf8',
1547
+ stdio: ['ignore', 'pipe', 'ignore'],
1548
+ }).trim()
1549
+ } catch {
1550
+ info('No global pantheon-opencode binary found in PATH')
1551
+ return 'no-binary'
1552
+ }
1553
+
1554
+ const binaries = raw
1555
+ .split(/\r?\n/)
1556
+ .map((line) => line.trim())
1557
+ .filter(Boolean)
1558
+
1559
+ if (binaries.length === 0) {
1560
+ info('No pantheon-opencode binary found in PATH')
1561
+ return 'no-binary'
1562
+ }
1563
+
1564
+ let danglingFound = false
1565
+ const resolvedBinaries = []
1566
+
1567
+ for (const binPath of binaries) {
1568
+ let real = null
1569
+ try {
1570
+ real = realpathSync(binPath)
1571
+ } catch {
1572
+ danglingFound = true
1573
+ error(`Dangling binary symlink in PATH: ${binPath} points to a non-existent path`)
1574
+ continue
1575
+ }
1576
+
1577
+ let binVersion = null
1578
+ let curDir = dirname(real)
1579
+ for (let i = 0; i < 4; i++) {
1580
+ const candidatePkg = join(curDir, 'package.json')
1581
+ if (existsSync(candidatePkg)) {
1582
+ try {
1583
+ const p = readJson(candidatePkg)
1584
+ if (p?.name === 'pantheon-opencode') {
1585
+ binVersion = p.version
1586
+ break
1587
+ }
1588
+ } catch {}
1589
+ }
1590
+ curDir = dirname(curDir)
1591
+ }
1592
+
1593
+ resolvedBinaries.push({ path: binPath, real, version: binVersion })
1594
+ }
1595
+
1596
+ if (danglingFound) return 'dangling'
1597
+
1598
+ if (resolvedBinaries.length > 1) {
1599
+ const primary = resolvedBinaries[0]
1600
+ const others = resolvedBinaries.slice(1)
1601
+ const divergent = others.filter(
1602
+ (b) => b.version && primary.version && b.version !== primary.version,
1603
+ )
1604
+
1605
+ if (divergent.length > 0) {
1606
+ warn(
1607
+ `Multiple global pantheon-opencode installs detected across PATH prefixes:\n` +
1608
+ resolvedBinaries
1609
+ .map(
1610
+ (b, idx) =>
1611
+ ` ${idx === 0 ? '▶ (active)' : ' (shadowed)'} ${b.path} (v${b.version ?? 'unknown'})`,
1612
+ )
1613
+ .join('\n') +
1614
+ `\nStale global copies cause version skew. Clean up stale prefixes with: npm uninstall -g pantheon-opencode`,
1615
+ { code: 'path_shadowing_detected', classification: 'advisory' },
1616
+ )
1617
+ return 'shadowing'
1618
+ }
1619
+ }
1620
+
1621
+ pass(`Primary binary in PATH resolves cleanly (${binaries[0]})`)
1622
+ return 'ok'
1623
+ }
1624
+
1517
1625
  // ---------------------------------------------------------------------------
1518
1626
  // Check H3: Plugin version drift (issue #158)
1519
1627
  // ---------------------------------------------------------------------------
@@ -3053,6 +3161,7 @@ async function main() {
3053
3161
  checkCodeModeDir(args)
3054
3162
  checkCodeModeManifest(args)
3055
3163
  checkInstallVersionDrift(args)
3164
+ checkPathShadowing(args)
3056
3165
  checkPluginVersionDrift(args)
3057
3166
  await checkTuiPlugin(args)
3058
3167
  await checkInstallerFileInventory(args)
@@ -642,6 +642,22 @@ export function resolveStablePantheonRoot(root = ROOT) {
642
642
  'pantheon-opencode',
643
643
  )
644
644
  if (existsSync(join(globalCandidate, 'src', 'plugin', 'index.ts'))) {
645
+ try {
646
+ const rootPkg = readJsonConfig(join(root, 'package.json'))
647
+ const globalPkg = readJsonConfig(join(globalCandidate, 'package.json'))
648
+ if (rootPkg?.version && globalPkg?.version) {
649
+ if (rootPkg.version === globalPkg.version) {
650
+ return { root: globalCandidate, volatile: false }
651
+ }
652
+ return {
653
+ root,
654
+ volatile: true,
655
+ skew: { running: rootPkg.version, global: globalPkg.version },
656
+ }
657
+ }
658
+ } catch {
659
+ // Fallback if package.json read fails
660
+ }
645
661
  return { root: globalCandidate, volatile: false }
646
662
  }
647
663
  return { root, volatile: true }
@@ -150,6 +150,8 @@ const GLOBAL_NPM_ENV_KEYS = new Set([
150
150
  'npm_config_globalconfig',
151
151
  'npm_config_prefix',
152
152
  'npm_config_location',
153
+ 'npm_config_allow_scripts',
154
+ 'npm_config_approve_scripts',
153
155
  ])
154
156
 
155
157
  /**