wkappbot-code 0.3.35 → 0.3.39

package/bin/postinstall.js

@@ -23,7 +23,7 @@ import { homedir } from "node:os";
 import { appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { buildDone, files, globalBinDir, markRunning, parseDoctor, platformOf, selfTest, withPathFirst, writeDone } from "../lib/setup-run.js";
+import { buildDone, files, globalBinDir, parseDoctor, platformOf, selfTest, startWorker, withPathFirst, writeDone } from "../lib/setup-run.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const CLI = join(HERE, "wkappbot-code.js");
@@ -83,10 +83,8 @@ function main() {
     if (d.version === version() && (d.installRc ?? d.rc) === 0) { console.log("[wkappbot-code] already set up by " + d.version + " (" + DONE + ")"); return; }
   } catch {}
   mkdirSync(STATE, { recursive: true });
-  markRunning(homedir(), version());
-  const out = openSync(LOG, "a");
-  const c = spawn(process.execPath, [fileURLToPath(import.meta.url), "--run"], { detached: true, stdio: ["ignore", out, out], env: process.env, windowsHide: true });
-  c.unref();
+  // 0.3.39: startWorker records the WORKER's pid in postinstall.running (this parent exits at once)
+  startWorker({ script: fileURLToPath(import.meta.url), home: homedir(), version: version(), env: process.env });
   console.log("[wkappbot-code] " + (cloud ? "cloud VM detected: wiring the Claude Code harness in the background" : "setting up in the background (install, doctor, self-test)") +
     " (log: " + LOG + ", result: " + DONE + "); the first `wkappbot-code` run prints the summary");
 }

package/bin/wkappbot-code.js

