pantheon-opencode 1.6.0 → 1.6.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.
@@ -0,0 +1,91 @@
1
+ /**
2
+ * opencode-state.mjs — where an OpenCode host keeps its state, resolved once.
3
+ *
4
+ * WHY THIS MODULE EXISTS: the installer used to PRINT a hardcoded claim about
5
+ * state isolation (`~/.local/share/opencode/opencode-v2.db`, "open service port
6
+ * 49375"). Nothing in this package ever set `OPENCODE_DB`, no installer created
7
+ * that file, and no code bound that port — it was a sentence about a
8
+ * configuration that never existed outside a sandbox. A notice is a statement
9
+ * about the user's machine, so it has to be produced by the same rule the host
10
+ * and Pantheon's own database consumers use, not by a literal.
11
+ *
12
+ * THE RULE (mirrored from `resolveCostDbPath` in src/pantheon/cost-command.ts
13
+ * and from the credential-store lookup in scripts/vision-status.mjs):
14
+ *
15
+ * 1. `OPENCODE_DB` — an explicit file override (what a SANDBOX uses; it is
16
+ * also the only reason an `opencode-v2.db` name ever appears anywhere);
17
+ * 2. otherwise the XDG default `<data dir>/opencode.db`, where `<data dir>` is
18
+ * `$XDG_DATA_HOME/opencode` when `XDG_DATA_HOME` is set, else
19
+ * `~/.local/share/opencode`.
20
+ *
21
+ * There is deliberately NO per-generation filename and no per-generation port:
22
+ * both host generations read the same store, and the schema — not the filename
23
+ * — is what distinguishes their ledgers. `PANTHEON_COST_DB` is NOT part of this
24
+ * rule: it redirects the cost REPORT only, never the host's store.
25
+ *
26
+ * Plain Node ESM on purpose: this is consumed by the installer (no TypeScript)
27
+ * and by tests, and the equivalent TypeScript resolver is not importable there.
28
+ *
29
+ * @module opencode-state
30
+ */
31
+
32
+ import { homedir } from 'node:os'
33
+ import { join } from 'node:path'
34
+
35
+ /** The one filename every real installation writes. */
36
+ export const OPENCODE_DB_FILENAME = 'opencode.db'
37
+
38
+ /** Directory name under the XDG data root. */
39
+ export const OPENCODE_DATA_DIR_NAME = 'opencode'
40
+
41
+ /**
42
+ * OpenCode data directory: `$XDG_DATA_HOME/opencode` when set, else
43
+ * `~/.local/share/opencode`.
44
+ *
45
+ * @param {NodeJS.ProcessEnv} [env]
46
+ * @param {string} [home]
47
+ * @returns {string}
48
+ */
49
+ export function openCodeDataDir(env = process.env, home = homedir()) {
50
+ const configured = typeof env.XDG_DATA_HOME === 'string' ? env.XDG_DATA_HOME.trim() : ''
51
+ const dataHome = configured !== '' ? configured : join(home, '.local', 'share')
52
+ return join(dataHome, OPENCODE_DATA_DIR_NAME)
53
+ }
54
+
55
+ /**
56
+ * Resolve the host's state database the way the host does.
57
+ *
58
+ * Returns the path AND its source, because the two produce different honest
59
+ * wording: an `OPENCODE_DB` override is the user's own choice, while the XDG
60
+ * path is only this platform's documented default.
61
+ *
62
+ * @param {NodeJS.ProcessEnv} [env]
63
+ * @param {string} [home]
64
+ * @returns {{ path: string, source: 'OPENCODE_DB' | 'default' }}
65
+ */
66
+ export function resolveOpenCodeStatePath(env = process.env, home = homedir()) {
67
+ const override = typeof env.OPENCODE_DB === 'string' ? env.OPENCODE_DB.trim() : ''
68
+ if (override !== '') return { path: override, source: 'OPENCODE_DB' }
69
+ return { path: join(openCodeDataDir(env, home), OPENCODE_DB_FILENAME), source: 'default' }
70
+ }
71
+
72
+ /**
73
+ * One honest sentence about state sharing for the generation being installed.
74
+ *
75
+ * Both generations read one store, so "isolated" is never the right word. The
76
+ * sentence names the resolved path, says where that path came from, and states
77
+ * that Pantheon binds no service port (there is nothing to name).
78
+ *
79
+ * @param {NodeJS.ProcessEnv} [env]
80
+ * @param {string} [home]
81
+ * @returns {string}
82
+ */
83
+ export function describeSharedState(env = process.env, home = homedir()) {
84
+ const { path: dbPath, source } = resolveOpenCodeStatePath(env, home)
85
+ const origin = source === 'OPENCODE_DB' ? 'set by OPENCODE_DB' : 'the host default'
86
+ return (
87
+ `State is shared, not isolated per generation: OpenCode V1 and V2 read the same ` +
88
+ `store (${dbPath}; ${origin}). Pantheon configures no separate database and binds ` +
89
+ 'no service port.'
90
+ )
91
+ }
@@ -12,15 +12,17 @@
12
12
  * scripts/install/opencode-version.mjs). Known V2 beta gaps handled here:
13
13
  * top-level `subagent_depth` is migrated to `experimental.subagent_depth`, and
14
14
  * the instruction content is consolidated into AGENTS.md, which both versions
15
- * load. Pass --version v2 to pantheon-init for an informational label; state
16
- * isolation is handled at runtime via OPENCODE_DB.
15
+ * load. Pass --version v2 to pantheon-init for an informational label.
16
+ *
17
+ * Nothing here isolates host STATE: both generations read one OpenCode store,
18
+ * and the resolver in scripts/install/opencode-state.mjs (not a literal in this
19
+ * file) is what the V2 notice reports.
17
20
  */
18
21
 
19
22
  import { createHash } from 'node:crypto'
20
- import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
23
+ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs'
21
24
  import { homedir } from 'node:os'
22
25
  import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
23
- import { listV2UnsupportedFeatures } from '../../src/pantheon/v2-unsupported.mjs'
24
26
  import { copyAgentPrompts, writeAgentsMdManaged } from '../build-agents-md.mjs'
25
27
  import { backupWarning, createBackupSet, previewBackupSet } from './backup.mjs'
26
28
  import {
@@ -49,6 +51,7 @@ import {
49
51
  import { componentForInstalledPath, updateFileInventory } from './file-inventory.mjs'
50
52
  import { healthCheck } from './health-check.mjs'
51
53
  import { detectVersion, runMigrations } from './migrate.mjs'
54
+ import { describeSharedState } from './opencode-state.mjs'
52
55
  import { DRY_RUN_PROBE_TIMEOUT_MS, resolveOpenCodeVersion } from './opencode-version.mjs'
53
56
  import {
54
57
  ACTIONS,
@@ -81,7 +84,11 @@ import {
81
84
  } from './shared.mjs'
82
85
  import { createInitialState, hasState, readState, setComponentState, writeState } from './state.mjs'
83
86
  import { strings } from './strings.mjs'
84
-
87
+ import {
88
+ describePluginOptionsReachability,
89
+ formatV2CapabilityNotice,
90
+ v2Capabilities,
91
+ } from './v2-capabilities.mjs'
85
92
  import { setupVenv, venvPythonPath } from './venv.mjs'
86
93
  import { assertNoSymlinkAncestors, assertPathWithin, assertSafeRemoval } from './verify.mjs'
87
94
 
@@ -573,6 +580,78 @@ function normalizePluginRef(ref) {
573
580
  return typeof ref === 'string' ? ref.replaceAll('\\', '/').replace(/\/$/, '') : ref
574
581
  }
575
582
 
583
+ /**
584
+ * Whether a path-ish plugin ref is a filesystem path rather than a package spec.
585
+ *
586
+ * The V2 loader treats anything that is not an obvious path as an npm/GitHub
587
+ * spec and runs `npm install` on it — including `a/b`, which it reads as a
588
+ * GitHub repository and fails on (`NpmInstallFailedError`). A relative path is
589
+ * always spelled with `./` or `../`, so that spelling is the discriminator.
590
+ *
591
+ * @param {string} value
592
+ * @returns {boolean}
593
+ */
594
+ function looksLikePluginPath(value) {
595
+ if (value.startsWith('.') || value.startsWith('/') || value.startsWith('~')) return true
596
+ return /^[A-Za-z]:[\\/]/.test(value)
597
+ }
598
+
599
+ /**
600
+ * Whether the OpenCode V2 loader can load a `plugins` entry EXACTLY as written.
601
+ *
602
+ * This is the gate for the V1→V2 migration: the V1 singular `plugin` list is
603
+ * ignored by the V2 host, but moving an entry there into `plugins` only helps
604
+ * when the loader accepts it. The loader's contract (documented on
605
+ * PANTHEON_V2_PLUGIN and proven by sandbox probes) is:
606
+ * - a DIRECTORY containing a real index.ts/index.js loads;
607
+ * - a file path is rejected ("must be a directory");
608
+ * - a package shorthand is resolved through `npm install` and dies with
609
+ * NpmInstallFailedError.
610
+ * Migrating a file path or a shorthand would therefore convert "silently
611
+ * ignored" into "config fails to load", which is worse than leaving it alone.
612
+ *
613
+ * @param {unknown} entry the `plugins`/`plugin` entry
614
+ * @param {string} configDir the config directory the loader resolves against
615
+ * @returns {{ loadable: boolean, reason: 'directory'|'file'|'missing'|'npm-spec'|'unverifiable', resolved: string|null }}
616
+ */
617
+ export function v2PluginEntryLoadability(entry, configDir) {
618
+ if (typeof entry !== 'string' || entry.trim() === '') {
619
+ return { loadable: false, reason: 'unverifiable', resolved: null }
620
+ }
621
+ const value = entry.trim()
622
+ if (!looksLikePluginPath(value)) {
623
+ return { loadable: false, reason: 'npm-spec', resolved: null }
624
+ }
625
+ const resolved = isAbsolute(value) ? value : resolve(configDir, value)
626
+ if (!existsSync(resolved)) {
627
+ return { loadable: false, reason: 'missing', resolved }
628
+ }
629
+ try {
630
+ if (!statSync(resolved).isDirectory()) {
631
+ return { loadable: false, reason: 'file', resolved }
632
+ }
633
+ } catch {
634
+ return { loadable: false, reason: 'missing', resolved }
635
+ }
636
+ return { loadable: true, reason: 'directory', resolved }
637
+ }
638
+
639
+ /** Human explanation of a non-loadable entry, naming the exact failure mode. */
640
+ const V2_LOAD_FAILURES = {
641
+ 'npm-spec':
642
+ 'is a package/GitHub shorthand, which the V2 loader resolves through `npm install` and fails on (NpmInstallFailedError)',
643
+ file: 'is a file, and the V2 loader only accepts a directory containing index.ts ("must be a directory")',
644
+ missing:
645
+ 'does not exist, and the V2 loader only accepts an existing directory containing index.ts',
646
+ unverifiable:
647
+ 'is not a path this installer can verify, so it was left untouched rather than guessed at',
648
+ }
649
+
650
+ /** Render a plugin entry for a warning without ever printing a bare object. */
651
+ function describePluginEntry(entry) {
652
+ return typeof entry === 'string' ? entry : JSON.stringify(entry)
653
+ }
654
+
576
655
  const PANTHEON_V1_PLUGIN = 'src/plugin.ts'
577
656
  const PANTHEON_V1_HOOKS = 'src/plugins/pantheon-hooks.ts'
578
657
  // Canonical V2 entry is the plugin DIRECTORY (beta loader contract: entries
@@ -1471,9 +1550,10 @@ async function installPass(
1471
1550
 
1472
1551
  // V1/V2 dual-version awareness (Phase 3): the installer builds a unified
1473
1552
  // config, then applies V2-native migration (migrateV1toV2) when
1474
- // --opencode-version=v2. V2 normalizes V1 fields in memory (no rewrite) and
1475
- // isolates its state DB via OPENCODE_DB (~/.local/share/opencode/opencode-v2.db)
1476
- // with a distinct service port (49375 vs V1's 49374).
1553
+ // --opencode-version=v2. V2 normalizes V1 fields in memory (no rewrite).
1554
+ // Neither generation isolates state: both read the same OpenCode store, so
1555
+ // the V2 notice reports the path an actual resolver returns instead of a
1556
+ // literal, and claims no service port because nothing binds one.
1477
1557
  // Default to 'auto' so a flagless run resolves against the actual host. A
1478
1558
  // hardcoded 'v1' here (or in bin/pantheon-init.mjs) is what shipped the bug:
1479
1559
  // the V1 branch writes .ts file paths that a 2.x host drops from the config.
@@ -1503,25 +1583,30 @@ async function installPass(
1503
1583
  )
1504
1584
  }
1505
1585
  const versionAssumed = dryRun && versionFallback !== null
1506
- if (version === 'v2') {
1507
- notice(
1508
- 'OpenCode V2 target — shared config; state isolated via OPENCODE_DB ' +
1509
- '(~/.local/share/opencode/opencode-v2.db), service port 49375',
1510
- )
1511
- // Say what the V2 contract does NOT give you, at the moment the user picks
1512
- // it. The V2 surface is 3 tools (hashline_edit, pantheon_cost,
1513
- // pantheon_model); V1's is 6 plus the BackgroundJobBoard, the three goal
1514
- // tools and the caller/target delegation matrix. This list was previously
1515
- // reachable only through `getUnsupportedFeatures()`, which no production
1516
- // code called — a user migrating hit the reduction with no warning at all.
1517
- //
1518
- // The markers are read from the same seed `getUnsupportedFeatures()` is
1519
- // built from (src/pantheon/v2-unsupported.mjs), so this notice cannot drift
1520
- // from what the plugin reports. Advisory: a V2 install is a supported
1521
- // configuration, not a failure.
1522
- notice(
1523
- `V2 plugin generation — reduced surface. Unsupported features: ${listV2UnsupportedFeatures().join(', ')}`,
1524
- )
1586
+ // Both V2 notices belong to the run the USER started, not to the internal
1587
+ // plan pass the gate spawns. That pass runs with the same output channel, so
1588
+ // an ungated notice printed twice on the unauthorized-preview path (`init`
1589
+ // without --yes: plan pass, then the outer apply pass, both loud). The
1590
+ // sibling `warning()` for a sibling opencode.jsonc is gated the same way;
1591
+ // a real --dry-run is not a plan pass, so it still prints them once.
1592
+ if (version === 'v2' && !opts.planOnly) {
1593
+ // The notice states only what this installer actually does and what the
1594
+ // host actually reads. It previously claimed an isolated state database and
1595
+ // a dedicated service port: nothing in this package sets OPENCODE_DB, no
1596
+ // install creates a per-generation file, nothing binds that port, and the
1597
+ // repo's own database consumer documents the opposite
1598
+ // (src/pantheon/cost-command.ts). The path below comes from the shared
1599
+ // resolver, so the sentence cannot drift from the code.
1600
+ notice(`OpenCode V2 target — ${describeSharedState()}`)
1601
+ // Say what the V2 contract gives you AND what it does not, at the moment
1602
+ // the user picks it. "Reduced surface" alone is misleading in both
1603
+ // directions: V2 registers real hooks, transforms and events, and it also
1604
+ // drops the goal tools. The not-registered half is the same SEED
1605
+ // `getUnsupportedFeatures()` is built from (imported, never restated), so
1606
+ // this notice cannot drift from what the plugin reports; the notice says
1607
+ // so, because the live list is a superset that grows at runtime. Advisory:
1608
+ // a V2 install is a supported configuration, not a failure.
1609
+ notice(formatV2CapabilityNotice())
1525
1610
  }
1526
1611
 
1527
1612
  // Interactive mode handling
@@ -1548,14 +1633,40 @@ async function installPass(
1548
1633
  isTTY: opts.deps?.isTTY,
1549
1634
  })
1550
1635
 
1636
+ // Resolve the location from the SELECTION before any cancel return: a
1637
+ // cancel after the user picked "Current project" must record that
1638
+ // directory, not the global default the caller would fall back to. The
1639
+ // recorded target is where the user was installing, not where a file was
1640
+ // written (nothing was written either way).
1641
+ const selectedTarget = result.target === 'project' ? process.cwd() : target
1642
+
1551
1643
  if (result.canceled) {
1552
- notice('Installation canceled.')
1553
- return { ...stats, applied: false, reason: 'canceled' }
1644
+ // The named point is what makes the message explainable. The interactive
1645
+ // module already printed the single cancel line through the prompt
1646
+ // library's own cancel channel, so printing another one here was the
1647
+ // duplicate the issue reports: the user saw the same sentence twice and
1648
+ // learned nothing about WHERE it stopped.
1649
+ return {
1650
+ ...stats,
1651
+ applied: false,
1652
+ reason: 'canceled',
1653
+ cancelPoint: result.cancelPoint ?? 'components',
1654
+ target: selectedTarget,
1655
+ }
1554
1656
  }
1555
1657
 
1556
1658
  if (!result.confirmed) {
1557
- notice('Installation canceled.')
1558
- return { ...stats, applied: false, reason: 'canceled' }
1659
+ // Answering "No" at the pre-install confirmation is not the prompt
1660
+ // library's cancel channel, so nothing was printed yet: this is the one
1661
+ // message, and it names the point.
1662
+ notice(S.canceledAt(S.cancelPoints.confirmation))
1663
+ return {
1664
+ ...stats,
1665
+ applied: false,
1666
+ reason: 'canceled',
1667
+ cancelPoint: 'confirmation',
1668
+ target: selectedTarget,
1669
+ }
1559
1670
  }
1560
1671
 
1561
1672
  // Map target selection to actual path
@@ -1565,9 +1676,7 @@ async function installPass(
1565
1676
  componentSet.clear()
1566
1677
  for (const c of newComponents) componentSet.add(c)
1567
1678
 
1568
- if (result.target === 'project') {
1569
- target = process.cwd()
1570
- }
1679
+ target = selectedTarget
1571
1680
  }
1572
1681
 
1573
1682
  // Product defaults live in code (PRODUCT_CONFIG_DEFAULTS). A repository-root
@@ -1583,6 +1692,25 @@ async function installPass(
1583
1692
  const pantheonConfigPath =
1584
1693
  typeof mergeDevConfigOpt === 'string' ? resolve(mergeDevConfigOpt) : null
1585
1694
  const targetConfigPath = join(target, 'opencode.json')
1695
+ // The installer reads and writes ONLY `opencode.json`, but the V2 host also
1696
+ // loads a sibling `opencode.jsonc` and unions arrays from both. A Pantheon
1697
+ // entry there is invisible to this installer, so a "second config" is a real
1698
+ // ambiguity the user has to resolve — name it instead of leaving the two
1699
+ // files to disagree silently.
1700
+ const siblingJsonc = join(target, 'opencode.jsonc')
1701
+ const configAdvisories = []
1702
+ if (version === 'v2' && existsSync(siblingJsonc)) {
1703
+ configAdvisories.push(
1704
+ `Both ${targetConfigPath} and ${siblingJsonc} exist and an OpenCode V2 host merges ` +
1705
+ 'them (scalars from the .jsonc win, arrays are unioned). The installer reads and ' +
1706
+ 'writes only opencode.json, so anything plugin-related in the .jsonc — including a ' +
1707
+ 'Pantheon entry — is neither seen nor changed by this install. Move those entries ' +
1708
+ 'into opencode.json and delete the .jsonc, or edit both by hand.',
1709
+ )
1710
+ // The internal plan pass is not a user-facing report; the apply pass (and a
1711
+ // real --dry-run) prints it once.
1712
+ if (!opts.planOnly) warning(configAdvisories[0])
1713
+ }
1586
1714
  const { config, raw: configRaw } = readJsonConfigWithRaw(targetConfigPath)
1587
1715
  const pantheonConfig =
1588
1716
  pantheonConfigPath !== null && existsSync(pantheonConfigPath)
@@ -1674,12 +1802,19 @@ async function installPass(
1674
1802
  isTTY: opts.deps?.isTTY,
1675
1803
  })
1676
1804
  if (accepted === PROMPT_CANCELED) {
1677
- notice(S.nothingApplied)
1678
- return { ...stats, applied: false, reason: 'canceled' }
1805
+ // The real prompt already printed the one cancel line through clack's
1806
+ // own cancel channel. An INJECTED reviewer (tests, other callers)
1807
+ // prints nothing, so this is the single place that guarantees the
1808
+ // message exists exactly once, and it names the point.
1809
+ if (typeof injected === 'function') notice(S.canceledAt(S.cancelPoints.review))
1810
+ return { ...stats, applied: false, reason: 'canceled', cancelPoint: 'review' }
1679
1811
  }
1680
1812
  if (!accepted) {
1681
- notice(S.nothingApplied)
1682
- return { ...stats, applied: false, reason: 'declined' }
1813
+ // Answering "No" is not a cancel: it used to reach the caller as a
1814
+ // silent `reason: 'declined'` and exit 0 with "Nothing applied." and
1815
+ // no explanation at all.
1816
+ notice(S.declinedAt(S.cancelPoints.review))
1817
+ return { ...stats, applied: false, reason: 'declined', cancelPoint: 'review' }
1683
1818
  }
1684
1819
  } else {
1685
1820
  notice(S.planOnlyNoYes)
@@ -2433,11 +2568,55 @@ async function installPass(
2433
2568
  }
2434
2569
 
2435
2570
  if (version === 'v2') {
2436
- // V2 loads the plural `plugins` list. Keep third-party V1 entries in the
2437
- // legacy list for users who still use them, but never leave a Pantheon V1
2438
- // entry configured alongside the V2 package export.
2571
+ // V2 loads the plural `plugins` list, and the singular `plugin` key is dead
2572
+ // on this host. Migrating a V1 config therefore means deciding, entry by
2573
+ // entry, whether the V2 loader can load it AT ALL: a directory can, a file
2574
+ // path is rejected ("must be a directory") and a package shorthand dies in
2575
+ // `npm install`. Copying every entry across would turn "silently ignored"
2576
+ // into "config fails to load", so only loadable entries move; the rest stay
2577
+ // where they are and the warning names the exact failure mode.
2439
2578
  if (Array.isArray(config.plugin)) {
2579
+ // Strip Pantheon refs FIRST, exactly as the V1 branch does: a stale V1
2580
+ // .ts path is not a registrable entry on this host and must not be moved.
2440
2581
  config.plugin = removePantheonPluginReferences(config.plugin)
2582
+ if (!Array.isArray(config.plugins)) config.plugins = []
2583
+ const migrated = []
2584
+ const blocked = []
2585
+ for (const plugin of config.plugin) {
2586
+ const verdict = v2PluginEntryLoadability(plugin, target)
2587
+ if (!verdict.loadable) {
2588
+ blocked.push({ plugin, reason: verdict.reason })
2589
+ continue
2590
+ }
2591
+ if (!hasPluginReference(config.plugins, plugin)) {
2592
+ config.plugins.push(deepClone(plugin))
2593
+ migrated.push(plugin)
2594
+ }
2595
+ }
2596
+ if (migrated.length > 0) {
2597
+ warning(
2598
+ `V2 host ignores the singular "plugin" key; also registered ${migrated.length} ` +
2599
+ `third-party entr${migrated.length === 1 ? 'y' : 'ies'} under "plugins" so ` +
2600
+ `they keep loading: ${migrated.map(describePluginEntry).join(', ')}. ` +
2601
+ 'Remove any that only support the V1 plugin API.',
2602
+ )
2603
+ }
2604
+ if (blocked.length > 0) {
2605
+ warning(
2606
+ 'V2 host ignores the singular "plugin" key; these entries were left in it ' +
2607
+ `because the V2 loader cannot load them, so they will NOT be active: ${blocked
2608
+ .map(
2609
+ ({ plugin, reason }) =>
2610
+ `${describePluginEntry(plugin)} ${V2_LOAD_FAILURES[reason]}`,
2611
+ )
2612
+ .join('; ')}.`,
2613
+ )
2614
+ }
2615
+ // Pantheon refs are already gone. An emptied array is not configuration:
2616
+ // drop the dead key entirely so the written config points at the list the
2617
+ // V2 host actually reads. A surviving V1 list is the user's own data and
2618
+ // is left in place (a downgrade still finds it).
2619
+ if (config.plugin.length === 0) delete config.plugin
2441
2620
  }
2442
2621
  if (!Array.isArray(config.plugins)) config.plugins = []
2443
2622
  // Preserve any options already set on the Pantheon V2 entry across the
@@ -2476,11 +2655,49 @@ async function installPass(
2476
2655
  config.plugins = config.plugins.filter(
2477
2656
  (plugin) => pluginReferenceIdentity(plugin) !== pluginReferenceIdentity(resolvedV2),
2478
2657
  )
2479
- config.plugins.push(
2480
- existingV2Options === null
2481
- ? resolvedV2
2482
- : { package: resolvedV2, options: deepClone(existingV2Options) },
2658
+ // ALWAYS the object form, even on a fresh install with nothing to preserve.
2659
+ // The host hands a plugin its `options` only from `{ package, options }`,
2660
+ // and the opt-in features (`context_pruner`, `memory_injection`) read
2661
+ // `ctx.options`. Emitting a bare string — which a fresh install used to do —
2662
+ // left those features unreachable for anyone who did not already know the
2663
+ // object syntax from the docs, so the shape (with an empty options bag) is
2664
+ // written from the start and a user's hand-added keys survive a re-run.
2665
+ config.plugins.push({
2666
+ package: resolvedV2,
2667
+ options: existingV2Options === null ? {} : deepClone(existingV2Options),
2668
+ })
2669
+
2670
+ // A path that LOOKS like a Pantheon V2 entry but is not one this package
2671
+ // can prove it owns (managedPluginIdentity only recognizes installed copies
2672
+ // and this package's own paths) would now be registered twice: the host
2673
+ // would run both copies' hooks. Retiring it on a guess could delete a
2674
+ // third-party plugin, so say what is happening instead of guessing.
2675
+ const lookalikes = config.plugins.filter(
2676
+ (ref) =>
2677
+ !isPantheonPluginReference(ref) &&
2678
+ pluginMetadataReferences(ref).some((reference) =>
2679
+ /(^|\/)plugin-v2(?:\.ts)?$/.test(normalizePluginRef(reference)),
2680
+ ),
2483
2681
  )
2682
+ if (lookalikes.length > 0) {
2683
+ warning(
2684
+ 'This config also points at another copy of the Pantheon V2 plugin, which this ' +
2685
+ 'installer cannot prove it owns: ' +
2686
+ `${lookalikes.map(describePluginEntry).join(', ')}. With the entry registered in ` +
2687
+ 'this install, BOTH copies would load and their hooks would run twice. Remove that ' +
2688
+ 'entry by hand if it is an older Pantheon installation; it is left alone because a ' +
2689
+ 'third-party plugin could share the path.',
2690
+ )
2691
+ }
2692
+ }
2693
+
2694
+ // Report whether the entry the host will read can actually carry options.
2695
+ // Computed here, from the config this pass is about to write, so it answers
2696
+ // the installed state rather than an assumption.
2697
+ const v2PluginOptions =
2698
+ version === 'v2' ? describePluginOptionsReachability(config.plugins) : null
2699
+ if (v2PluginOptions !== null && !v2PluginOptions.reachable && !opts.planOnly) {
2700
+ warning(`Pantheon V2 plugin options are not reachable: ${v2PluginOptions.detail}`)
2484
2701
  }
2485
2702
 
2486
2703
  if (pantheonConfig !== null) {
@@ -2989,6 +3206,18 @@ async function installPass(
2989
3206
  target,
2990
3207
  openCodeVersion: version,
2991
3208
  versionAssumed,
3209
+ configAdvisories,
3210
+ v2Capabilities: version === 'v2' ? v2Capabilities() : null,
3211
+ pluginOptions: v2PluginOptions,
3212
+ }
3213
+ : {
3214
+ ...stats,
3215
+ applied: true,
3216
+ reason: 'applied',
3217
+ target,
3218
+ openCodeVersion: version,
3219
+ configAdvisories,
3220
+ v2Capabilities: version === 'v2' ? v2Capabilities() : null,
3221
+ pluginOptions: v2PluginOptions,
2992
3222
  }
2993
- : { ...stats, applied: true, reason: 'applied' }
2994
3223
  }
@@ -0,0 +1,115 @@
1
+ /**
2
+ * run-record.mjs — the one-line record of what the LAST `init` run did.
3
+ *
4
+ * WHY A SEPARATE FILE, AND NOT `install-state.json`: that manifest is written
5
+ * only by an APPLY, so it answers "what is installed" and cannot answer "what
6
+ * did the previous run decide". A canceled or declined run previously left no
7
+ * trace at all: the user saw a line scroll past, and a re-run could not tell
8
+ * whether the last attempt was interrupted, refused at the review prompt, or
9
+ * never authorized. This record is written on every non-preview termination,
10
+ * including the ones that apply nothing, so the answer survives the terminal.
11
+ *
12
+ * It is deliberately NOT an install artifact:
13
+ * - it is never registered in the file inventory, so it is not "owned" and
14
+ * uninstall/reconcile do not treat it as installed content;
15
+ * - it never replaces, mirrors or edits `install-state.json`;
16
+ * - a failure to write it never changes the exit code (see the caller): an
17
+ * explanation is worth having, not worth failing a run for.
18
+ *
19
+ * No secrets and no config contents are recorded — status, reason, cancel
20
+ * point, mode, version, timestamp and target only.
21
+ *
22
+ * @module run-record
23
+ */
24
+
25
+ import { mkdirSync, readFileSync } from 'node:fs'
26
+ import { join } from 'node:path'
27
+ import { writeFileAtomically } from './verify.mjs'
28
+
29
+ /** Directory inside the install target that holds Pantheon bookkeeping. */
30
+ export const RUN_RECORD_DIR = '.pantheon'
31
+
32
+ /** File name of the last-run record. */
33
+ export const RUN_RECORD_FILENAME = 'last-run.json'
34
+
35
+ /**
36
+ * Absolute path of the record for an install target.
37
+ *
38
+ * @param {string} target
39
+ * @returns {string}
40
+ */
41
+ export function runRecordPath(target) {
42
+ return join(target, RUN_RECORD_DIR, RUN_RECORD_FILENAME)
43
+ }
44
+
45
+ /**
46
+ * Build the record. Pure, so the shape is testable without touching disk.
47
+ *
48
+ * @param {{
49
+ * status: string,
50
+ * reason?: string|null,
51
+ * cancelPoint?: string|null,
52
+ * mode: 'apply'|'dry-run',
53
+ * applied: boolean,
54
+ * pantheonVersion?: string|null,
55
+ * at?: string,
56
+ * }} input
57
+ * @returns {object}
58
+ */
59
+ export function buildRunRecord({
60
+ status,
61
+ reason = null,
62
+ cancelPoint = null,
63
+ mode,
64
+ applied,
65
+ pantheonVersion = null,
66
+ at = new Date().toISOString(),
67
+ }) {
68
+ const where = cancelPoint === null ? '' : ` at ${cancelPoint}`
69
+ return {
70
+ schema_version: 1,
71
+ command: 'init',
72
+ status,
73
+ reason,
74
+ cancel_point: cancelPoint,
75
+ mode,
76
+ applied,
77
+ pantheon_version: pantheonVersion,
78
+ at,
79
+ summary: `init ${status}${where} — ${applied ? 'changes were applied' : 'nothing was applied'} (${at})`,
80
+ }
81
+ }
82
+
83
+ /**
84
+ * Persist the record. Never throws: a bookkeeping failure is reported to the
85
+ * caller, which prints it as a warning instead of hiding it.
86
+ *
87
+ * @param {string} target
88
+ * @param {object} record
89
+ * @returns {{written: boolean, path: string, error: string|null}}
90
+ */
91
+ export function writeRunRecord(target, record) {
92
+ const path = runRecordPath(target)
93
+ try {
94
+ mkdirSync(join(target, RUN_RECORD_DIR), { recursive: true })
95
+ writeFileAtomically(path, `${JSON.stringify(record, null, 2)}\n`)
96
+ return { written: true, path, error: null }
97
+ } catch (err) {
98
+ return { written: false, path, error: err instanceof Error ? err.message : String(err) }
99
+ }
100
+ }
101
+
102
+ /**
103
+ * Read the previous run's record, or null when there is none / it is unreadable.
104
+ *
105
+ * @param {string} target
106
+ * @returns {object|null}
107
+ */
108
+ export function readRunRecord(target) {
109
+ try {
110
+ const parsed = JSON.parse(readFileSync(runRecordPath(target), 'utf8'))
111
+ return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
112
+ } catch {
113
+ return null
114
+ }
115
+ }