wkappbot-code 0.3.33 → 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");
@@ -52,11 +52,15 @@ async function runWorker() {
   const env = withPathFirst({ ...process.env, WKAPPBOT_CODE_NO_UPDATE_CHECK: "1", WKAPPBOT_CODE_SETUP_WORKER: "1" }, globalBinDir(process.env));
   stamp("worker start: node " + args.join(" "));
   const out = openSync(LOG, "a");
-  const installRc = await new Promise((res) => {
+  const runInstall = () => new Promise((res) => {
     const c = spawn(process.execPath, args, { stdio: ["ignore", out, out], env });
     c.on("error", () => res(-1));
     c.on("close", (code) => res(code ?? -1));
   });
+  let installRc = await runInstall();
+  // a permanent file lock makes install exit 75 (lib/lockwait.js EXIT_LOCKED): retry three times, then say what to do and go on (the worker exits 0)
+  for (let i = 1; i <= 3 && installRc === 75; i++) { stamp("install rc 75 (a file is locked); retry " + i + " of 3"); installRc = await runInstall(); }
+  if (installRc === 75) stamp("install is still locked: close the program holding the file, then run wkappbot-code install again (run wkappbot-code install again)");
   stamp("install rc " + installRc + "; doctor");
   const dr = spawnSync(process.execPath, [CLI, "doctor"], { encoding: "utf8", env, timeout: 300000 });
   const dtext = (dr.stdout || "") + (dr.stderr || "");
@@ -79,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/prepack.js

@@ -12,6 +12,7 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFile
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { PLUGIN_LIBS } from "../lib/plugin-files.js";
 
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const KIH = resolve(PKG_DIR, "..");
@@ -20,6 +21,15 @@ const PKG = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
 const die = (m) => { console.error("[wkappbot-code prepack] " + m); process.exit(1); };
 const sh = (p) => process.platform === "win32" ? p.replace(/\\/g, "/") : p;
 
+// Every relative import of a file install copies beside the plugin must be copied too (0.3.34: wk-hook.js imported ./rmguard.js, install copied wk-hook.js alone,
+// ERR_MODULE_NOT_FOUND, every guard dead). Fail BEFORE a tarball exists. Spec: wkappbot skill read agent-harness-landscape-2026-howto
+{
+  const flat = new Set(["wisdom-kernel.js", ...PLUGIN_LIBS]);
+  for (const [d, f] of [["plugin", "wisdom-kernel.js"], ...PLUGIN_LIBS.map((n) => ["lib", n])]) {
+    const src = readFileSync(join(PKG_DIR, d, f), "utf8");
+    for (const m of src.matchAll(/(?:\bfrom\s+|\bimport\s*\(\s*)["'](\.\/[^"']+)["']/g)) if (!flat.has(m[1].slice(2))) die(d + "/" + f + " imports " + m[1] + ", which install does not copy beside the plugin (add it to lib/plugin-files.js)");
+  }
+}
 let stage = process.env.WKAPPBOT_CODE_HARNESS_STAGE || "";
 let tmp = "";
 const copy = join(KIH, "tools", "wk-harness-min-copy.sh");

package/bin/wkappbot-code.js

@@ -37,7 +37,7 @@ import { createHash } from "node:crypto";
 import {
   copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync,
   realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync,
-} from "node:fs";
+} from "../lib/fslocked.js";
 import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -45,12 +45,13 @@ import { quietCheck, runUpdate, updateRow } from "../lib/update.js"; import { rm
 import { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
 import { aiCliRows, installAiClis, removeAiClis } from "../lib/ai-clis.js";
 import { providerCli, providerRow } from "../lib/providers.js";
+import { EXIT_LOCKED, isLockError } from "../lib/lockwait.js"; import { PLUGIN_LIBS } from "../lib/plugin-files.js"; import { installLockMd, removeLockMd } from "../lib/lock-md.js";
 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";
+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"));
@@ -361,8 +362,12 @@ function installPlugin(o, kih, kihSource) {
   const dest = join(cfg, "wkappbot-code", "wisdom-kernel.js");
   copyFileSync(join(PKG_DIR, "plugin", "wisdom-kernel.js"), dest);
   // The plugin file exports ONLY the plugin (OpenCode calls every named export as one); its helpers ride beside it.
-  copyFileSync(join(PKG_DIR, "lib", "wk-hook.js"), join(cfg, "wkappbot-code", "wk-hook.js"));
+  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");
@@ -429,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);
@@ -457,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) || "")
@@ -481,7 +495,8 @@ function install(o) {
   // the compressed allow list (lib/allow-compact.js): five harness-own prefixes, never the wide rows learned on the owner's seats
   st.allows = (o.harness && o.allows) ? addAllows(SETTINGS(), prev.allows || {}, log) : (prev.allows || { skipped: true });
   // the standard global rules for a fresh machine (lib/starter-md.js): only where the user has no ~/.claude/CLAUDE.md
-  st.starterMd = o.harness ? installStarterMd({ claudeDir: dirname(SETTINGS()), pkgDir: PKG_DIR, prev: prev.starterMd, log }) : { skipped: true };  // Global pre-push dispatcher (owner 2026-11-06): the push-owner gate runs in every repo, then the repo's own hooks.
+  st.starterMd = o.harness ? installStarterMd({ claudeDir: dirname(SETTINGS()), pkgDir: PKG_DIR, prev: prev.starterMd, log }) : { skipped: true };
+  st.lockMd = o.harness ? installLockMd({ claudeDir: dirname(SETTINGS()), pkgDir: PKG_DIR, prev: prev.lockMd, log }) : { skipped: true };  // the study-lock rules of the installed sources, in ~/.claude/REFLEX.md (lib/lock-md.js)  // Global pre-push dispatcher (owner 2026-11-06): the push-owner gate runs in every repo, then the repo's own hooks.
   // A user's own absolute global core.hooksPath is kept (the script WARNs). Skipped with --no-harness.
   st.pushGate = { skipped: true };
   if (o.harness && kih && existsSync(join(kih, "tools", "wk-global-hooks.sh"))) {
@@ -576,7 +591,7 @@ function uninstall(o) {
   }
   // 3b. the ~/.local/bin/wkappbot link: removed ONLY when it points at the core this install placed (the core file stays)
   const core = (st.bin && st.bin.dest) || binDest(o);
-  removeStarterMd(st.starterMd, log); removeStaleWkskill(HARNESS_LINKS(), log);  // an older harness install's counterfeit wkskill link (SDK e2e: local-bin=wkskill)
+  removeStarterMd(st.starterMd, log); removeLockMd(st.lockMd, log); removeStaleWkskill(HARNESS_LINKS(), log);  // an older harness install's counterfeit wkskill link (SDK e2e: local-bin=wkskill)
   let linkRemoved = "";
   for (const p of new Set(shimCandidates().concat([join(homedir(), ".local", "bin", "wkappbot")]))) {
     if (!isSymlink(p) || (st.shims || []).includes(p)) continue;
@@ -660,7 +675,7 @@ function doctor(o) {
   const v = opencodeVersion();
   add("opencode", v === OPENCODE_VERSION, v ? v + (v === OPENCODE_VERSION ? "" : " (pinned " + OPENCODE_VERSION + ")") : "not on PATH", false);
   const pdest = join(cfg, "wkappbot-code", "wisdom-kernel.js");
-  add("plugin", existsSync(pdest) && existsSync(join(cfg, "wkappbot-code", "wk-hook.js")), pdest + " + wk-hook.js", true);
+  add("plugin", existsSync(pdest) && PLUGIN_LIBS.every((f) => existsSync(join(cfg, "wkappbot-code", f))), pdest + " + " + PLUGIN_LIBS.join(" + "), true);
   let entry = null;
   try { entry = (JSON.parse(readFileSync(join(cfg, "opencode.json"), "utf8")).plugin || []).find((p) => String(Array.isArray(p) ? p[0] : p).includes("wisdom-kernel")); } catch {}
   add("config", !!entry, join(cfg, "opencode.json"), true);
@@ -678,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);
@@ -740,13 +759,21 @@ 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); }
 switch (o.cmd) {
   case "--version": case "-v": case "version":
     console.log("wkappbot-code " + PKG.version + " (opencode-ai " + OPENCODE_VERSION + ")"); process.exit(0);
-  case "install": process.exit(install(o));
+  case "install": { let rc; try { rc = install(o); } catch (e) { if (e && (e.code === "ELOCKBUDGET" || isLockError(e))) { console.error(e.message + "\nwkappbot-code: a file is held by another program; close it and run wkappbot-code install again"); rc = EXIT_LOCKED; } else throw e; } process.exit(rc); }
   case "uninstall": process.exit(uninstall(o));
   case "doctor": process.exitCode = doctor(o); break;
   case "update": process.exit(upd());

package/lib/allow-compact.js

@@ -4,7 +4,7 @@
 // are far too wide for a stranger's machine. A fresh install gets ONLY these five read-or-own-store prefixes. Every call
 // still meets the harness PreToolUse hook first, and a hook refusal beats an allow rule, so an entry here skips the
 // permission prompt, never the harness. Uninstall removes exactly the entries this install added.
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "./fslocked.js";
 import { dirname } from "node:path";
 import { readSettings } from "./hook-wire.js";
 
@@ -13,6 +13,9 @@ export const COMPACT_ALLOWS = [
   "Bash(wkappbot file read *)",    // read-only file view
   "Bash(wk-verify)",               // live hook check, no arguments
   "Bash(wkappbot-code doctor)",    // read-only health table
+  "Bash(wkappbot-code install)",   // what postinstall and the user run to set up (owner 2026-11-13: refused or prompted every time)
+  "Bash(wkappbot-code install *)", // the same with flags
+  "Bash(node */wkappbot-code/bin/postinstall.js*)",  // the postinstall entry npm runs
 ];
 
 // prev: the state recorded by the last install ({ added, madeAllow, madePerms }); a reinstall keeps owning what it added.

package/lib/doctor-path.js

@@ -4,7 +4,7 @@
 // Windows: a new cmd.exe whose PATH is machine PATH + user PATH read from the registry.
 // PASS only when each bare-name run prints "wkappbot v". Any other outcome is FAIL for that name.
 import { execFileSync } from "node:child_process";
-import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, symlinkSync, unlinkSync, writeFileSync } from "./fslocked.js";
 import { dirname, join, resolve } from "node:path";
 
 const OK_MARK = "wkappbot v";
@@ -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/fslocked.js

@@ -0,0 +1,18 @@
+// fslocked.js -- node:fs for the install road: every name of node:fs, with the writers wrapped in lockRetry, so a file another
+// process holds (EBUSY, EPERM, EACCES, ETXTBSY) is waited for, then reported as ELOCKBUDGET, instead of failing at once.
+// The modules an install runs import from here instead of "node:fs" (owner 2026-11-13). Spec: wkappbot skill read harness-installer-owns-all-setup
+import * as real from "node:fs";
+import { lockRetry } from "./lockwait.js";
+
+export * from "node:fs";
+
+const wrap = (name, labelAt = 0) => (...a) => lockRetry(() => real[name](...a), { label: String(a[labelAt]) });
+export const writeFileSync = wrap("writeFileSync");
+export const appendFileSync = wrap("appendFileSync");
+export const mkdirSync = wrap("mkdirSync");
+export const copyFileSync = wrap("copyFileSync", 1);
+export const renameSync = wrap("renameSync", 1);
+export const symlinkSync = wrap("symlinkSync", 1);
+export const unlinkSync = wrap("unlinkSync");
+export const rmSync = wrap("rmSync");
+export const chmodSync = wrap("chmodSync");

package/lib/hook-wire.js

@@ -10,7 +10,7 @@
 // stays verbatim, and every lite arm is present once. The web installer calls it through the CLI form below when it has
 // node but no python3:   node hook-wire.js wire SETTINGS LITE
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "./fslocked.js";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { pickPython, stubWarning } from "./python-pick.js";

package/lib/lock-md.js

@@ -0,0 +1,56 @@
+// lock-md.js -- the study-lock rules for the installed harness sources, laid where the installed hooks read them (owner 2026-11-13
+// via the spokesman: "the md files that protect the harness sources are not installed, not in the global md either").
+// The JS study lock reads ~/.claude/CLAUDE.md and ~/.claude/REFLEX.md besides the repo's own; this install writes the rules of
+// templates/harness-locks.md into ~/.claude/REFLEX.md between two markers. A REFLEX.md the user already has keeps every byte
+// of its own text: the block is appended once and refreshed in place. Uninstall removes exactly the block, and the file when
+// the install made it and nothing else is left. Spec: wkappbot skill read harness-installer-owns-all-setup
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "./fslocked.js";
+import { dirname, join } from "node:path";
+
+export const BEGIN = "<!-- wk-harness-locks:begin (managed by wkappbot-code install; edit outside this block) -->";
+export const END = "<!-- wk-harness-locks:end -->";
+
+const block = (tpl) => BEGIN + "\n" + tpl.replace(/\s+$/, "") + "\n" + END + "\n";
+const cut = (text) => {
+  const a = text.indexOf(BEGIN), b = text.indexOf(END);
+  return a >= 0 && b > a ? { before: text.slice(0, a), after: text.slice(b + END.length).replace(/^\r?\n/, ""), has: true } : { before: text, after: "", has: false };
+};
+
+// o: { claudeDir, pkgDir, prev ({ path, created }), log } -> { path, created, action }
+export function installLockMd(o) {
+  const log = o.log || (() => {});
+  const path = join(o.claudeDir, "REFLEX.md");
+  const tplPath = join(o.pkgDir, "templates", "harness-locks.md");
+  if (!existsSync(tplPath)) { log("lock-md: WARN " + tplPath + " is missing from this package"); return { path, action: "missing-template" }; }
+  const mine = block(readFileSync(tplPath, "utf8"));
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, mine);
+    log("lock-md: wrote the harness study-lock rules to " + path);
+    return { path, created: true, action: "written" };
+  }
+  const cur = readFileSync(path, "utf8"), c = cut(cur);
+  const created = !!(o.prev && o.prev.created);
+  if (c.has) {
+    const next = c.before + mine + c.after;
+    if (next === cur) return { path, created, action: "current" };
+    writeFileSync(path, next);
+    log("lock-md: refreshed the harness study-lock block in " + path);
+    return { path, created, action: "refreshed" };
+  }
+  writeFileSync(path, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + (cur === "" ? "" : "\n") + mine);
+  log("lock-md: appended the harness study-lock block to your " + path + " (your text is untouched)");
+  return { path, created: false, action: "appended" };
+}
+
+// Removes the block; a file this install made is deleted when nothing but the block was in it.
+export function removeLockMd(rec, log = () => {}) {
+  if (!rec || !rec.path || !existsSync(rec.path)) return false;
+  const cur = readFileSync(rec.path, "utf8"), c = cut(cur);
+  if (!c.has) return false;
+  const rest = (c.before.replace(/\s+$/, "") + (c.before.trim() && c.after.trim() ? "\n\n" : "") + c.after.replace(/^\s+/, ""));
+  if (rec.created && !rest.trim()) { rmSync(rec.path, { force: true }); log("lock-md: removed " + rec.path + " (it held only the harness block)"); return true; }
+  writeFileSync(rec.path, c.before.trim() ? (c.before.replace(/\s+$/, "") + (c.after.trim() ? "\n\n" + c.after.replace(/^\s+/, "") : "\n")) : c.after.replace(/^\s+/, ""));
+  log("lock-md: removed the harness study-lock block from " + rec.path + " (your text kept)");
+  return true;
+}

package/lib/lockwait.js

@@ -0,0 +1,36 @@
+// lockwait.js -- run a file operation, and when another process holds the file (EBUSY, EPERM, EACCES, ETXTBSY) wait for it to
+// leave instead of failing at once (owner 2026-11-13 via the spokesman: install and postinstall failed on a locked file every time).
+//   lockRetry(fn, { label, holderDir, budgetMs = 30000, firstMs = 250 })
+//   - the wait starts at 250 ms and doubles, through holders.js waitForHolders when holderDir names the harness folder
+//   - ONE untruncated "LOCKED <label>: <code> ..." line goes to the log, however many retries follow
+//   - past the budget the error has code ELOCKBUDGET (the message holds the whole label and the last OS code)
+//   - any other error is thrown at once
+// lib/fslocked.js puts this under every file write an install makes; bin/wkappbot-code.js turns ELOCKBUDGET into exit 75.
+// Spec: wkappbot skill read harness-installer-owns-all-setup
+import { waitForHolders } from "./holders.js";
+
+export const LOCK_CODES = new Set(["EBUSY", "EPERM", "EACCES", "ETXTBSY"]);
+export const EXIT_LOCKED = 75;
+export const isLockError = (e) => !!e && LOCK_CODES.has(e.code);
+const sleepMs = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* no wait available */ } };
+const envBudget = () => { const n = Number(process.env.WKAPPBOT_CODE_LOCK_BUDGET_MS); return Number.isFinite(n) && n >= 0 && process.env.WKAPPBOT_CODE_LOCK_BUDGET_MS !== undefined ? n : 30000; };
+
+export function lockRetry(fn, opts = {}) {
+  const budget = opts.budgetMs ?? envBudget(), nap = opts.sleep || sleepMs, log = opts.log || ((s) => console.error(s));
+  const label = String(opts.label || "file"), wait = opts.waitForHolders || waitForHolders;
+  let delay = opts.firstMs ?? 250, waited = 0, said = false, last = null;
+  for (;;) {
+    try { return fn(); } catch (e) {
+      if (!isLockError(e)) throw e;
+      last = e;
+      if (waited >= budget) break;
+      if (!said) { log(`LOCKED ${label}: ${e.code} -- another process holds it; waiting up to ${Math.round(budget / 1000)} s`); said = true; }
+      const step = Math.min(delay, budget - waited);
+      if (opts.holderDir) { wait(opts.holderDir, { maxMs: step, gap: Math.min(50, step), sleep: nap }); } else nap(step);
+      waited += step; delay *= 2;
+    }
+  }
+  const err = new Error(`LOCKED ${label}: ${last.code} still held after ${waited} ms (budget ${budget} ms)`);
+  err.code = "ELOCKBUDGET"; err.cause = last; err.lockedLabel = label;
+  throw err;
+}