@@ -51,7 +51,7 @@ 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";
+import { ensureOpencodeBin, files as setupFiles, findOpenCode, globalBinDir, launchOpenCode, printBanner, resumeIfWorkerDead, startWorker } from "../lib/setup-run.js";
 
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
@@ -364,6 +364,10 @@ function installPlugin(o, kih, kihSource) {
   // The plugin file exports ONLY the plugin (OpenCode calls every named export as one); its helpers ride beside it.
   for (const f of PLUGIN_LIBS) copyFileSync(join(PKG_DIR, "lib", f), join(cfg, "wkappbot-code", f));
   writeFileSync(join(cfg, "wkappbot-code", "package.json"), '{ "type": "module" }\n');
+  // 0.3.41: the session arm (plugin/wisdom-kernel.js) resumes a dead postinstall worker from this package root, which a
+  // global npm install does not place beside the plugin (lib/setup-run.js postinstallScriptIn).
+  mkdirSync(join(homedir(), ".wkappbot-code"), { recursive: true });
+  writeFileSync(join(homedir(), ".wkappbot-code", "package-dir"), PKG_DIR + "\n");
   const url = pathToFileURL(dest).href;
   const tmpl = JSON.parse(readFileSync(join(PKG_DIR, "opencode.json"), "utf8"));
   const target = o.project ? join(process.cwd(), "opencode.json") : join(cfg, "opencode.json");
@@ -430,6 +434,14 @@ function waitForSetupWorker() {
   log(alive() ? "background setup still running after 10 min; installing anyway" : "background setup finished; continuing");
 }
 
+// npm install -g opencode-ai at the pinned version; returns the rc (-1 when npm cannot start). A failure is logged, never silent.
+function npmInstallOpencode(log) {
+  const r = spawnSync("npm", ["install", "-g", "opencode-ai@" + OPENCODE_VERSION, "--no-audit", "--no-fund"], { shell: process.platform === "win32", stdio: "inherit" });
+  const rc = r.error ? -1 : (r.status ?? -1);
+  if (rc !== 0) log("opencode: npm install FAILED (rc " + rc + (r.error ? ", " + String(r.error.message).split("\n")[0] : "") + ") -- run: npm install -g opencode-ai@" + OPENCODE_VERSION);
+  return rc;
+}
+
 function install(o) {
   waitForSetupWorker();
   const prev = readState(o);
@@ -458,9 +470,10 @@ function install(o) {
     else {
       log("npm install -g opencode-ai@" + OPENCODE_VERSION + " (was: " + (have || "none") + ")");
       // 0.3.12: a failed OpenCode install (offline, no npm rights) must not abort the harness, plugin and config parts below.
-      try { execFileSync("npm", ["install", "-g", "opencode-ai@" + OPENCODE_VERSION, "--no-audit", "--no-fund"], { shell: process.platform === "win32",  stdio: "inherit" }); }
-      catch (e) { bad++; log("opencode: npm install FAILED (" + String(e.message).split("\n")[0] + ") -- run: npm install -g opencode-ai@" + OPENCODE_VERSION); }
+      if (npmInstallOpencode(log) !== 0) bad++;
     }
+    // 0.3.39 (2026-11-14): the bin must be LINKED, not the 479-byte placeholder; one retry, every rc logged (lib/setup-run.js)
+    if (!ensureOpencodeBin({ bin: findOpenCode(process.env, globalBinDir(process.env)), reinstall: () => npmInstallOpencode(log), log }).ok) bad++;
   }
   // 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) || [], (prev.aiClis && prev.aiClis.prefix) || "")
@@ -680,7 +693,11 @@ function doctor(o) {
     core = r.status === 0 ? (r.stdout || "").trim().split("\n")[0] : "";
     add("bin", !!core, core ? dest + "  " + core + (st.bin && st.bin.link ? "  (PATH link " + st.bin.link + ")" : "") : dest + " does not run", !!(st.bin && !st.bin.skipped));
   }
-  const pr = checkPath({ home: homedir(), env: process.env, platform: process.platform }); add("path", pr.ok, pr.text, true);
+  const pr = checkPath({ home: homedir(), env: process.env, platform: process.platform });
+  // --no-bin: this install wrote no bare-name link, so the path row is a skip whatever core file sits at dest, as the bin row is
+  // (a core at dest that is not on PATH is only a FAIL when the install owns the links, i.e. bin is not skipped)
+  if (!pr.ok && st.bin && st.bin.skipped) add("path", false, pr.text, false, true);
+  else add("path", pr.ok, pr.text, true);
   // kih-hook: the harness the plugin calls and its verdict road; no pwsh and no lite = NO verdict = FAIL whatever the install mode.
   const k = (entry && Array.isArray(entry) && entry[1] && entry[1].kihDir) || kihDir(o);
   const hk = hasHook(k);
@@ -742,6 +759,14 @@ if (["install", "doctor", "config"].includes(o.cmd) && !o.update) {
   if (nv && (o.autoUpdate || process.env.WKAPPBOT_CODE_AUTO_UPDATE === "1")) upd();
 }
 // The one-line result of the automatic post-install setup (lib/setup-run.js), once; not for the worker's own children.
+// 0.3.39 self-heal (2026-11-14): a background worker that died before postinstall.done is started again here, on every run
+// (doctor and doctor --fix included). The worker's own children and the opt-out switch never arm it.
+if (process.env.WKAPPBOT_CODE_SETUP_WORKER !== "1" && process.env.WKAPPBOT_CODE_NO_POSTINSTALL !== "1" && !["--version", "-v", "version"].includes(o.cmd)) {
+  try {
+    const rs = resumeIfWorkerDead({ home: homedir(), runSetup: () => startWorker({ script: join(PKG_DIR, "bin", "postinstall.js"), home: homedir(), version: PKG.version }) });
+    if (rs.resumed) log("background setup did not finish (" + rs.reason + "); started it again -- log: " + setupFiles(homedir()).log);
+  } catch {}
+}
 if (!["--version", "-v", "version", "uninstall"].includes(o.cmd) && process.env.WKAPPBOT_CODE_SETUP_WORKER !== "1") { try { printBanner(); } catch {} }
 // Bare `wkappbot-code`: open OpenCode (its start screen); no opencode on PATH falls through to the usage below.
 if (process.argv.length <= 2 && o.cmd === "help") { const rc = launchOpenCode(); if (rc !== null) process.exit(rc); }

package/lib/doctor-path.js

@@ -40,6 +40,13 @@ export function loginShell(h, env, bin) {
   }
 }
 
+// The environment a fresh cmd.exe is started with on win32. It carries the registry PATH only, plus PATHEXT, so the
+// .cmd shims the installer writes always resolve by bare name (PATHEXT is never left to cmd's built-in default).
+function winShellEnv(h, env, winPath) {
+  // profile-mark: winShellEnv
+  return { SystemRoot: env.SystemRoot || "C:\\Windows", USERPROFILE: h, HOME: h, PATHEXT: env.PATHEXT || ".COM;.EXE;.BAT;.CMD", PATH: winPath };
+}
+
 // checkPath({home, env, platform, readRegPath, runShell}) -> {ok, text}
 //   home        HOME (or USERPROFILE on Windows) the fresh shell starts in
 //   env         carries the OS persistent PATH (PATH key; default process.env)
@@ -61,7 +68,7 @@ export function checkPath({ home, env = process.env, platform = process.platform
       try {
         out = execFileSync("cmd.exe", ["/d", "/s", "/c", `${bin} --version`], {
           encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60000,
-          env: { SystemRoot: env.SystemRoot || "C:\\Windows", USERPROFILE: h, HOME: h, PATH: winPath },
+          env: winShellEnv(h, env, winPath),
         });
       } catch (e) {
         out = typeof e.stdout === "string" ? e.stdout : "";

package/lib/plugin-files.js

@@ -3,4 +3,6 @@
 // copied file must be in this list: a missing one made the whole plugin fail to load (0.3.34, SDK run 43333160662:
 // ERR_MODULE_NOT_FOUND, every guard dead). bin/prepack.js refuses to pack when an import is not listed, and
 // selftest-pluginlayout.mjs imports the plugin from an installed layout. Spec: wkappbot skill read agent-harness-landscape-2026-howto
-export const PLUGIN_LIBS = ["wk-hook.js", "rmguard.js"];
+// 0.3.40: the session arm (wisdom-kernel.js session.created) resumes a dead postinstall worker through lib/setup-run.js,
+// whose chain is setup-run -> fslocked -> lockwait -> holders; each rides beside the plugin like the others.
+export const PLUGIN_LIBS = ["wk-hook.js", "rmguard.js", "setup-run.js", "fslocked.js", "lockwait.js", "holders.js"];

package/lib/setup-run.js

@@ -8,7 +8,8 @@
 // Files in ~/.wkappbot-code: postinstall.log, postinstall.running (worker alive), postinstall.done, postinstall.seen.
 // A user's own settings.json entries are the installer's job to keep (wkappbot-code.js install); this module only reads.
 // Spec: wkappbot skill read agent-harness-landscape-2026-howto
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, openSync, statSync, writeSync } from "node:fs";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "./fslocked.js";
 import { homedir, tmpdir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
@@ -88,6 +89,125 @@ export function writeDone(home, rec) {
   renameSync(tmp, f.done);   // the done file appears whole or not at all (the selftest polls for it)
   rmSync(f.running, { force: true });
 }
+// Starts the detached worker (bin/postinstall.js --run) and records ITS pid in postinstall.running. The parent used to record
+// its own pid, which exits at once, so a live worker looked dead. (0.3.39, 2026-11-14)
+export function startWorker({ script, home = homedir(), version, env = process.env, spawnFn = spawn }) {
+  const f = files(home);
+  mkdirSync(f.dir, { recursive: true });
+  rmSync(f.done, { force: true });   // the old verdict belongs to the old install
+  const out = openSync(f.log, "a");
+  const c = spawnFn(process.execPath, [script, "--run"], { detached: true, stdio: ["ignore", out, out], env, windowsHide: true });
+  if (c && c.unref) c.unref();
+  writeFileSync(f.running, JSON.stringify({ version, at: new Date().toISOString(), pid: (c && c.pid) || 0 }) + "\n");
+  return c;
+}
+// A pid that answers signal 0 is alive (EPERM = alive under another user). 0 or junk is never alive.
+export function pidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try { process.kill(n, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+// Self-heal (0.3.39, 2026-11-14): a worker that died before postinstall.done leaves postinstall.running naming a dead pid,
+// and nothing ever retried. Every wkappbot-code run (doctor included) calls this: a dead pid with no done file runs setup
+// again through runSetup (production: startWorker). Returns {resumed, pid, reason}.
+// ONE SHARED LOCK (0.3.42, 2026-11-15): the shell arm pi_resume in tools/wkharness-lite.sh takes the same file,
+// ~/.wkappbot-code/resume.lock, with noclobber. Whoever holds it re-reads postinstall.running UNDER the lock, so a second
+// starter sees the first worker's live pid and does nothing. A lock whose holder pid is dead is reclaimed.
+export const resumeLockFile = (home = homedir()) => join(stateDir(home), "resume.lock");
+const RESUME_LOCK_STALE_MS = 60 * 1000;   // an empty lock file (writer died before its pid) is reclaimed after this
+function createResumeLock(p) {
+  try {
+    const fd = openSync(p, "wx");
+    try { writeSync(fd, String(process.pid) + "\n"); } finally { closeSync(fd); }
+    return true;
+  } catch (e) { if (e.code === "EEXIST") return false; throw e; }
+}
+export function takeResumeLock(home = homedir(), alive = pidAlive) {
+  const p = resumeLockFile(home);
+  try { mkdirSync(stateDir(home), { recursive: true }); } catch {}
+  try { if (createResumeLock(p)) return true; } catch { return false; }
+  let holder = "";
+  try { holder = String(readFileSync(p, "utf8")).trim(); } catch { return false; }
+  if (/^[0-9]+$/.test(holder)) { if (alive(Number(holder))) return false; }
+  else if (Date.now() - statSync(p).mtimeMs < RESUME_LOCK_STALE_MS) return false;
+  rmSync(p, { force: true });
+  try { return createResumeLock(p); } catch { return false; }
+}
+export function releaseResumeLock(home = homedir()) { try { rmSync(resumeLockFile(home), { force: true }); } catch {} }
+export function resumeIfWorkerDead({ home = homedir(), runSetup, alive = pidAlive } = {}) {
+  const f = files(home);
+  if (!takeResumeLock(home, alive)) return { resumed: false, pid: 0, reason: "resume lock held by another starter" };
+  try {
+    const running = readJson(f.running);   // read AFTER taking the lock: the lock holder may have just written the new pid
+    if (!running) return { resumed: false, pid: 0, reason: "no postinstall.running" };
+    if (existsSync(f.done)) return { resumed: false, pid: 0, reason: "postinstall.done exists" };
+    const pid = Number(running.pid);
+    if (!(pid > 0)) return { resumed: false, pid: 0, reason: "postinstall.running names no pid" };
+    if (alive(pid)) return { resumed: false, pid, reason: "worker pid " + pid + " is alive" };
+    runSetup();   // startWorker writes the new worker's pid into postinstall.running before the lock is released
+    return { resumed: true, pid, reason: "worker pid " + pid + " is dead and postinstall.done is absent" };
+  } finally { releaseResumeLock(home); }
+}
+// Session arm (0.3.40, 2026-11-14): called once per OpenCode session start by plugin/wisdom-kernel.js (event session.created).
+// The same self-heal as the CLI dispatch, but fail-open: it never throws, and the worker is detached (startWorker), so the
+// session start waits for nothing. The CLI's skip flags apply: WKAPPBOT_CODE_SETUP_WORKER=1 (a worker's own child) and
+// WKAPPBOT_CODE_NO_POSTINSTALL=1 (the opt-out). runSetup is injectable for selftest-resume.mjs (s5a-s5e).
+export function sessionStartResume({ home = homedir(), env = process.env, script = "", version = "", runSetup, spawnFn } = {}) {
+  try {
+    if (env.WKAPPBOT_CODE_SETUP_WORKER === "1" || env.WKAPPBOT_CODE_NO_POSTINSTALL === "1") return { resumed: false, pid: 0, reason: "skip flag set" };
+    const ver = version || (script && (readJson(join(dirname(script), "..", "package.json")) || {}).version) || "";
+    const run = runSetup || (script ? () => startWorker({ script, home, version: ver, env, spawnFn }) : null);
+    if (!run) return { resumed: false, pid: 0, reason: "no postinstall script" };
+    return resumeIfWorkerDead({ home, runSetup: run });
+  } catch (e) { return { resumed: false, pid: 0, reason: "error: " + String(e && e.message).slice(0, 120) }; }
+}
+// The worker script: <kih>/wkappbot-code/bin/postinstall.js when the harness checkout carries it, else the package root the
+// installer recorded in ~/.wkappbot-code/package-dir (0.3.41: a normal npm global install has no checkout). "" when neither exists.
+export function postinstallScriptIn(kihDir, home = homedir()) {
+  const inKih = kihDir ? join(kihDir, "wkappbot-code", "bin", "postinstall.js") : "";
+  if (inKih && existsSync(inKih)) return inKih;
+  let pkg = "";
+  try { pkg = String(readFileSync(join(stateDir(home), "package-dir"), "utf8")).trim(); } catch {}
+  const p = pkg ? join(pkg, "bin", "postinstall.js") : "";
+  return p && existsSync(p) ? p : "";
+}
+
+// The opencode-ai npm package links a 479-byte placeholder bin that its own postinstall replaces with the real binary.
+// The step is LINKED when the file is over OPENCODE_MIN_BYTES or `--version` exits 0. Otherwise npm install runs ONCE more
+// (reinstall) and every size and rc goes to log, never silently. Returns {ok, retries, size, rc}. (0.3.39, 2026-11-14)
+export const OPENCODE_MIN_BYTES = 4096;
+// A Windows npm bin is a .cmd shim that node cannot spawn without a shell, so the probe returned rc 1
+// (SDK run 43689775714, 2026-11-15). The shell flag is set only for .cmd/.bat on win32.
+export function versionSpawnPlan(bin, isWin = IS_WIN) {
+  const shell = isWin && /\.(?:cmd|bat)$/i.test(bin);
+  return { file: shell ? '"' + bin + '"' : bin, shell };
+}
+function defaultVersionRc(bin) {
+  const plan = versionSpawnPlan(bin);
+  const r = spawnSync(plan.file, ["--version"], { encoding: "utf8", timeout: 30000, shell: plan.shell, stdio: ["ignore", "pipe", "ignore"] });
+  return r.status ?? 1;
+}
+export function ensureOpencodeBin({ bin, reinstall, log = () => {}, versionRc = defaultVersionRc, minBytes = OPENCODE_MIN_BYTES }) {
+  const check = () => {
+    const size = bin && existsSync(bin) ? statSync(bin).size : -1;
+    const rc = size >= 0 ? versionRc(bin) : -1;
+    return { ok: size > minBytes || rc === 0, size, rc };
+  };
+  const describe = (s) => "bin " + (bin || "(none)") + " size " + s.size + ", --version rc " + s.rc + (s.ok ? " -- linked" : " -- NOT linked (placeholder or missing)");
+  let s = check();
+  log("opencode " + describe(s));
+  let retries = 0;
+  if (!s.ok) {
+    retries = 1;
+    const rc = reinstall();
+    log("opencode: retry 1 of 1: npm install rc " + rc);
+    s = check();
+    log("opencode after retry: " + describe(s));
+  }
+  if (!s.ok) log("opencode: FAIL -- the opencode bin is still not linked after the retry; run: npm install -g opencode-ai@<pinned version>");
+  return { ok: s.ok, retries, size: s.size, rc: s.rc };
+}
+
 export function buildDone({ version, installRc, doctor, selftest, env = process.env }) {
   return { version, installRc, rc: installRc, doctor: { pass: doctor.pass, warn: doctor.warn, fail: doctor.fail, skip: doctor.skip },
     selftest: { n: selftest.n, m: selftest.m }, platform: platformOf(env), at: new Date().toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkappbot-code",
-  "version": "0.3.35",
+  "version": "0.3.39",
   "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": {

package/plugin/wisdom-kernel.js

@@ -82,6 +82,14 @@ export const WisdomKernel = async (ctx = {}, options = {}) => {
         if (!event) return;
         if (event.type === "session.created") {
           const sid = event.properties && event.properties.info && event.properties.info.id;
+          // 0.3.40 session arm: a postinstall worker that died before postinstall.done is started again, detached and fail-open
+          // (lib/setup-run.js sessionStartResume; the CLI dispatch does the same on every run).
+          try {
+            let S;
+            try { S = await import("./setup-run.js"); } catch { S = await import("../lib/setup-run.js"); }
+            const os = await import("node:os");
+            S.sessionStartResume({ home: os.homedir(), env: process.env, script: S.postinstallScriptIn(k) });
+          } catch {}
           await H.runHook("session", { hook_event_name: "SessionStart", session_id: sid, cwd, source: "startup", agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
         } else if (event.type === "session.idle") {
           const sid = event.properties && event.properties.sessionID;