pantheon-opencode 1.5.1 → 1.6.0-beta.1

package/scripts/check-plugin-v2-coverage.mjs

@@ -0,0 +1,213 @@
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+export const REQUIRED_NODE_VERSION = 'v24.15.0'
+export const LINE_THRESHOLD_NUMERATOR = 4
+export const LINE_THRESHOLD_DENOMINATOR = 5
+
+function integerField(value, name, minimum) {
+  const label = minimum === 0 ? 'non-negative' : 'positive'
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${name} must be a ${label} integer`)
+  }
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < minimum) {
+    throw new Error(`${name} must be a ${label} integer`)
+  }
+  return parsed
+}
+
+function normalizeSourcePath(source, repoRoot) {
+  const path = source.startsWith('file:') ? fileURLToPath(source) : source
+  return resolve(repoRoot, path)
+}
+
+function exactlyOneField(lines, name) {
+  const values = lines.filter((line) => line.startsWith(`${name}:`))
+  if (values.length !== 1) {
+    throw new Error(`target LCOV record must contain exactly one ${name} field`)
+  }
+  return values[0].slice(name.length + 1)
+}
+
+function optionalPair(lines, foundName, hitName) {
+  const foundFields = lines.filter((line) => line.startsWith(`${foundName}:`))
+  const hitFields = lines.filter((line) => line.startsWith(`${hitName}:`))
+  if (foundFields.length === 0 && hitFields.length === 0) return null
+  if (foundFields.length !== 1 || hitFields.length !== 1) {
+    throw new Error(`target LCOV record must contain one ${foundName}/${hitName} pair`)
+  }
+
+  const found = integerField(foundFields[0].slice(foundName.length + 1), foundName, 0)
+  const hit = integerField(hitFields[0].slice(hitName.length + 1), hitName, 0)
+  if (hit > found) throw new Error(`${hitName} ${hit} exceeds ${foundName} ${found}`)
+  return { hit, found }
+}
+
+/** Parse and validate the single LCOV record for the exact target source. */
+export function parseTargetLcov(report, repoRoot, targetPath) {
+  if (typeof report !== 'string' || report.trim() === '') {
+    throw new Error('LCOV report is empty')
+  }
+  const normalizedRoot = resolve(repoRoot)
+  const normalizedTarget = resolve(targetPath)
+  const records = []
+  let current = []
+  for (const line of report.split(/\r?\n/)) {
+    if (line === 'end_of_record') {
+      if (current.length > 0) records.push(current)
+      current = []
+    } else if (line.trim() !== '') {
+      current.push(line)
+    }
+  }
+  if (current.length > 0) records.push(current)
+
+  const targetRecords = []
+  for (const lines of records) {
+    const sourceFields = lines.filter((line) => line.startsWith('SF:'))
+    const matchingSources = sourceFields.filter(
+      (line) => normalizeSourcePath(line.slice(3), normalizedRoot) === normalizedTarget,
+    )
+    if (matchingSources.length === 0) continue
+    if (sourceFields.length !== 1 || matchingSources.length !== 1) {
+      throw new Error('target LCOV record must contain exactly one SF entry')
+    }
+    targetRecords.push(lines)
+  }
+
+  if (targetRecords.length !== 1) {
+    throw new Error(
+      `expected exactly one LCOV record for ${normalizedTarget}; found ${targetRecords.length} LCOV records`,
+    )
+  }
+
+  const lines = targetRecords[0]
+  const lineRecords = new Map()
+  for (const entry of lines.filter((line) => line.startsWith('DA:'))) {
+    const fields = entry.slice(3).split(',')
+    if (fields.length < 2 || fields.length > 3) {
+      throw new Error('DA entry must contain a line number and execution count')
+    }
+    const lineNumber = integerField(fields[0], 'DA line number', 1)
+    const count = integerField(fields[1], 'DA count', 0)
+    if (lineRecords.has(lineNumber)) {
+      throw new Error(`duplicate DA line number ${lineNumber}`)
+    }
+    lineRecords.set(lineNumber, count)
+  }
+
+  const found = integerField(exactlyOneField(lines, 'LF'), 'LF', 1)
+  const hit = integerField(exactlyOneField(lines, 'LH'), 'LH', 0)
+  if (hit > found) throw new Error(`LH ${hit} exceeds LF ${found}`)
+  if (found !== lineRecords.size) {
+    throw new Error(`LF ${found} does not equal ${lineRecords.size} unique DA entries`)
+  }
+
+  const coveredRecords = [...lineRecords.values()].filter((count) => count > 0).length
+  if (hit !== coveredRecords) {
+    throw new Error(`LH ${hit} does not equal ${coveredRecords} covered DA entries`)
+  }
+
+  return {
+    sourcePath: normalizedTarget,
+    lines: { hit, found },
+    branches: optionalPair(lines, 'BRF', 'BRH'),
+    functions: optionalPair(lines, 'FNF', 'FNH'),
+  }
+}
+
+/** Compare using integer arithmetic so the 80% boundary cannot round down. */
+export function passesLineThreshold(coverage) {
+  return (
+    BigInt(coverage.lines.hit) * BigInt(LINE_THRESHOLD_DENOMINATOR) >=
+    BigInt(coverage.lines.found) * BigInt(LINE_THRESHOLD_NUMERATOR)
+  )
+}
+
+function formatMetric(metric) {
+  if (metric == null || metric.found === 0) return 'not reported'
+  return `${metric.hit}/${metric.found} (${((metric.hit / metric.found) * 100).toFixed(2)}%)`
+}
+
+function listTypeScriptTests(repoRoot) {
+  const directory = join(repoRoot, 'tests', 'pantheon')
+  return readdirSync(directory)
+    .filter((file) => file.endsWith('.test.ts'))
+    .sort()
+    .map((file) => join(directory, file))
+}
+
+function runCoverage() {
+  if (process.version !== REQUIRED_NODE_VERSION) {
+    throw new Error(
+      `plugin-v2 coverage requires Node ${REQUIRED_NODE_VERSION}; got ${process.version}`,
+    )
+  }
+
+  const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+  const targetPath = resolve(repoRoot, 'src', 'plugin-v2.ts')
+  const testFiles = listTypeScriptTests(repoRoot)
+  if (testFiles.length === 0) throw new Error('no tests/pantheon/*.test.ts files found')
+
+  const tempRoot = mkdtempSync(join(tmpdir(), 'pantheon-plugin-v2-coverage-'))
+  try {
+    const lcovPath = join(tempRoot, 'coverage.lcov')
+    const nodeOptions = [process.env.NODE_OPTIONS, '--conditions=import'].filter(Boolean).join(' ')
+    const args = [
+      '--experimental-test-coverage',
+      '--enable-source-maps',
+      '--import',
+      'tsx',
+      '--test',
+      '--test-concurrency=1',
+      '--test-reporter=spec',
+      '--test-reporter=lcov',
+      '--test-reporter-destination=stdout',
+      `--test-reporter-destination=${lcovPath}`,
+      ...testFiles,
+    ]
+    const result = spawnSync(process.execPath, args, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      env: { ...process.env, NODE_OPTIONS: nodeOptions },
+      maxBuffer: 32 * 1024 * 1024,
+    })
+    if (result.stdout) process.stdout.write(result.stdout)
+    if (result.stderr) process.stderr.write(result.stderr)
+    if (result.error) throw new Error(`TypeScript test command failed: ${result.error.message}`)
+    if (result.status !== 0) {
+      throw new Error(`TypeScript test command exited ${result.status ?? 'without a status'}`)
+    }
+
+    let report
+    try {
+      report = readFileSync(lcovPath, 'utf8')
+    } catch (error) {
+      throw new Error(`LCOV report was not generated: ${error.message}`)
+    }
+    const coverage = parseTargetLcov(report, repoRoot, targetPath)
+    console.log(`Coverage source: ${coverage.sourcePath}`)
+    console.log(`Lines: ${formatMetric(coverage.lines)}`)
+    console.log(`Branches (informational): ${formatMetric(coverage.branches)}`)
+    console.log(`Functions (informational): ${formatMetric(coverage.functions)}`)
+    if (!passesLineThreshold(coverage)) {
+      throw new Error('src/plugin-v2.ts line coverage is below the required 80%')
+    }
+    console.log('src/plugin-v2.ts line coverage: PASS (>= 80%)')
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true })
+  }
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    runCoverage()
+  } catch (error) {
+    console.error(`Plugin V2 coverage gate: ${error.message}`)
+    process.exitCode = 1
+  }
+}

package/scripts/ci-validate-yaml.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 """Validate agent YAML frontmatter in CI."""
+
 import os
 import re
 import sys
@@ -7,18 +8,19 @@ import sys
 import yaml
 
 errors = 0
-for f in sorted(os.listdir('src/agents')):
-    if not f.endswith('.md'):
+for f in sorted(os.listdir("src/agents")):
+    if not f.endswith(".md"):
         continue
     with open(f"src/agents/{f}", encoding="utf-8") as agent_file:
         content = agent_file.read()
-    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
     if match:
         try:
             yaml.safe_load(match.group(1))
         except yaml.YAMLError as e:
-            print(f'FAIL: {f}: {e}')
+            print(f"FAIL: {f}: {e}")
             errors += 1
 
-print(f'{sum(1 for _ in os.listdir("src/agents") if _.endswith(".md")) - errors}/{sum(1 for _ in os.listdir("src/agents") if _.endswith(".md"))} agents valid')
+agent_count = sum(1 for _ in os.listdir("src/agents") if _.endswith(".md"))
+print(f"{agent_count - errors}/{agent_count} agents valid")
 sys.exit(errors)

package/scripts/code_mode_server.py

@@ -20,6 +20,11 @@ import hashlib
 import json
 import logging
 import os
+
+try:
+    import resource
+except (ImportError, OSError, ValueError):  # pragma: no cover - platform-specific
+    resource = None  # type: ignore[assignment]
 import shutil
 import signal
 import stat
@@ -125,6 +130,88 @@ def _build_script_env(
     return env
 
 
+# Additional tasks a sandboxed script may create beyond the UID's current
+# count. RLIMIT_NPROC is a per-real-UID limit on the *total* number of
+# processes AND threads, so the sandbox floor must clear everything the host
+# already owns before a script can fork at all. This headroom is the actual
+# anti-fork-bomb budget: the script still cannot exceed current + headroom.
+NPROC_HEADROOM: int = 64
+
+
+def _uid_task_count() -> int | None:
+    """Count the tasks (processes + threads) this real UID already owns.
+
+    The kernel compares the post-fork total against RLIMIT_NPROC, so this is
+    the number the sandbox limit has to exceed. Returns *None* when the count
+    cannot be established (no readable ``/proc``), which makes the caller
+    fail open on ``--nproc`` rather than pin a value that may be too low and
+    break every script.
+
+    The tally is one too high per process: ``/proc/<pid>/task`` already lists
+    the thread-group leader, so the extra ``1`` counts it twice. That bias
+    only widens the derived limit (the fail-open direction), so it is left in
+    place deliberately.
+    """
+    uid = os.getuid()
+    count = 0
+    try:
+        pids = os.listdir("/proc")
+    except OSError:
+        return None
+    for pid in pids:
+        if not pid.isdigit():
+            continue
+        proc_dir = f"/proc/{pid}"
+        try:
+            if os.stat(proc_dir).st_uid != uid:
+                continue
+            # ``/proc/<pid>/task`` already includes the thread-group leader,
+            # so the extra 1 counts it twice (over-count by one per process).
+            count += 1 + len(os.listdir(f"{proc_dir}/task"))
+        except OSError:
+            # Process exited between listdir and stat, or is not ours to read.
+            continue
+    return count
+
+
+def _sandbox_nproc() -> str | None:
+    """Return the ``--nproc`` value for a sandboxed script, or *None*.
+
+    Derived from the host rather than hardcoded: the value is the UID's
+    current task count plus ``NPROC_HEADROOM``, clamped to the hard limit
+    (``prlimit`` fails with EPERM above it, and an unprivileged process cannot
+    raise its soft limit past the hard one).
+
+    Returns *None* when the count or the limit cannot be read, in which case
+    the caller omits ``--nproc``. ``--as`` and ``--cpu`` still apply, so the
+    sandbox keeps its memory and CPU boundaries.
+    """
+    current = _uid_task_count()
+    if current is None:
+        _log.warning(
+            "code-mode: cannot count this UID's tasks; omitting --nproc, so "
+            "the sandboxed script's fork budget is unbounded"
+        )
+        return None
+    if resource is None:
+        _log.warning(
+            "code-mode: cannot read RLIMIT_NPROC; omitting --nproc, so the "
+            "sandboxed script's fork budget is unbounded"
+        )
+        return None
+    try:
+        _soft, hard = resource.getrlimit(resource.RLIMIT_NPROC)
+    except (OSError, ValueError):
+        _log.warning(
+            "code-mode: cannot read RLIMIT_NPROC; omitting --nproc, so the "
+            "sandboxed script's fork budget is unbounded"
+        )
+        return None
+    if hard == getattr(resource, "RLIM_INFINITY", -1):
+        return str(current + NPROC_HEADROOM)
+    return str(max(1, min(current + NPROC_HEADROOM, hard)))
+
+
 def _prlimit_prefix(
     prlimit_path: str | None,
     timeout_s: int = SCRIPT_TIMEOUT,
@@ -132,21 +219,34 @@ def _prlimit_prefix(
     """Return a ``prlimit`` command prefix to wrap a subprocess, or *None*.
 
     On Linux with ``prlimit`` available the prefix adds:
-      --nproc=512  --as=1073741824  --cpu=<timeout_s + 5>
-
-    On non-Linux or when *prlimit_path* is falsy, returns *None* (fail-open).
+      --nproc=<uid task count + NPROC_HEADROOM>  --as=1073741824
+      --cpu=<timeout_s + 5>
+
+    ``--nproc`` is derived per invocation by :func:`_sandbox_nproc` rather
+    than hardcoded. RLIMIT_NPROC is a per-real-UID total across processes AND
+    threads, so a fixed value below the host's current usage makes the very
+    first ``fork()`` inside the sandbox fail with EAGAIN — which is exactly
+    what a hardcoded ``--nproc=512`` did on a host already running more than
+    512 tasks. The isolation property is unchanged: a script still cannot
+    create more than ``NPROC_HEADROOM`` additional tasks.
+
+    On non-Linux, when *prlimit_path* is falsy, or when the nproc limit cannot
+    be derived, the flag is omitted (fail-open); ``--as``/``--cpu`` remain.
     """
     if not prlimit_path:
         return None
 
     cpu_limit = timeout_s + 5
-    return [
-        prlimit_path,
-        "--nproc=512",
+    prefix = [prlimit_path]
+    nproc = _sandbox_nproc()
+    if nproc is not None:
+        prefix.append(f"--nproc={nproc}")
+    prefix += [
         "--as=1073741824",  # 1 GiB in bytes
         f"--cpu={cpu_limit}",
         "--",
     ]
+    return prefix
 
 
 def _detect_prlimit() -> str | None:
@@ -226,7 +326,9 @@ def _packaged_scripts_dir() -> Path | None:
     return None
 
 
-def _resolve_scripts_dir(candidates: list[Path], *, allow_packaged: bool = True) -> Path | None:
+def _resolve_scripts_dir(
+    candidates: list[Path], *, allow_packaged: bool = True
+) -> Path | None:
     """Select the first usable candidate, optionally trying the package copy."""
     for candidate in candidates:
         if _has_usable_scripts(candidate):
@@ -377,9 +479,7 @@ def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
         ) from None
 
     if not isinstance(data, dict):
-        raise ManifestError(
-            "CORRUPT_DATA", "Code-mode manifest must be a JSON object."
-        )
+        raise ManifestError("CORRUPT_DATA", "Code-mode manifest must be a JSON object.")
 
     if data.get("version") != 1:
         raise ManifestError(
@@ -527,7 +627,6 @@ def _contract_result(
     return f"[{status}] {message}"
 
 
-
 def _format_output(
     stdout: str,
     stderr: str,
@@ -818,22 +917,15 @@ async def execute_code_script(
                 timeout_s=timeout_s,
                 status="TIMEOUT",
             )
-    except FileNotFoundError:
-        return _build_result(
-            "",
-            f"Script '{script_name}' not found or interpreter missing.",
-            -1,
-            timed_out=False,
-            duration_ms=0,
-            metadata=metadata,
-            json_output=json_output,
-            timeout_s=timeout_s,
-            status="UNAVAILABLE",
-        )
     except OSError as e:
+        error = (
+            f"Script '{script_name}' not found or interpreter missing."
+            if isinstance(e, FileNotFoundError)
+            else f"Failed to execute script: {e}"
+        )
         return _build_result(
             "",
-            f"Failed to execute script: {e}",
+            error,
             -1,
             timed_out=False,
             duration_ms=0,

package/scripts/doctor.mjs

@@ -88,15 +88,25 @@ function parseArgs(argv) {
     args.target = process.cwd()
   }
 
-  if (args.profile === 'auto') {
-    args.profile = args.target.includes('pantheon-sandbox') ? 'sandbox' : 'global'
-  }
-
   // Resolve to absolute
   if (!args.target.startsWith('/')) {
     args.target = join(process.cwd(), args.target)
   }
 
+  if (args.profile === 'auto') {
+    const target = resolve(args.target)
+    // A checkout is not a managed OpenCode installation: its repository
+    // config intentionally contains only development MCPs. Use the lite
+    // policy for `npm run doctor` so a fresh checkout does not require a
+    // user's global MCP registry or pre-existing venv.
+    args.profile =
+      target === resolve(ROOT)
+        ? 'lite'
+        : args.target.includes('pantheon-sandbox')
+          ? 'sandbox'
+          : 'global'
+  }
+
   return args
 }
 
@@ -159,7 +169,7 @@ function showHelp() {
    C. Permission Checks    — frontmatter validation
    D. OpenCode Status      — OpenCode artifact layout
    E. Git Status           — uncommitted changes
-   F. Runtime Layer        — venv python + pinned pip dependencies
+    F. Runtime Layer        — runtime Python + pinned pip dependencies
    H3. Plugin Drift        — registered plugin version vs this package
    K. Node Runtime         — node:sqlite availability for pantheon_cost
 
@@ -818,12 +828,14 @@ function checkGitStatus(args) {
 }
 
 // ---------------------------------------------------------------------------
-// Check F: Runtime Layer — Venv, Python & pinned dependencies
+// Check F: Runtime Layer — Runtime Python & pinned dependencies
 // ---------------------------------------------------------------------------
 // The MCP servers run on the venv Python under ~/.config/opencode/.venv
-// (same resolution as scripts/install-mcp.mjs). This layer verifies the venv
-// exists, the interpreter responds, and the installed packages satisfy the
-// EXACT pins in src/mcp/requirements-mcp.txt and requirements-vision.txt
+// (same resolution as scripts/install-mcp.mjs) after installation. A
+// repository checkout/CI job is not an installed target, however, so it may
+// intentionally have no venv. In that case the doctor uses PANTHEON_PYTHON or
+// python3 and still validates the exact pins. Missing or mismatched packages
+// remain blocking errors; the fallback never makes the runtime check advisory
 // (issue #18 / #21).
 
 /** Parse `pip freeze` output into a normalized name → version map. */
@@ -906,31 +918,53 @@ function checkRequirementLine(line, installed) {
   }
 }
 
+/** Classify whether a required runtime file is available to the doctor. */
+export function classifyRequiredRuntimeFile(exists) {
+  return exists ? 'present' : 'error'
+}
+
+/** Validate a required runtime requirements file without downgrading absence. */
+export function validateRequiredRuntimeFile(filePath) {
+  const present = classifyRequiredRuntimeFile(existsSync(filePath)) === 'present'
+  return {
+    ok: present,
+    message: present
+      ? `requirements file present: ${filePath}`
+      : `requirements file not found: ${filePath}`,
+  }
+}
+
 function checkVenvLayer(args) {
-  section('F. Runtime Layer — Venv, Python & Dependencies')
+  section('F. Runtime Layer — Runtime Python & Dependencies')
 
-  const venvPython = resolveRuntimePython(args)
+  const runtimePython = resolveRuntimePython(args)
 
-  if (!existsSync(venvPython)) {
-    if (args.profile === 'lite') {
-      info(`Venv python not found — runtime layer skipped for lite profile`)
+  if (!isAbsolute(runtimePython) || !existsSync(runtimePython)) {
+    if (runtimePython === 'python3') {
+      info('No dedicated .venv found — validating the Python interpreter on PATH')
     } else {
-      error(`Venv python not found: ${venvPython} (run \`pantheon-opencode init\` to create it)`)
+      error(
+        `Runtime Python not found: ${runtimePython} (set PANTHEON_PYTHON or run \`pantheon-opencode init\` to create a .venv)`,
+      )
+      return
     }