package/lib/plugin-files.js

@@ -0,0 +1,8 @@
+// plugin-files.js -- the helper files that ride BESIDE the OpenCode plugin in <config>/wkappbot-code/ (install copies each of
+// lib/<name> there). wisdom-kernel.js imports ./wk-hook.js, and wk-hook.js imports ./rmguard.js, so EVERY relative import of a
+// 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
+// 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/providers.js

@@ -3,7 +3,7 @@
 // ("{env:VAR}"); a key or a URL typed where a name belongs is refused and never echoed, and no env var value is read
 // except by the doctor row, which only checks that a variable is set and prints its name.
 // Pure build/merge/remove functions first, then the CLI body. Spec: wkappbot skill read agent-harness-landscape-2026
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "./fslocked.js";
 import { dirname, join } from "node:path";
 
 export const NPM = "@ai-sdk/openai-compatible";

package/lib/python-acquire.js

@@ -10,7 +10,7 @@
 // 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, unlinkSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from "./fslocked.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { pickPython, stubWarning } from "./python-pick.js";

package/lib/rmguard.js

@@ -0,0 +1,128 @@
+// wkappbot-code/lib/rm-guard.js -- the rm rule every harness family shares (owner 2026-11-12: rm was not blocked; block
+// wildcards and folders, make each file be named, check each file's protection state). JS home of the rule; the sh twin
+// is tools/wkharness-lite.sh rk_eval/rk_rm, and both run the one case table tools/wkjs/rm-guard.cases.txt
+// (tools/wkjs/rm-guard.selftest.js). Spec: wkappbot skill read harness-rm-guard-howto
+//   REFUSED: a recursive delete (rm -r, rmdir -r, find -delete, Remove-Item -Recurse, del /s); a glob character in an rm
+//   target; an expansion ($, backtick) or xargs rm; a named file that is git-tracked with uncommitted changes, on the
+//   harness protected list, or read-only/immutable. EXEMPT: scratch (repo .tmp/, /tmp, TMPDIR, node_modules/ dist/ build/
+//   .bak/ inside the repo). A clean tracked file may go (git restores it).
+import fs from "node:fs";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+
+const REMEDY = "name each file explicitly, or move scratch work under .tmp/";
+const SCRATCH_SEG = new Set([".tmp", "node_modules", "dist", "build", ".bak"]);
+const PROTECTED_BASE = /^(CLAUDE\.md|REFLEX\.md|HANDOFF\.md|settings(\.local)?\.json|[^/]*\.skill\.json)$/i;
+const PROTECTED_DIR = /(^|\/)(\.claude\/hooks|\.githooks)(\/|$)/i;
+
+// Slash form, ".." and "." folded away; relative names resolve against cwd. Returns "" for an escape past the root.
+function norm(p, cwd) {
+  let s = String(p).replace(/\\+/g, "/");
+  if (!/^([A-Za-z]:)?\//.test(s)) s = String(cwd || ".").replace(/\\+/g, "/").replace(/\/+$/, "") + "/" + s;
+  const m = /^([A-Za-z]:)?(\/)?/.exec(s);
+  const head = m[0];
+  const out = [];
+  for (const seg of s.slice(head.length).split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") { if (!out.length) return ""; out.pop(); continue; }
+    out.push(seg);
+  }
+  return head + out.join("/");
+}
+
+function tmpRoots(env) {
+  const r = ["/tmp", "/var/tmp"];
+  for (const t of [env && env.TMPDIR, process.env.TMPDIR, os.tmpdir()]) if (t) r.push(String(t).replace(/\\+/g, "/").replace(/\/+$/, ""));
+  return r.filter((x) => x && x !== "/");
+}
+
+// True when target sits under a scratch area. The scratch root itself is NOT scratch (rm -rf /tmp is refused).
+export function isScratch(target, cwd, env) {
+  const t = String(target).replace(/^\$\{?TMPDIR\}?(?=\/|\\|$)/, (env && env.TMPDIR) || process.env.TMPDIR || os.tmpdir());
+  if (/[$`]/.test(t)) return false;
+  const n = norm(t, cwd);
+  if (!n) return false;
+  const nd = n.replace(/^[A-Za-z]:/, ""); // C:/r/build and an MSYS-style cwd /r name the same place
+  const lower = nd.toLowerCase();
+  for (const r of tmpRoots(env)) { const rl = r.toLowerCase(); if (lower.startsWith(rl + "/") && lower.length > rl.length + 1) return true; }
+  const c = norm(cwd || ".", "/").replace(/^[A-Za-z]:/, "");
+  if (c && lower.startsWith(c.toLowerCase() + "/")) {
+    const rel = nd.slice(c.length + 1).split("/");
+    if (rel.some((seg) => SCRATCH_SEG.has(seg))) return true;
+  }
+  return false;
+}
+
+function gitDirty(file, cwd) {
+  try {
+    const dir = fs.statSync(file).isDirectory() ? file : file.replace(/[\\/][^\\/]*$/, "") || ".";
+    const out = execFileSync("git", ["-C", dir, "status", "--porcelain", "--", file], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
+    return out.split("\n").some((l) => l.length > 3 && !l.startsWith("??") && !l.startsWith("!!"));
+  } catch { return false; }
+}
+
+function immutable(file) {
+  if (process.platform !== "linux") return false;
+  try { return /^\S*i\S*\s/.test(execFileSync("lsattr", ["-d", file], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] })); } catch { return false; }
+}
+
+// A named file target: why it must not be removed, or "".
+export function fileProtection(target, cwd) {
+  const abs = norm(target, cwd);
+  if (!abs) return "";
+  if (PROTECTED_BASE.test(abs.replace(/^.*\//, "")) || PROTECTED_DIR.test(abs)) return "protected harness file";
+  let st; try { st = fs.lstatSync(abs); } catch { return ""; }
+  if (st.isDirectory()) return "";
+  if ((st.mode & 0o222) === 0) return "read-only file";
+  if (immutable(abs)) return "immutable file";
+  if (gitDirty(abs, cwd)) return "git-tracked with uncommitted changes";
+  return "";
+}
+
+const isRecFlag = (x) => /^-[A-Za-z]*[rR][A-Za-z]*$/.test(x) || x === "--recursive";
+const PS_RM = /^(remove-item|ri|rm|del|erase|rd|rmdir|rmdir\.exe)$/i;
+
+// One simple command's words (quotes already removed by shellSegments). Returns a refusal label or "".
+export function rmRisk(words, cwd, env) {
+  const w = words || [];
+  if (!w.length) return "";
+  const low = w.map((x) => String(x).toLowerCase());
+  // find ... -delete / -exec rm: refused unless every search root is scratch
+  const fi = low.indexOf("find");
+  if (fi >= 0 && fi === low.findIndex((x) => /^(find|gfind)$/.test(x)) && (low.includes("-delete") || /-exec(dir)?/.test(low.join(" ")) && low.includes("rm"))) {
+    const roots = w.slice(fi + 1).filter((x, i, a) => !x.startsWith("-") && (i === 0 || !a[i - 1].startsWith("-") || /^-[HLP]$/.test(a[i - 1])));
+    if (!roots.length || !roots.every((r) => isScratch(r, cwd, env))) return `find -delete (recursive delete): ${REMEDY}`;
+  }
+  const xi = low.indexOf("xargs");
+  if (xi >= 0 && low.slice(xi + 1).some((x) => /^(rm|rmdir|unlink|shred)$/.test(x))) return `xargs rm (targets unknown): ${REMEDY}`;
+  // Remove-Item / del / rd with a recursive switch
+  const pi = w.findIndex((x, i) => PS_RM.test(x) && (i === 0 || /^(sudo|cmd|powershell|pwsh|\/c|-command|-c)$/i.test(w[i - 1])));
+  const ri = w.indexOf("rm");
+  if (ri > 0 && w[ri - 1] === "git") return ""; // git rm stages a removal; git restores it
+  const i = ri >= 0 && (ri === 0 || /^(sudo|doas|command|exec|env|time|nice|nohup)$/.test(w[ri - 1])) ? ri : pi;
+  if (i < 0 && !/^(unlink|shred)$/.test(low[0])) return "";
+  const a = w.slice(i < 0 ? 1 : i + 1);
+  const rec = a.some((x) => isRecFlag(x) || /^-recurse$/i.test(x) || /^\/s$/i.test(x));
+  const tg = [];
+  let dd = false;
+  for (const x of a) {
+    if (dd) { tg.push(x); continue; }
+    if (x === "--") { dd = true; continue; }
+    if (x.startsWith("--") || (/^-[A-Za-z]/.test(x) && !/[\\/.]/.test(x)) || /^\/[a-z]$/i.test(x)) continue;
+    if (/^-(path|literalpath|include|exclude|filter)$/i.test(x)) continue;
+    tg.push(x);
+  }
+  if (!tg.length) return "";
+  for (const t of tg) {
+    if (/[$`]/.test(t) && !/^\$\{?TMPDIR\}?[\\/]/.test(t)) return `rm with a shell expansion in the target: ${REMEDY}`;
+  }
+  const scratch = tg.map((t) => isScratch(t, cwd, env));
+  if (rec && !scratch.every(Boolean)) return `rm -r of a folder or tree (recursive delete): ${REMEDY}`;
+  if (tg.some((t, k) => /[*?[\]]/.test(t) && !scratch[k])) return `rm with a wildcard in the target: ${REMEDY}`;
+  for (let k = 0; k < tg.length; k++) {
+    if (scratch[k]) continue;
+    const why = fileProtection(tg[k], cwd);
+    if (why) return `rm of ${tg[k]} refused, ${why}: ${REMEDY}`;
+  }
+  return "";
+}

