wkappbot-code 0.3.17 → 0.3.20

package/bin/wkappbot-code.js

@@ -47,6 +47,7 @@ import { hooksRow, wireClaudeHooks } from "../lib/hook-wire.js";
 import { installStarterMd, removeStarterMd } from "../lib/starter-md.js";
 import { addAllows, removeAllows } from "../lib/allow-compact.js";
 import { ensurePrereqs } from "../lib/prereq.js";
+import { ensurePython } from "../lib/python-acquire.js";
 import { files as setupFiles, launchOpenCode, printBanner } from "../lib/setup-run.js";
 
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -200,8 +201,8 @@ function installBin(o) {
   log("bin: bash " + script + " acquire --dest " + target);
   const r = spawnSync("bash", [shPath(script), "acquire", "--dest", shPath(target)], { encoding: "utf8", env: shEnv() });
   for (const line of ((r.stdout || "") + (r.stderr || "")).split("\n").filter(Boolean)) log("  " + line);
-  // rc 3 = the release host could not be reached (a package-registry-only VM): no core, but NOT a failed install --
-  // the hooks and the lite harness need no core and still refuse the risky classes. A sha256 mismatch stays rc 1.
+  // rc 3 = the release host could not be reached (a package-registry-only VM): no core. The hooks and the lite harness
+  // need no core and still refuse the risky classes, but the install reports the missing core as a FAILED part (0.3.13).
   if (r.status === 3) return { ok: false, degraded: true, dest, note: "core not fetched (release host unreachable); hooks + lite harness run without it -- rerun wkappbot-code install once github.com is reachable" };
   if (r.status !== 0) return { ok: false, dest, note: "wk-bin-acquire rc " + r.status };
   // Put `wkappbot` on PATH beside wkappbot-code itself, unless that name is already taken by someone else.
@@ -425,6 +426,8 @@ function install(o) {
   // is not on PATH is used from its folder, and a missing one is installed with winget (lib/prereq.js)
   st.prereq = ensurePrereqs({ log });
   if (!st.prereq.ok) bad++;
+  // 0.3.20 (owner 2026-11-09): a real Python before any step runs python -- the Store alias stub made install exit 49
+  st.python = ensurePython({ log });
   if (o.update) log("install --update: refreshing the core, the harness and the public skills");
   const ps = pwshPath();
   log("pwsh: " + (ps || "not found") + " -- the FULL harness (PowerShell 7) runs only on a dev seat (a harness checkout, or --dev-seat);" +
@@ -441,7 +444,7 @@ function install(o) {
     }
   }
   // 0.3.13 (owner 2026-11-08): the famous AI CLIs come along, so a user who knows nothing about LLMs still has them.
-  st.aiClis = (o.npm && o.aiClis) ? installAiClis(log, process.env, undefined, (prev.aiClis && prev.aiClis.installed) || [])
+  st.aiClis = (o.npm && o.aiClis) ? installAiClis(log, process.env, undefined, (prev.aiClis && prev.aiClis.installed) || [], (prev.aiClis && prev.aiClis.prefix) || "")
     : ((prev.aiClis && (prev.aiClis.installed || []).length) ? prev.aiClis : { skipped: true });  // a skip still owns what an earlier install added
   const dest = binDest(o);
   st.bin = o.bin ? installBin(o) : { skipped: true, dest };
@@ -569,7 +572,7 @@ function uninstall(o) {
     else log("shim: kept " + cmdShim + " (it no longer calls " + core + ")");
   }
   // 3d. the AI CLIs this install added (lib/ai-clis.js), never one the user had before
-  removeAiClis((st.aiClis && st.aiClis.installed) || [], log);
+  removeAiClis((st.aiClis && st.aiClis.installed) || [], log, process.env, undefined, (st.aiClis && st.aiClis.prefix) || "");
   // 4. the harness dirs we created, the plugin entry and our config folder
   // Windows frees a closed handle late (ENOTEMPTY): lib/rmtree.js retries ~6 s, then a per-entry pass names the blocker; a failure goes on.
   const rmTree = (p, what) => {

package/lib/ai-clis.js

@@ -23,6 +23,14 @@ export function cliVersion(name, env = process.env) {
   return m ? m[0] : line.slice(0, 40);
 }
 
+// The npm global prefix an install uses RIGHT NOW (npm_config_prefix included: npm exports it to a postinstall worker, so a
+// worker lays the CLIs into the prefix of the `npm install -g wkappbot-code` that started it). Recorded in the state so an
+// uninstall run from another shell takes the CLIs back from THAT prefix, not from whatever its own default prefix is.
+export function npmPrefix(env = process.env) {
+  const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", timeout: 30000, shell: IS_WIN, env });
+  return r.status === 0 ? String(r.stdout || "").trim().split("\n").pop().trim() : "";
+}
+
 function npmGlobal(pkgs, env) {
   const r = spawnSync("npm", ["install", "-g", ...pkgs, "--no-audit", "--no-fund"], { stdio: "inherit", shell: IS_WIN, env });
   return r.status === 0;
@@ -30,13 +38,14 @@ function npmGlobal(pkgs, env) {
 
 // Installs every CLI of AI_CLIS that is not on PATH yet. Returns { installed: [...], present: [...], failed: [...] }.
 // prevInstalled: the names an earlier install added; a rerun keeps owning them, so uninstall still takes them back.
-export function installAiClis(log, env = process.env, list = AI_CLIS, prevInstalled = []) {
+export function installAiClis(log, env = process.env, list = AI_CLIS, prevInstalled = [], prevPrefix = "") {
   const present = [], missing = [];
   for (const c of list) (cliVersion(c.name, env) ? present : missing).push(c);
   if (present.length) log("ai-clis: already installed: " + present.map((c) => c.name).join(", "));
-  const res = { installed: present.map((c) => c.name).filter((n) => prevInstalled.includes(n)), present: present.map((c) => c.name), failed: [] };
+  const res = { installed: present.map((c) => c.name).filter((n) => prevInstalled.includes(n)), present: present.map((c) => c.name), failed: [], prefix: prevPrefix };
   if (!missing.length) return res;
-  log("ai-clis: npm install -g " + missing.map((c) => c.pkg).join(" "));
+  res.prefix = npmPrefix(env) || prevPrefix;
+  log("ai-clis: npm install -g " + missing.map((c) => c.pkg).join(" ") + (res.prefix ? " (prefix " + res.prefix + ")" : ""));
   if (npmGlobal(missing.map((c) => c.pkg), env)) res.installed.push(...missing.map((c) => c.name));
   else {
     log("ai-clis: the one-pass install failed, retrying each CLI alone");
@@ -49,12 +58,14 @@ export function installAiClis(log, env = process.env, list = AI_CLIS, prevInstal
 // uninstall takes back what install added (SDK os-qa 2026-11-09, run 42552244938: the npm prefix bin kept claude, codex,
 // gemini and qwen after uninstall on every leg). Only the names install recorded go; a CLI the user had stays. A failed
 // npm uninstall is a WARN with the command to finish it by hand.
-export function removeAiClis(names, log, env = process.env, list = AI_CLIS) {
+// prefix: the npm global prefix install recorded (SDK os-qa u1-uninstall, 2026-11-09: the worker laid the CLIs into the
+// prefix of the npm that started it, and an uninstall from a shell with another default prefix left them behind).
+export function removeAiClis(names, log, env = process.env, list = AI_CLIS, prefix = "") {
   const pkgs = list.filter((c) => (names || []).includes(c.name)).map((c) => c.pkg);
   if (!pkgs.length) return true;
-  log("ai-clis: npm uninstall -g " + pkgs.join(" "));
-  const r = spawnSync("npm", ["uninstall", "-g", ...pkgs, "--no-audit", "--no-fund"], { stdio: "inherit", shell: IS_WIN, env });
-  if (r.status !== 0) log("ai-clis: WARN npm uninstall rc " + r.status + " -- run: npm uninstall -g " + pkgs.join(" "));
+  log("ai-clis: npm uninstall -g " + pkgs.join(" ") + (prefix ? " (prefix " + prefix + ")" : ""));
+  const r = spawnSync("npm", ["uninstall", "-g", ...pkgs, ...(prefix ? ["--prefix", prefix] : []), "--no-audit", "--no-fund"], { stdio: "inherit", shell: IS_WIN, env });
+  if (r.status !== 0) log("ai-clis: WARN npm uninstall rc " + r.status + " -- run: npm uninstall -g " + pkgs.join(" ") + (prefix ? " --prefix " + prefix : ""));
   return r.status === 0;
 }
 

package/lib/hook-wire.js

@@ -13,6 +13,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { pickPython, stubWarning } from "./python-pick.js";
 
 // The same harness-hook pattern as tools/wkharness-lite.sh --wire HARNESS_HOOK. ANCHORED (2026-11-09 review, proven on
 // fixtures): the loose form also took a user's own pwsh lint.ps1, bash ~/bin/session-start.sh and my-wkharness-notes.sh
@@ -147,8 +148,9 @@ export function ensureRules(kih, log = () => {}) {
   if (existsSync(want)) return "present";
   const shipped = join(kih, "tools", "wkharness-lite-rules.tsv");
   if (existsSync(shipped)) { mkdirSync(dirname(want), { recursive: true }); writeFileSync(want, readFileSync(shipped)); return "copied"; }
-  const py = spawnSync("sh", ["-c", "command -v python3"], { encoding: "utf8" });
-  if (py.status === 0) {
+  const py = pickPython();
+  if (py.stubs.length) log("hooks: " + stubWarning(py.stubs));
+  if (py.cmd) {
     const r = spawnSync("sh", [join(kih, "tools", "wkharness-lite.sh").replace(/\\/g, "/"), "--wire"], { encoding: "utf8" });
     if (r.status === 0 && existsSync(want)) return "built";
   }

package/lib/prereq.js

@@ -24,7 +24,7 @@ const realRun = (cmd, args, env) => spawnSync(cmd, args, { stdio: "inherit", env
 export function ensurePrereqs(o = {}) {
   const platform = o.platform || process.platform, env = o.env || process.env, log = o.log || (() => {});
   const which = o.which || realWhich, exists = o.exists || existsSync, run = o.run || realRun;
-  const probe = () => { const found = {}, missing = []; for (const t of TOOLS) { const p = which(t, env); if (p) found[t] = p; else missing.push(t); } return { found, missing }; };
+  let gitDir = ""; const inGit = (t) => { if (!gitDir) return ""; for (const sub of ["bin", join("usr", "bin"), "cmd", join("ucrt64", "bin"), join("mingw64", "bin"), join("clangarm64", "bin")]) { const f = join(gitDir, sub, t + ".exe"); if (exists(f)) return f; } return ""; }; const probe = () => { const found = {}, missing = []; for (const t of TOOLS) { const p = which(t, env) || inGit(t); if (p) found[t] = p; else missing.push(t); } return { found, missing }; };
   let p = probe(), via = "path";
   if (!p.missing.length) return { ok: true, missing: [], found: p.found, via, note: "" };
   if (platform !== "win32") {
@@ -36,17 +36,20 @@ export function ensurePrereqs(o = {}) {
     for (const d of GIT_DIRS(env)) {
       if (!exists(join(d, "bin", "bash.exe"))) continue;
       const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH") || "PATH";
-      env[key] = [join(d, "bin"), join(d, "usr", "bin"), join(d, "cmd")].join(delimiter) + delimiter + (env[key] || "");
+      const dirs = [join(d, "bin"), join(d, "usr", "bin"), join(d, "cmd"), ...[join(d, "ucrt64", "bin"), join(d, "mingw64", "bin"), join(d, "clangarm64", "bin")].filter((x) => exists(x))];
+      env[key] = dirs.join(delimiter) + delimiter + (env[key] || "");
       return d;
     }
     return "";
   };
   let dir = addGit();
+  gitDir = dir;
   if (dir) { p = probe(); via = "git-dir"; log("prereq: Git Bash found at " + dir + " (not on PATH) -- used for this install; add " + join(dir, "bin") + " to your PATH"); }
   if (p.missing.length && !o.noInstall && which("winget", env)) {
     log("prereq: Git for Windows (Git Bash) is missing -- installing it with winget");
     const rc = run("winget", ["install", "--id", "Git.Git", "-e", "--source", "winget", "--silent", "--accept-package-agreements", "--accept-source-agreements"], env);
     dir = addGit();
+    gitDir = dir;
     if (dir) { p = probe(); via = "winget"; log("prereq: winget installed Git for Windows at " + dir + " (rc " + rc + ")"); }
     else log("prereq: winget rc " + rc + " but no Git Bash was found afterwards");
   }

package/lib/python-acquire.js

@@ -0,0 +1,108 @@
+// wkappbot-code lib/python-acquire.js -- a REAL Python 3 on Windows before any step calls python (owner 2026-11-09:
+// "the harness install fails with code 49 when the Store alias is there -- detect the fake python, then force-install").
+// 49 is 9009 % 256: the Microsoft Store alias stub (WindowsApps\python.exe) seen through Git Bash or node.
+// ensurePython: probe (lib/python-pick.js, which RUNS each candidate); if no real Python and win32:
+//   1. winget install --id Python.Python.3.12 --scope user --silent (accept agreements)
+//   2. else the python.org embeddable zip, pinned 3.12.7 and sha256-checked, unpacked into ~/.wk-harness/python
+//   3. the real python dir goes AHEAD of %LOCALAPPDATA%\Microsoft\WindowsApps in the user PATH and in this process
+//   4. re-probe, then ONE line: "OK python <version> <path>" or "FAIL python: <reason>". It never throws.
+// Off Windows it only probes and reports (the package manager owns python there; lib/prereq.js names it).
+// Spec: wkappbot skill read harness-installer-owns-all-setup
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pickPython, stubWarning } from "./python-pick.js";
+
+export const EMBED = {
+  version: "3.12.7",
+  url: "https://www.python.org/ftp/python/3.12.7/python-3.12.7-embed-amd64.zip",
+  // measured 2026-11-09 from the python.org download over TLS (the release page lists no sha256 for this file)
+  sha256: "0d57bb6cb078b74d23dbfe91f77d6780d45bed328911609f1f7ee2ba1606bf44",
+};
+
+const realRun = (cmd, args, env, extra = {}) => spawnSync(cmd, args, { encoding: "utf8", env, timeout: 600000, windowsHide: true, ...extra });
+const pathKey = (env) => Object.keys(env).find((k) => k.toUpperCase() === "PATH") || "PATH";
+
+// dir first on a Windows PATH string (";" separated on every host, so the selftest runs anywhere), but always ahead
+// of any WindowsApps entry
+export function pathAheadOfWindowsApps(pathStr, dir) {
+  const parts = String(pathStr || "").split(";").filter((p) => p && p.toLowerCase() !== dir.toLowerCase());
+  const i = parts.findIndex((p) => /\\Microsoft\\WindowsApps\\?$/i.test(p));
+  if (i < 0) return [dir, ...parts].join(";");
+  parts.splice(i, 0, dir);
+  return parts.join(";");
+}
+
+// The folder winget's per-user Python lands in (LOCALAPPDATA\Programs\Python\Python3xx), newest first.
+function wingetPythonDir(env, exists, list) {
+  const base = join(env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "Programs", "Python");
+  let names = [];
+  try { names = list(base).filter((n) => /^Python3\d+$/i.test(n)).sort().reverse(); } catch { return ""; }
+  for (const n of names) if (exists(join(base, n, "python.exe"))) return join(base, n);
+  return "";
+}
+
+function setUserPath(dir, run, env) {
+  // the user PATH (registry), not the merged one; same ordering rule as tools/wk-fresh-windows-tools.ps1
+  const ps = (cmd, e) => run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", cmd], e);
+  const cur = ps("[Environment]::GetEnvironmentVariable('Path','User')", env);
+  if (!cur || cur.status !== 0) return false;
+  const next = pathAheadOfWindowsApps(String(cur.stdout || "").trim(), dir);
+  // the value travels in an env var, so no quoting of the PATH text is ever needed
+  const w = ps("[Environment]::SetEnvironmentVariable('Path',$env:WK_NEW_USER_PATH,'User')", { ...env, WK_NEW_USER_PATH: next });
+  return w && w.status === 0;
+}
+
+export function ensurePython(o = {}) {
+  const env = o.env || process.env, log = o.log || (() => {}), run = o.run || realRun;
+  const platform = o.platform || process.platform, exists = o.exists || existsSync, list = o.list || readdirSync;
+  const home = o.home || homedir(), read = o.read || readFileSync;
+  const report = (ok, msg, extra = {}) => { log((ok ? "OK python " : "FAIL python: ") + msg); return { ok, note: msg, ...extra }; };
+  try {
+    let p = pickPython({ env, run: o.probeRun });
+    const warn = stubWarning(p.stubs);
+    if (p.cmd) {
+      const v = run(p.cmd, [...p.args, "-c", "import sys;print(sys.version.split()[0]);print(sys.executable)"], env, { shell: platform === "win32" });
+      const [ver, exe] = String((v && v.stdout) || "").trim().split(/\r?\n/);
+      return report(true, (ver || "3") + " " + (exe || p.cmd), { cmd: p.cmd, args: p.args, via: "present" });
+    }
+    if (warn) log(warn);
+    if (platform !== "win32") return report(false, "no python3 -- install it with the package manager (apt/dnf/brew install python3)", { via: "none" });
+    if (o.noInstall) return report(false, (warn ? "only the Microsoft Store alias stub" : "no Python 3") + " -- run: wkappbot-code install", { via: "none" });
+    let dir = "", via = "";
+    // 1. winget, per user
+    const wg = run("winget", ["install", "--id", "Python.Python.3.12", "-e", "--scope", "user", "--silent", "--accept-package-agreements", "--accept-source-agreements"], env, { shell: true });
+    log("python: winget install Python.Python.3.12 rc " + (wg ? wg.status : "?"));
+    dir = wingetPythonDir(env, exists, list);
+    if (dir) via = "winget";
+    // 2. the pinned embeddable zip
+    if (!dir) {
+      const target = join(home, ".wk-harness", "python"), zip = join(home, ".wk-harness", "python-embed.zip");
+      mkdirSync(target, { recursive: true });
+      const dl = run("curl", ["-fsSL", "--retry", "6", "--retry-delay", "5", "-m", "300", "-o", zip, EMBED.url], env);
+      if (!dl || dl.status !== 0) return report(false, "winget gave no Python and the download of " + EMBED.url + " failed (curl rc " + (dl ? dl.status : "?") + ")", { via: "none" });
+      const sum = createHash("sha256").update(read(zip)).digest("hex");
+      if (sum !== EMBED.sha256) return report(false, "the embeddable zip sha256 " + sum + " is not the pinned " + EMBED.sha256, { via: "none" });
+      const ux = run("tar", ["-xf", zip, "-C", target], env);
+      if (!ux || ux.status !== 0) return report(false, "could not unpack " + zip + " (tar rc " + (ux ? ux.status : "?") + ")", { via: "none" });
+      dir = target; via = "embed";
+    }
+    // 3. a python3.exe beside python.exe (winget and the zip ship only python.exe, so `python3` would still hit the
+    // WindowsApps stub), PYTHON_CMD for every later step, and the dir ahead of WindowsApps in this process and the user PATH
+    try { if (!exists(join(dir, "python3.exe"))) (o.copy || copyFileSync)(join(dir, "python.exe"), join(dir, "python3.exe")); } catch (e) { log("python: WARN no python3.exe beside python.exe (" + (e && e.message || e) + ")"); }
+    env.PYTHON_CMD = join(dir, "python.exe");
+    const k = pathKey(env);
+    env[k] = pathAheadOfWindowsApps(env[k], dir);
+    if (env !== process.env && o.env === undefined) { const pk = pathKey(process.env); process.env[pk] = pathAheadOfWindowsApps(process.env[pk], dir); }
+    if (!setUserPath(dir, run, env)) log("python: WARN could not write the user PATH; add " + dir + " ahead of WindowsApps");
+    // 4. re-probe the real exe by path
+    const exe = join(dir, "python.exe");
+    const v = run(exe, ["-c", "import sys;print(sys.version.split()[0])"], env);
+    if (v && v.status === 0 && /^3\./.test(String(v.stdout).trim())) return report(true, String(v.stdout).trim() + " " + exe, { cmd: exe, args: [], via });
+    return report(false, exe + " did not run (rc " + (v ? v.status : "?") + ")", { via });
+  } catch (e) {
+    return report(false, "unexpected: " + (e && e.message || e), { via: "none" });
+  }
+}

package/lib/python-pick.js

@@ -0,0 +1,38 @@
+// wkappbot-code lib/python-pick.js -- the ONE way the package chooses a Python 3 (owner order 2026-11-09).
+// A name on PATH is not a Python: on Windows %LOCALAPPDATA%\Microsoft\WindowsApps\python.exe and python3.exe are
+// Store app-execution-alias stubs. `command -v python3` finds them, yet running one prints "Python was not found
+// ... Microsoft Store" and exits 9009. So every candidate is RUN: python3, then python, then py -3, each with
+// -c "import sys;print(sys.version_info[0])", and accepted only on rc 0 with the output 3. A WindowsApps path, rc 9009
+// or the Store text marks a stub; pickPython reports it so the caller prints ONE warning (stubWarning).
+// Twin for sh: tools/wk-python-pick.sh (wk_python). Spec: wkappbot skill read harness-installer-owns-all-setup
+import { spawnSync } from "node:child_process";
+
+export const CANDIDATES = [["python3"], ["python"], ["py", "-3"]];
+const PROBE = ["-c", "import sys;print(sys.version_info[0])"];
+const STORE_RE = /Microsoft Store|WindowsApps|app execution alias/i;
+
+const realRun = (cmd, args, env) => spawnSync(cmd, args, { encoding: "utf8", env, timeout: 15000, shell: process.platform === "win32", windowsHide: true });
+
+// -> { cmd, args, stubs: [names] } ; cmd "" when no working Python 3 exists.
+export function pickPython(o = {}) {
+  const env = o.env || process.env, run = o.run || realRun, stubs = [];
+  if (env.PYTHON_CMD) {
+    const r = run(env.PYTHON_CMD, PROBE, env);
+    if (r && r.status === 0 && String(r.stdout || "").trim() === "3") return { cmd: env.PYTHON_CMD, args: [], stubs };
+  }
+  for (const [cmd, ...pre] of CANDIDATES) {
+    const r = run(cmd, [...pre, ...PROBE], env);
+    if (!r) continue;
+    const out = String(r.stdout || "") + String(r.stderr || "");
+    if (r.status === 0 && String(r.stdout || "").trim() === "3") return { cmd, args: pre, stubs };
+    if (r.status === 9009 || r.status === 49 || STORE_RE.test(out)) stubs.push(cmd);  // 49 = 9009 % 256 through a shell
+  }
+  return { cmd: "", args: [], stubs };
+}
+
+// The one WARN line for a Store stub, or "" when none was seen.
+export function stubWarning(stubs) {
+  if (!stubs || !stubs.length) return "";
+  return "WARN python: " + stubs.join(", ") + " is the Microsoft Store alias stub, not Python -- install Python 3, " +
+    "or turn the alias off under Settings > Apps > Advanced app settings > App execution aliases";
+}

package/lib/setup-run.js

@@ -133,13 +133,25 @@ export function printBanner({ home = homedir(), out = console.log, now = Date.no
 // cannot be started (not on PATH): the caller then prints the usage as before.
 // 0.3.12: `opencode` is looked up on PATH first, then beside this CLI (argv1 = the npm bin dir where `npm i -g opencode-ai`
 // linked it), so a global prefix that is not on the user PATH still opens it.
+// 0.3.19: the binary is resolved BY FILE before spawning. On Windows a shell spawn of a missing name returns status 1
+// with no r.error ("'opencode' is not recognized"), so the old error-only fallback never reached the sibling .cmd shim.
 export function launchOpenCode(env = process.env, argv1 = process.argv[1] || "") {
-  const run = (cmd, e) => spawnSync(cmd, [], { stdio: "inherit", shell: IS_WIN, env: e });
-  let r = run("opencode", env);
-  if (r.error && argv1) r = run("opencode", withPathFirst({ ...env }, dirname(argv1)));
+  const bin = findOpenCode(env, argv1 ? dirname(argv1) : "");
+  if (!bin) return null;
+  const shell = IS_WIN && /\.(?:cmd|bat)$/i.test(bin);
+  const r = spawnSync(shell ? '"' + bin + '"' : bin, [], { stdio: "inherit", shell, env: withPathFirst({ ...env }, dirname(bin)) });
   if (r.error) return null;
   return r.status ?? 1;
 }
+// The opencode file on PATH, else beside this CLI (the npm bin dir); "" when there is none anywhere.
+export function findOpenCode(env = process.env, besideDir = "") {
+  const names = IS_WIN ? ["opencode.cmd", "opencode.exe", "opencode"] : ["opencode"];
+  const k = Object.keys(env).find((x) => x.toLowerCase() === "path") || "PATH";
+  const dirs = String(env[k] || "").split(delimiter).filter(Boolean);
+  if (besideDir) dirs.push(besideDir);
+  for (const d of dirs) for (const n of names) { const p = join(d, n); if (existsSync(p)) return p; }
+  return "";
+}
 
 // The npm global bin dir (where `npm i -g` links binaries): prefix/bin, or the prefix itself on Windows. "" when unknown.
 export function globalBinDir(env = process.env) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkappbot-code",
-  "version": "0.3.17",
+  "version": "0.3.20",
   "description": "wkappbot-code -- Wisdom Kernel: the pinned OpenCode bridge plus the reflex harness plugin, the wkappbot core, the web harness and the latest public skills in one install",
   "type": "module",
   "scripts": {