-    return
   }
-  pass(`Venv python exists: ${venvPython}`)
+  if (isAbsolute(runtimePython) && existsSync(runtimePython)) {
+    pass(`Runtime Python exists: ${runtimePython}`)
+  }
 
-  const probe = spawn(venvPython, ['-c', 'import sys; print(sys.version.split()[0])'])
+  const probe = spawn(runtimePython, ['-c', 'import sys; print(sys.version.split()[0])'])
   if (probe.status !== 0) {
-    error(`Venv python does not respond (exit ${probe.status}): ${probe.stderr}`)
+    error(
+      `Runtime Python does not respond (exit ${probe.status}): ${probe.stderr || 'interpreter is unavailable'}`,
+    )
     return
   }
-  pass(`Venv python responds (Python ${probe.stdout})`)
+  pass(`Runtime Python responds (Python ${probe.stdout})`)
 
-  const freeze = spawn(venvPython, ['-m', 'pip', 'freeze'])
+  const freeze = spawn(runtimePython, ['-m', 'pip', 'freeze'])
   if (freeze.status !== 0) {
-    warn(`pip freeze failed (exit ${freeze.status}) — cannot verify pinned versions`)
+    error(`pip freeze failed (exit ${freeze.status}) — cannot verify pinned versions`)
     return
   }
   const installed = parsePipFreeze(freeze.stdout)