package/lib/setup-run.js

@@ -8,8 +8,9 @@
 // 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 { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+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/lib/stale-wkskill.js

@@ -2,7 +2,7 @@
 // (owner 2026-11-11: the fake wkskill is deleted; spokesman 2026-11-12: SDK e2e "after: local-bin=wkskill", RESULT 20/21 on every leg).
 // A link or .cmd twin is removed ONLY while it still points into a harness (its target or body names wkharness or wk-harness);
 // a wkskill file or link of the user's own stays. Spec: wkappbot skill read harness-installer-owns-all-setup
-import { lstatSync, readFileSync, readlinkSync, rmSync } from "node:fs";
+import { lstatSync, readFileSync, readlinkSync, rmSync } from "./fslocked.js";
 import { join } from "node:path";
 
 const isHarness = (s) => /wkharness|wk-harness/.test(String(s || ""));

package/lib/starter-md.js

@@ -5,7 +5,7 @@
 // NO global CLAUDE.md; refreshed only while it still equals what this install wrote (sha256 kept in install-state.json);
 // a file the user changed or wrote is never touched. Uninstall removes it only when it is still unchanged.
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "./fslocked.js";
 import { dirname, join } from "node:path";
 
 const sha = (s) => createHash("sha256").update(s).digest("hex");

