pantheon-opencode 1.6.0 → 1.6.2-beta.1

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 (115) hide show
  1. package/AGENTS.global.md +11 -11
  2. package/AGENTS.md +2 -2
  3. package/CHANGELOG.md +45 -0
  4. package/README.md +122 -6
  5. package/README.pt-BR.md +14 -9
  6. package/bin/pantheon-init.mjs +255 -39
  7. package/package.json +8 -6
  8. package/plugin.json +1 -1
  9. package/pyproject.toml +1 -1
  10. package/scripts/build-agents-md.mjs +1 -1
  11. package/scripts/doctor.mjs +231 -46
  12. package/scripts/install/agents-md.mjs +2 -1
  13. package/scripts/install/config-migration.mjs +344 -393
  14. package/scripts/install/config-paths.mjs +15 -0
  15. package/scripts/install/interactive.mjs +30 -9
  16. package/scripts/install/interrupt.mjs +78 -0
  17. package/scripts/install/mcp-permissions.mjs +164 -0
  18. package/scripts/install/opencode-state.mjs +91 -0
  19. package/scripts/install/opencode-version.mjs +31 -13
  20. package/scripts/install/opencode-wildcard.mjs +106 -0
  21. package/scripts/install/opencode.mjs +508 -108
  22. package/scripts/install/plan-artifact.mjs +12 -1
  23. package/scripts/install/plugin.mjs +17 -1
  24. package/scripts/install/run-record.mjs +115 -0
  25. package/scripts/install/strings.mjs +35 -6
  26. package/scripts/install/v2-capabilities.mjs +204 -0
  27. package/scripts/package-evidence.mjs +1 -0
  28. package/scripts/release-gates.mjs +7 -2
  29. package/scripts/sandbox-env.sh +174 -0
  30. package/scripts/setup-v2-config.mjs +1703 -0
  31. package/scripts/setup.mjs +415 -0
  32. package/scripts/sync-tui.mjs +9 -1
  33. package/scripts/test-opencode-v2-sandbox.sh +438 -151
  34. package/scripts/update-skills-lock.mjs +30 -0
  35. package/skills-lock.json +10 -10
  36. package/src/agents/aphrodite.md +5 -2
  37. package/src/agents/apollo.md +5 -0
  38. package/src/agents/athena.md +6 -1
  39. package/src/agents/demeter.md +5 -1
  40. package/src/agents/gaia.md +4 -0
  41. package/src/agents/hephaestus.md +6 -1
  42. package/src/agents/hermes.md +6 -3
  43. package/src/agents/iris.md +5 -1
  44. package/src/agents/mnemosyne.md +20 -50
  45. package/src/agents/nyx.md +5 -1
  46. package/src/agents/prometheus.md +4 -0
  47. package/src/agents/talos.md +4 -0
  48. package/src/agents/themis.md +4 -0
  49. package/src/agents/zeus.md +9 -3
  50. package/src/instructions/agent-return-format.instructions.md +1 -1
  51. package/src/instructions/memory-protocol.instructions.md +3 -3
  52. package/src/instructions/test-economy.instructions.md +6 -6
  53. package/src/mcp/pantheon_vision.py +37 -36
  54. package/src/mcp/requirements-mcp.txt +1 -1
  55. package/src/mcp/requirements-vision.txt +1 -1
  56. package/src/pantheon/cost-command.ts +127 -40
  57. package/src/pantheon/delegation-enforce.ts +160 -23
  58. package/src/pantheon/guard-path.ts +162 -0
  59. package/src/pantheon/v2-bounded-read.ts +15 -1
  60. package/src/pantheon/v2-bridge.ts +27 -0
  61. package/src/pantheon/v2-shell-hooks.ts +260 -0
  62. package/src/pantheon/v2-unsupported.mjs +32 -4
  63. package/src/pantheon/v2-vision.ts +34 -29
  64. package/src/pantheon/vision.ts +49 -11
  65. package/src/plugin-v2.ts +413 -60
  66. package/src/plugin.ts +22 -2
  67. package/src/plugins/tui/dist/quota-adapters.d.ts +89 -0
  68. package/src/plugins/tui/dist/quota-adapters.d.ts.map +1 -0
  69. package/src/plugins/tui/dist/quota-adapters.js +1142 -0
  70. package/src/plugins/tui/dist/quota-adapters.js.map +1 -0
  71. package/src/plugins/tui/dist/quota-cli.d.ts +17 -0
  72. package/src/plugins/tui/dist/quota-cli.d.ts.map +1 -0
  73. package/src/plugins/tui/dist/quota-cli.js +184 -0
  74. package/src/plugins/tui/dist/quota-cli.js.map +1 -0
  75. package/src/plugins/tui/dist/quota-rpc-UL2HuFRJ.js +390 -0
  76. package/src/plugins/tui/dist/quota-rpc-UL2HuFRJ.js.map +1 -0
  77. package/src/plugins/tui/dist/server-v2.d.ts +14 -0
  78. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -0
  79. package/src/plugins/tui/dist/server-v2.js +673 -0
  80. package/src/plugins/tui/dist/server-v2.js.map +1 -0
  81. package/src/plugins/tui/dist/tui-v2.d.ts +247 -52
  82. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  83. package/src/plugins/tui/dist/tui-v2.js +2492 -529
  84. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  85. package/src/plugins/tui/dist/tui.js +1 -1
  86. package/src/plugins/tui/index-v2.ts +3 -6
  87. package/src/plugins/tui/package-lock.json +11 -11
  88. package/src/plugins/tui/package.json +6 -4
  89. package/src/plugins/tui/src/context-gauge.ts +59 -0
  90. package/src/plugins/tui/src/go-key-diagnostic-ui.ts +100 -0
  91. package/src/plugins/tui/src/go-key-diagnostic.ts +125 -0
  92. package/src/plugins/tui/src/index-v2.tsx +199 -240
  93. package/src/plugins/tui/src/model-usage-limits.ts +4 -0
  94. package/src/plugins/tui/src/quota-adapters.ts +1598 -0
  95. package/src/plugins/tui/src/quota-cli.ts +237 -0
  96. package/src/plugins/tui/src/quota-rpc.ts +209 -0
  97. package/src/plugins/tui/src/quota-v2-model.ts +1032 -0
  98. package/src/plugins/tui/src/quota-v2.tsx +986 -0
  99. package/src/plugins/tui/src/server-v2.ts +841 -0
  100. package/src/plugins/tui/src/sidebar-width.ts +129 -0
  101. package/src/plugins/tui/tsconfig.typecheck.json +1 -1
  102. package/src/plugins/tui/tsdown.config.ts +8 -1
  103. package/src/routing.yml +72 -13
  104. package/src/skills/README.md +4 -0
  105. package/src/skills/agent-coordination/SKILL.md +0 -3
  106. package/src/skills/artifact-management/SKILL.md +0 -3
  107. package/src/skills/auto-continue/SKILL.md +0 -3
  108. package/src/skills/code-review-checklist/SKILL.md +0 -3
  109. package/src/skills/context-compression/SKILL.md +0 -3
  110. package/src/skills/memory-bank/SKILL.md +6 -28
  111. package/src/skills/session-goal/SKILL.md +0 -3
  112. package/src/skills/simplify/SKILL.md +5 -4
  113. package/src/skills/tdd-with-agents/SKILL.md +0 -3
  114. package/src/skills/visual-review-pipeline/SKILL.md +0 -1
  115. package/src/pantheon/memory-context.ts +0 -1017