@@ -940,8 +974,9 @@ function checkVenvLayer(args) {
     join(ROOT, 'src', 'mcp', 'requirements-vision.txt'),
   ]
   for (const reqFile of reqFiles) {
-    if (!existsSync(reqFile)) {
-      warn(`requirements file not found: ${reqFile}`)
+    const requirement = validateRequiredRuntimeFile(reqFile)
+    if (!requirement.ok) {
+      error(requirement.message)
       continue
     }
     const base = basename(reqFile)
@@ -1073,7 +1108,9 @@ export function validateCodeModeManifest(codeModeDir) {
 
   const actualScripts = readdirSync(codeModeDir).filter(
     (name) =>
-      (name.endsWith('.py') || name.endsWith('.sh')) && statSync(join(codeModeDir, name)).isFile(),
+      !name.startsWith('eval-') &&
+      (name.endsWith('.py') || name.endsWith('.sh')) &&
+      statSync(join(codeModeDir, name)).isFile(),
   )
   const missing = listed.filter((name) => !existsSync(join(codeModeDir, name)))
   const extra = actualScripts.filter((name) => !Object.hasOwn(data.scripts, name))
@@ -1104,12 +1141,32 @@ export function checkCodeModeManifest(args) {
   pass(`✅ Code-mode manifest valid: ${result.count}/${result.total} scripts verified`)
 }
 
-/** Resolve the venv created by init for either a project or global install. */
+/**
+ * Resolve the Python used by the runtime checks.
+ *
+ * Installed targets use the venv created by init. A checkout in CI does not
+ * have that installation state, however, so the explicit PANTHEON_PYTHON
+ * override and the PATH fallback make the contract reproducible without
+ * silently skipping dependency validation.
+ */
 export function resolveRuntimePython(args) {
+  const env = args.env ?? process.env
+  if (typeof env.PANTHEON_PYTHON === 'string' && env.PANTHEON_PYTHON.trim() !== '') {
+    return env.PANTHEON_PYTHON.trim()
+  }
+
   const target = resolve(args.target)
   const isProject = existsSync(join(target, '.opencode'))
-  const runtimeRoot = isProject ? target : resolveOpenCodeConfigDir(args.env ?? process.env)
-  return join(runtimeRoot, '.venv', 'bin', 'python3')
+  const runtimeRoot = isProject ? target : resolveOpenCodeConfigDir(env)
+  const venvCandidates =
+    process.platform === 'win32'
+      ? [
+          join(runtimeRoot, '.venv', 'Scripts', 'python.exe'),
+          join(runtimeRoot, '.venv', 'Scripts', 'python'),
+        ]
+      : [join(runtimeRoot, '.venv', 'bin', 'python3'), join(runtimeRoot, '.venv', 'bin', 'python')]
+  const existing = venvCandidates.find((candidate) => existsSync(candidate))
+  return existing ?? 'python3'
 }
 
 /** Return relative script arguments as absolute paths using an MCP entry cwd. */

package/scripts/install/cli-ui.mjs

@@ -159,7 +159,7 @@ export function spinner(message) {
   }
 }
 
-export function printSummary(target, platforms, stats) {
+export function printSummary(target, _platforms, stats) {
   if (_quiet) return
 
   const S = strings()

package/scripts/install/config-migration.mjs

@@ -116,7 +116,7 @@ const PROVIDER_RENAME_REVERSE = Object.fromEntries(
  * V2 shape:
  *   { package: "aisdk:ai-sdk-openai", settings: { baseURL: "...", apiKey: "..." }, models: { ... } }
  */
-function convertProviderV1toV2(name, config) {
+function convertProviderV1toV2(_name, config) {
   const result = { ...config }
 
   // npm → package (with aisdk: prefix)
@@ -171,7 +171,7 @@ function convertProviderV1toV2(name, config) {
 /**
  * Convert a single V2 provider config back to V1.
  */
-function convertProviderV2toV1(name, config) {
+function convertProviderV2toV1(_name, config) {
   const result = { ...config }
 
   // package → npm (strip aisdk: prefix)