package/lib/update.js

@@ -5,7 +5,7 @@
 // WKAPPBOT_CODE_NO_UPDATE_CHECK=1 turns the quiet check off. Spec: wkappbot skill read agent-harness-landscape-2026-howto
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "./fslocked.js";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 

package/lib/wk-hook.js

@@ -9,6 +9,7 @@ import { appendFileSync, existsSync, mkdirSync, statSync, writeFileSync } from "
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { rmRisk } from "./rmguard.js";
 
 // OpenCode tool id -> Claude tool name the kih guards already know.
 export const TOOL_MAP = {
@@ -271,6 +272,8 @@ export function riskClass(tool, input, cwd) {
           if (tg.some((x) => GIT_SEG.test(x))) return "write under .git";
         }
       }
+      const rr = rmRisk(w, cwd, process.env); // owner 2026-11-12: recursive, wildcard and unprotected-file deletes (lib/rmguard.js)
+      if (rr) return rr;
       if (w.some((x) => GIT_SEG.test(x)) && (seg.redirect || /^(rm|mv|cp|tee|truncate|dd|ln|chmod|sed)$/.test(w[0] || ""))) return "write under .git";
     }
     return "";

package/package.json

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

package/templates/harness-locks.md

@@ -0,0 +1,6 @@
+## Study locks for the installed harness sources (wkappbot-code install, owner 2026-11-13)
+## An Edit or Write of an installed harness source is refused until the skills below are read, even after an emergency-edit grant.
+## harness:skill (?i)[/\\]\.wk-harness[/\\](?:tools|\.githooks|\.claude[/\\]hooks|wkappbot-code[/\\]lib)[/\\]
+wkappbot skill read harness-installer-owns-all-setup
+wkappbot skill read agent-harness-landscape-2026-howto
+wkappbot skill read verify-tool-or-guard-synthetic-live-static-howto