@@ -33,6 +33,7 @@ import { listV2UnsupportedFeatures } from '../src/pantheon/v2-unsupported.mjs'
33
33
  import { classifyFileInventory } from './install/file-inventory.mjs'
34
34
  import { staleTuiRefs } from './install/plugin.mjs'
35
35
  import { readState } from './install/state.mjs'
36
+ import { describePluginOptionsReachability } from './install/v2-capabilities.mjs'
36
37
  import { isSupportedNodeVersion, MIN_SUPPORTED_NODE_VERSION } from './node-engine-policy.mjs'
37
38
 
38
39
  // ---------------------------------------------------------------------------
@@ -353,6 +354,150 @@ export function collectMcpConfigs(args) {
353
354
  return configs
354
355
  }
355
356
 
357
+ function isRecord(value) {
358
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
359
+ }
360
+
361
+ /**
362
+ * Return MCP entries and retain whether each came from the V1 flat map or the
363
+ * V2 `mcp.servers` map. Nested-map detection is deliberately based on the map
364
+ * structure, not a partial server-field heuristic: malformed object entries
365
+ * still remain identifiable as nested entries and can fail closed below.
366
+ * @param {unknown} mcp
367
+ * @returns {Map<string, { entry: any, layout: 'v1' | 'v2' }>}
368
+ */
369
+ function getMcpServerEntryRecords(mcp) {
370
+ if (!isRecord(mcp)) return new Map()
371
+
372
+ const nested = mcp.servers
373
+ // A V1 server named "servers" is still a server config; otherwise this
374
+ // wrapper is the V2 map, including maps with malformed/non-object members.
375
+ // Keeping those malformed members in the V2 layout prevents a bad entry
376
+ // from making valid neighboring nested servers disappear.
377
+ const isNestedServerMap = isRecord(nested) && !isValidMcpServerEntry(nested, 'v1')
378
+ const entries = new Map()
379
+
380
+ for (const [name, entry] of Object.entries(mcp)) {
381
+ if (isNestedServerMap && name === 'servers') continue
382
+ entries.set(name, { entry, layout: 'v1' })
383
+ }
384
+
385
+ if (isNestedServerMap) {
386
+ for (const [name, entry] of Object.entries(nested)) {
387
+ // A nested entry takes precedence over a duplicate V1 flat name, in
388
+ // agreement with the V2 host's effective configuration.
389
+ entries.set(name, { entry, layout: 'v2' })
390
+ }
391
+ }
392
+
393
+ return entries
394
+ }
395
+
396
+ /**
397
+ * Return MCP entries from either the V1 flat map or V2's `mcp.servers` map.
398
+ * When both contain distinct names, keep both; for a duplicate, the nested V2
399
+ * entry wins because it is the shape the V2 host reads.
400
+ * @param {unknown} mcp
401
+ * @returns {Record<string, any>}
402
+ */
403
+ export function getMcpServerEntries(mcp) {
404
+ return Object.fromEntries(
405
+ [...getMcpServerEntryRecords(mcp)]
406
+ .filter(([, record]) => isRecord(record.entry))
407
+ .map(([name, record]) => [name, record.entry]),
408
+ )
409
+ }
410
+
411
+ function isStringMap(value) {
412
+ return isRecord(value) && Object.values(value).every((item) => typeof item === 'string')
413
+ }
414
+
415
+ /**
416
+ * Validate the timeout field against the OpenCode config generation in use.
417
+ * V1 MCP entries use a numeric timeout; V2 uses the named startup/catalog/
418
+ * execution timeout map, whose values are positive integers.
419
+ * @param {unknown} timeout
420
+ * @param {'v1' | 'v2'} layout
421
+ */
422
+ function isValidMcpTimeout(timeout, layout) {
423
+ if (layout === 'v1') return Number.isFinite(timeout) && timeout >= 0
424
+ if (!isRecord(timeout)) return false
425
+
426
+ const supportedTimeouts = new Set(['startup', 'catalog', 'execution'])
427
+ return Object.entries(timeout).every(
428
+ ([name, value]) => supportedTimeouts.has(name) && Number.isInteger(value) && value > 0,
429
+ )
430
+ }
431
+
432
+ /**
433
+ * OpenCode V2 remote MCP servers use Streamable HTTP and require an absolute
434
+ * HTTP(S) endpoint. Parsing without a base rejects relative URLs.
435
+ * @param {unknown} value
436
+ */
437
+ function isAbsoluteRemoteMcpUrl(value) {
438
+ if (typeof value !== 'string' || value.trim() === '' || value !== value.trim()) return false
439
+ try {
440
+ const url = new URL(value)
441
+ return (
442
+ (url.protocol === 'http:' || url.protocol === 'https:') &&
443
+ url.hostname !== '' &&
444
+ url.username === '' &&
445
+ url.password === ''
446
+ )
447
+ } catch {
448
+ return false
449
+ }
450
+ }
451
+
452
+ /** @param {unknown} value */
453
+ function hasEmbeddedRemoteMcpCredentials(value) {
454
+ if (typeof value !== 'string') return false
455
+ try {
456
+ const url = new URL(value)
457
+ return (
458
+ (url.protocol === 'http:' || url.protocol === 'https:') &&
459
+ (url.username !== '' || url.password !== '')
460
+ )
461
+ } catch {
462
+ return false
463
+ }
464
+ }
465
+
466
+ /**
467
+ * Verify the transport-specific required fields from OpenCode's local/remote
468
+ * MCP schema. Both V1 flat and V2 nested local commands are argv arrays.
469
+ * Unknown entry fields are left alone so documented and forward-compatible
470
+ * optional settings work.
471
+ * @param {any} entry
472
+ * @param {'v1' | 'v2'} layout
473
+ */
474
+ function isValidMcpServerEntry(entry, layout) {
475
+ if (!isRecord(entry) || (entry.type !== 'local' && entry.type !== 'remote')) return false
476
+
477
+ if (entry.enabled !== undefined && typeof entry.enabled !== 'boolean') return false
478
+ if (entry.disabled !== undefined && typeof entry.disabled !== 'boolean') return false
479
+ if (entry.timeout !== undefined && !isValidMcpTimeout(entry.timeout, layout)) return false
480
+ if (entry.cwd !== undefined && typeof entry.cwd !== 'string') return false
481
+ if (entry.environment !== undefined && !isStringMap(entry.environment)) return false
482
+
483
+ if (entry.type === 'local') {
484
+ if (
485
+ !Array.isArray(entry.command) ||
486
+ entry.command.length === 0 ||
487
+ entry.command.some((part) => typeof part !== 'string')
488
+ ) {
489
+ return false
490
+ }
491
+ return true
492
+ }
493
+
494
+ return (
495
+ isAbsoluteRemoteMcpUrl(entry.url) &&
496
+ (entry.headers === undefined || isStringMap(entry.headers)) &&
497
+ (entry.oauth === undefined || entry.oauth === false || isRecord(entry.oauth))
498
+ )
499
+ }
500
+
356
501
  function checkMcpConfig(args) {
357
502
  section('B. MCP Configuration')
358
503
 
@@ -376,49 +521,57 @@ function checkMcpConfig(args) {
376
521
  for (const cfg of configs) {
377
522
  info(`Checking ${cfg.label} opencode.json`)
378
523
 
379
- const mcp = cfg.data.mcp
380
- if (!mcp || typeof mcp !== 'object') {
524
+ const rawMcp = cfg.data.mcp
525
+ if (!rawMcp || typeof rawMcp !== 'object' || Array.isArray(rawMcp)) {
381
526
  if (requiredMcpNames.length > 0)
382
527
  error(`${cfg.label}: required MCPs missing — no "mcp" section`)
383
528
  else info(`${cfg.label}: no "mcp" section (${args.profile} profile — optional)`)
384
529
  continue
385
530
  }
531
+ const mcpRecords = getMcpServerEntryRecords(rawMcp)
532
+ for (const { entry, layout } of mcpRecords.values()) {
533
+ if (!isValidMcpServerEntry(entry, layout)) {
534
+ warn(`${cfg.label}: MCP server entry is invalid`)
535
+ }
536
+ }
386
537
 
387
538
  // 1. gh_grep MCP check (optional in every supported profile)
388
- const ghGrep = mcp.gh_grep
389
- if (ghGrep) {
390
- if (ghGrep.type === 'remote' && ghGrep.url === 'https://mcp.grep.app') {
539
+ const ghGrepRecord = mcpRecords.get('gh_grep')
540
+ if (ghGrepRecord) {
541
+ const { entry: ghGrep, layout } = ghGrepRecord
542
+ const isValid = isValidMcpServerEntry(ghGrep, layout)
543
+ if (isValid && ghGrep.type === 'remote' && ghGrep.url === 'https://mcp.grep.app') {
391
544
  pass(`${cfg.label}: gh_grep MCP configured correctly`)
392
- } else {
393
- const gotUrl = ghGrep.url ?? '<missing>'
394
- const detail =
395
- ghGrep.type !== 'remote'
396
- ? `type is "${ghGrep.type}" instead of "remote"`
397
- : `url is "${gotUrl}"`
398
- warn(`${cfg.label}: gh_grep MCP may need review — ${detail}`)
545
+ } else if (isValid) {
546
+ warn(
547
+ `${cfg.label}: gh_grep MCP may need review — expected a remote MCP at the recommended endpoint`,
548
+ )
399
549
  }
400
550
  } else {
401
551
  info(`${cfg.label}: optional gh_grep MCP not configured (${args.profile} profile)`)
402
552
  }
403
553
 
404
554
  // 2. Context7 MCP check
405
- const context7 = mcp.context7
406
- if (context7) {
407
- const isLocal = context7.type === 'local'
408
- const hasCommand =
409
- Array.isArray(context7.command) &&
410
- context7.command.length > 0 &&
411
- context7.command.some((s) => s.includes('context7-mcp') || s.includes('context7'))
412
- const enabled = context7.enabled !== false
413
-
414
- if (isLocal && hasCommand && enabled) {
415
- pass(`${cfg.label}: Context7 MCP configured correctly`)
416
- } else {
417
- const details = []
418
- if (!isLocal) details.push(`type should be "local"`)
419
- if (!hasCommand) details.push("command missing or doesn't mention context7-mcp")
420
- if (!enabled) details.push('not enabled')
421
- warn(`${cfg.label}: Context7 MCP issues — ${details.join(', ')}`)
555
+ const context7Record = mcpRecords.get('context7')
556
+ if (context7Record) {
557
+ const { entry: context7, layout } = context7Record
558
+ if (isValidMcpServerEntry(context7, layout)) {
559
+ const isLocal = context7.type === 'local'
560
+ const hasCommand =
561
+ Array.isArray(context7.command) &&
562
+ context7.command.length > 0 &&
563
+ context7.command.some((s) => s.includes('context7-mcp') || s.includes('context7'))
564
+ const enabled = context7.enabled !== false
565
+
566
+ if (isLocal && hasCommand && enabled) {
567
+ pass(`${cfg.label}: Context7 MCP configured correctly`)
568
+ } else {
569
+ const details = []
570
+ if (!isLocal) details.push(`type should be "local"`)
571
+ if (!hasCommand) details.push("command missing or doesn't mention context7-mcp")
572
+ if (!enabled) details.push('not enabled')
573
+ warn(`${cfg.label}: Context7 MCP issues — ${details.join(', ')}`)
574
+ }
422
575
  }
423
576
  } else {
424
577
  info(`${cfg.label}: optional Context7 MCP not configured (${args.profile} profile)`)
@@ -442,13 +595,18 @@ function checkMcpConfig(args) {
442
595
  // existing executable and existing absolute script paths. Catches the
443
596
  // ENOENT-on-spawn failure class (dead hardcoded path, ambiguous relative
444
597
  // path) before opencode tries to spawn the server.
445
- for (const [name, mcpEntry] of Object.entries(mcp)) {
446
- if (mcpEntry?.type !== 'local') continue
447
- const cmd = mcpEntry.command
448
- if (!Array.isArray(cmd) || cmd.length === 0) {
449
- warn(`${cfg.label}: MCP "${name}" has no command array`)
450
- continue
598
+ for (const [name, { entry: mcpEntry, layout }] of mcpRecords) {
599
+ if (
600
+ isRecord(mcpEntry) &&
601
+ mcpEntry.type === 'remote' &&
602
+ hasEmbeddedRemoteMcpCredentials(mcpEntry.url)
603
+ ) {
604
+ warn(
605
+ `${cfg.label}: a remote MCP URL contains embedded credentials; use environment variables for authentication instead`,
606
+ )
451
607
  }
608
+ if (!isValidMcpServerEntry(mcpEntry, layout) || mcpEntry.type !== 'local') continue
609
+ const cmd = mcpEntry.command
452
610
  const exe = cmd[0]
453
611
  if (!exe.includes('/')) {
454
612
  // PATH-resolved executable — cannot verify statically; surface for manual check
@@ -471,13 +629,25 @@ function checkMcpConfig(args) {
471
629
  }
472
630
 
473
631
  if (requiredMcpNames.length > 0) {
474
- const configured = new Set(configs.flatMap((cfg) => Object.keys(cfg.data.mcp ?? {})))
632
+ const configured = new Set(
633
+ configs.flatMap((cfg) =>
634
+ [...getMcpServerEntryRecords(cfg.data.mcp)]
635
+ .filter(([, { entry, layout }]) => isValidMcpServerEntry(entry, layout))
636
+ .map(([name]) => name),
637
+ ),
638
+ )
475
639
  for (const required of requiredMcpNames) {
476
640
  if (configured.has(required))
477
641
  pass(
478
642
  `Required MCP "${required}" entry is present (presence check only; this check does not verify enabled state, command/transport usability, connectivity, or health)`,
643
+ { code: 'required_mcp_present', classification: 'present', server: required },
479
644
  )
480
- else error(`Required MCP "${required}" not configured in any available config`)
645
+ else
646
+ error(`Required MCP "${required}" not configured in any available config`, {
647
+ code: 'required_mcp_missing',
648
+ classification: 'missing',
649
+ server: required,
650
+ })
481
651
  }
482
652
  }
483
653
  }
@@ -585,9 +755,8 @@ async function checkMcpRuntimeSmoke(args) {
585
755
 
586
756
  const local = []
587
757
  for (const cfg of collectMcpConfigs(args)) {
588
- for (const [name, entry] of Object.entries(cfg.data.mcp ?? {})) {
589
- if (entry?.type !== 'local') continue
590
- if (!Array.isArray(entry.command) || entry.command.length === 0) continue
758
+ for (const [name, { entry, layout }] of getMcpServerEntryRecords(cfg.data.mcp)) {
759
+ if (!isValidMcpServerEntry(entry, layout) || entry.type !== 'local') continue
591
760
  const cwd = resolveMcpCwd(entry, cfg.path)
592
761
  const command = entry.command.map((part, index) =>
593
762
  index === 0 || part.startsWith('-') || part.startsWith('/') ? part : resolve(cwd, part),
@@ -624,7 +793,7 @@ async function checkMcpRuntimeSmoke(args) {
624
793
  */
625
794
  function checkAgentMcpReferences(cfg) {
626
795
  const agentFiles = readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md'))
627
- const mcpNames = new Set(Object.keys(cfg.data.mcp ?? {}))
796
+ const mcpNames = new Set(Object.keys(getMcpServerEntries(cfg.data.mcp)))
628
797
  const referencedNames = new Set()
629
798
 
630
799
  for (const file of agentFiles) {
@@ -1664,17 +1833,19 @@ export function describeV2Reduction({ registered, features }) {
1664
1833
  'Pantheon IS registered on the V2 plugin generation, but the shared ' +
1665
1834
  'unsupported-feature seed is empty, so the reduction cannot be reported. ' +
1666
1835
  "That is a fault in this installation's reporting, not an absence of " +
1667
- 'reduction: the V2 surface still drops the 3 goal tools and the ' +
1668
- 'caller/target delegation matrix.',
1836
+ 'reduction: the V2 surface still registers fewer tools than V1 (the three ' +
1837
+ 'goal tools are absent), so a clean report would be false.',
1669
1838
  }
1670
1839
  }
1671
1840
  return {
1672
1841
  status: 'reported',
1673
1842
  level: 'warn',
1674
1843
  message:
1675
- 'Pantheon is registered on the V2 plugin generation, which registers 3 tools ' +
1676
- "(hashline_edit, pantheon_cost, pantheon_model) instead of the V1 surface's 6 plus " +
1677
- `the BackgroundJobBoard and the caller/target delegation matrix. Unsupported: ${features.join(', ')}`,
1844
+ 'Pantheon is registered on the V2 plugin generation: 3 unconditional tools ' +
1845
+ '(hashline_edit, pantheon_cost, pantheon_model) plus the host-dependent ones, and a ' +
1846
+ "real hook/transform surface, against the V1 surface's 6 tools plus the " +
1847
+ 'BackgroundJobBoard. Not provided on V2 (static seed — a live host can add runtime ' +
1848
+ `markers on top): ${features.join(', ')}`,
1678
1849
  }
1679
1850
  }
1680
1851
 
@@ -1707,6 +1878,20 @@ export function checkV2UnsupportedFeatures(args) {
1707
1878
  if (verdict.level === 'info') info(verdict.message)
1708
1879
  else warn(verdict.message)
1709
1880
 
1881
+ // Whether the installed entry can receive plugin `options` at all: the host
1882
+ // passes them only from the object form, and `context_pruner` reads that bag.
1883
+ // A bare-string entry installs fine and silently leaves the opt-in
1884
+ // unreachable, which is why this reports the installed shape instead of
1885
+ // trusting the installer to have got it right.
1886
+ if (registered) {
1887
+ const plugins = configs.flatMap((cfg) =>
1888
+ Array.isArray(cfg.data?.plugins) ? cfg.data.plugins : [],
1889
+ )
1890
+ const reach = describePluginOptionsReachability(plugins)
1891
+ if (reach.reachable) info(`Plugin options reachable: ${reach.detail}`)
1892
+ else warn(`Plugin options NOT reachable: ${reach.detail}`)
1893
+ }
1894
+
1710
1895
  return verdict.status
1711
1896
  }
1712
1897
 
@@ -164,7 +164,8 @@ export function generateAgentsMd(agents, platformName = '', extraSections = '')
164
164
  '## Commands',
165
165
  '',
166
166
  '- Build: `npm run build`',
167
- '- Test: `npm test`',
167
+ '- Focused test: run the smallest relevant check for the changed behavior',
168
+ '- Full suite: `npm test` (CI/release gates or broad/high-risk changes)',
168
169
  '- Lint: `npm run lint`',
169
170
  '',
170
171
  '## Conventions',