wkappbot-code 0.3.32 → 0.3.35

package/bin/postinstall.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 || "");

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,14 +37,15 @@ 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";
-import { quietCheck, runUpdate, updateRow } from "../lib/update.js"; import { rmTreeHard, waitForArchive, holderReport } from "../lib/rmtree.js"; import { waitForHolders } from "../lib/holders.js"; import { plainFileUrl } from "../lib/fileurl.js"; import { removeStaleWkskill } from "../lib/stale-wkskill.js"; import { checkPath, installBothLinks, removeCreatedLinks } from "../lib/doctor-path.js";
+import { quietCheck, runUpdate, updateRow } from "../lib/update.js"; import { rmTreeHard, waitForArchive, holderReport } from "../lib/rmtree.js"; import { waitForHolders, stopHolders } from "../lib/holders.js"; import { plainFileUrl } from "../lib/fileurl.js"; import { removeStaleWkskill } from "../lib/stale-wkskill.js"; import { checkPath, installBothLinks, removeCreatedLinks } from "../lib/doctor-path.js";
 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";
@@ -361,7 +362,7 @@ 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');
   const url = pathToFileURL(dest).href;
   const tmpl = JSON.parse(readFileSync(join(PKG_DIR, "opencode.json"), "utf8"));
@@ -437,6 +438,7 @@ function install(o) {
   // 0.3.13 (owner 2026-11-09: Git Bash is a required tool too): bash, sh, curl, tar and git first; on Windows a Git that
   // is not on PATH is used from its folder, and a missing one is installed with winget (lib/prereq.js)
   // 0.3.32 (2026-11-12, kih ROOT 3): the uninstall also waits for every process whose command line names the harness dir (lib/holders.js) and prints the holders as one line the SDK e2e cause filter keeps.
+  // 0.3.33 (2026-11-12, kih ROOT 3): the holder wait matches the Git Bash spelling of the harness dir (/d/a/...), and after 8 s the shell-class children still naming it (bash, sh, flock, setsid, nohup, python; never wkappbot, wkchat, node) are ended before the removal (lib/holders.js stopHolders).
   // 0.3.31 (2026-11-12, spokesman order): provider add on a clean machine creates the OpenCode config folder (lib/providers.js mkdirSync) instead of dying with ENOENT, and the opencode.json backup of provider add and remove goes under <config dir>/wkappbot-code/backups, which uninstall removes with the rest of its state, so no opencode.json.bak-<stamp> stays in the user config folder.
   // 0.3.30 (2026-11-12, spokesman order after gate runs 43246725941 and 43247534046): 0.3.29 left the EPERM on .claude/hooks/wkharness-run.sh in one of two win-x64-nopy runs. The detached shadow run (wkjs_shadow) and the skill-draft child of the hook script were still started inside the harness copy with the script fd open; both now start from cwd / with the fd closed (wk_detach_prep), like the archive child. A failing tree removal on Windows now prints lib/rmtree.js holderReport: every Win32_Process row naming the harness dir plus every shell, node and python process with pid, ppid and command line, so a run that still hits EPERM names the real holder.
   // 0.3.29 (2026-11-12, spokesman order after SDK gate run 43227049219): uninstall waits (bounded 15 s) for a RECORDED archive pid before it removes the harness copy (lib/rmtree.js waitForArchive; the detached archive child starts from cwd / with the script fd closed), so no EPERM on .claude/hooks/wkharness-run.sh; install records st.opencodeBackups and uninstall leaves no opencode.json.bak-<stamp> of its own.
@@ -480,7 +482,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"))) {
@@ -575,7 +578,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;
@@ -609,7 +612,7 @@ function uninstall(o) {
   };
   // (B) the detached per-turn archive child may still hold .claude/hooks/wkharness-run.sh (Windows EPERM): wait for its RECORDED pid first.
   if (existsSync(HARNESS_DIR())) { const w = waitForArchive(HARNESS_DIR()); if (w.waited) log("harness: waited " + w.waited + " ms for the archive child" + (w.alive.length ? " (pid " + w.alive.join(",") + " still running)" : "")); }
-  if (st.harness && st.harness.mode === "web" && pr.harnessDirExisted !== true && existsSync(HARNESS_DIR())) { const h = waitForHolders(HARNESS_DIR()); if (h.waited) log("harness: waited " + h.waited + " ms for process(es) naming the harness dir" + (h.alive.length ? " (pid " + h.alive.join(",") + " still running)" : "")); }
+  if (st.harness && st.harness.mode === "web" && pr.harnessDirExisted !== true && existsSync(HARNESS_DIR())) { const h = waitForHolders(HARNESS_DIR()); if (h.waited) log("harness: waited " + h.waited + " ms for process(es) naming the harness dir" + (h.alive.length ? " (pid " + h.alive.join(",") + " still running)" : "")); if (h.alive.length) { const s = stopHolders(HARNESS_DIR()); log("harness: stopped " + s.stopped.length + " shell process(es) still naming the harness dir: " + s.stopped.map((r) => "pid=" + r.pid + " " + r.name + " " + String(r.cmd).slice(0, 200)).join(" ;; ") + (s.alive.length ? " (pid " + s.alive.join(",") + " still running)" : "")); } }
   if (st.harness && st.harness.mode === "web" && pr.harnessDirExisted !== true && existsSync(HARNESS_DIR())) rmTree(HARNESS_DIR(), "harness");
   if (pr.hooksDirExisted !== true && existsSync(HOOKS_DIR())) rmTree(HOOKS_DIR(), "push-gate");
   const cfgFile = join(configDir(o), "opencode.json");
@@ -659,7 +662,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);
@@ -745,7 +748,7 @@ if (process.argv.length <= 2 && o.cmd === "help") { const rc = launchOpenCode();
 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";

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/holders.js

@@ -1,32 +1,61 @@
-// holders.js -- wait for the processes that still hold the harness copy before an uninstall removes it (kih ROOT 3 2026-11-12, 0.3.32).
-// The 0.3.30 holder report named a live bash.exe at the failing Windows uninstall (SDK gate runs 43264303070 and 43269021533). lib/rmtree.js waitForArchive only waits
-// for the RECORDED archive pid, so any other detached hook child (the shadow run, the skill-draft child, a flock wrapper) still held .claude/hooks/wkharness-run.sh.
-// waitForHolders waits (bounded) for every process whose command line names the harness dir, never the uninstall's own pid or parent pid. exec and sleep are injectable.
+// holders.js -- wait for, then stop, the processes that still hold the harness copy before an uninstall removes it (kih ROOT 3 2026-11-12).
+// 0.3.32: the SDK win-x64-nopy gate (push run 43284028291, job 131412874028) still failed step 20 with EPERM on .claude/hooks/wkharness-run.sh while a 20 s holder wait ran,
+// and the runner cleanup then killed 8 orphan bash processes. Two defects, both fixed in 0.3.33:
+//  1. The command line of a Git Bash child names the harness dir in MSYS form (/d/a/_temp/home/.wk-harness/tools/wk-hippo-archive.sh), while the uninstall holds the Windows form
+//     (D:\a\_temp\home\.wk-harness). Matching only the Windows form never saw them (the live report listed bash.exe as a plain "shell" row, never HOLDS-DIR). dirForms() matches every form.
+//  2. A detached archive child can wait up to 300 s on its flock, longer than any sane wait. After the bounded wait, stopHolders() ends the shell-class children of the harness
+//     (bash, sh, flock, setsid, nohup, python) whose command line names the dir; it never touches wkappbot, wkchat or wka11y processes, the uninstall's own pid or parent pid, or node.
+// exec, sleep and kill are injectable so the selftest never queries or kills a real process.
 import { spawnSync } from "node:child_process";
 
 const sleepMs = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* no wait available */ } };
 const procExec = (cmd, args) => { const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 20000 }); return String(r.stdout || r.stderr || ""); };
+const STOPPABLE = /^(?:bash|sh|flock|setsid|nohup|python3?)(?:\.exe)?$/i;
 
-export function listHolders(dir, opts = {}) {
+// Every spelling of one directory in a process command line: Windows (c:/x), Git Bash (/c/x), Cygwin (/cygdrive/c/x), WSL (/mnt/c/x). All lower case, slashes forward.
+export function dirForms(dir) {
+  const w = String(dir).replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
+  const forms = [w], m = /^([a-z]):\/(.*)$/.exec(w);
+  if (m) for (const pre of ["/", "/cygdrive/", "/mnt/"]) forms.push(pre + m[1] + "/" + m[2]);
+  return forms;
+}
+
+// Rows { pid, name, cmd } of every process whose command line names the dir in any form, never this process or its parent.
+export function listHolderRows(dir, opts = {}) {
   const exec = opts.exec || procExec, isWin = opts.win ?? (process.platform === "win32");
-  const needle = String(dir).replace(/\\/g, "/").toLowerCase(), own = new Set([process.pid, process.ppid]);
+  const forms = dirForms(dir), own = new Set([process.pid, process.ppid]);
   let table = "";
   try {
     table = isWin ? exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId)`t$($_.ParentProcessId)`t$($_.Name)`t$([string]$_.CommandLine)\" }"])
       : exec("ps", ["-eo", "pid=,ppid=,comm=,args="]).split(/\r?\n/).map((l) => l.trim().replace(/\s+/g, "\t")).join("\n");
   } catch { return []; }
-  const pids = [];
+  const rows = [];
   for (const line of String(table).split(/\r?\n/)) {
     const f = line.split("\t"), pid = parseInt(f[0], 10);
     if (f.length < 4 || !(pid > 0) || own.has(pid)) continue;
-    if (f.slice(3).join(" ").replace(/\\/g, "/").toLowerCase().includes(needle)) pids.push(pid);
+    const cmd = f.slice(3).join(" "), hay = cmd.replace(/\\/g, "/").toLowerCase();
+    if (forms.some((x) => hay.includes(x))) rows.push({ pid, name: String(f[2]).trim(), cmd });
   }
-  return pids;
+  return rows;
 }
 
+export function listHolders(dir, opts = {}) { return listHolderRows(dir, opts).map((r) => r.pid); }
+
 export function waitForHolders(dir, opts = {}) {
-  const maxMs = opts.maxMs ?? 20000, gap = opts.gap || 500, nap = opts.sleep || sleepMs;
+  const maxMs = opts.maxMs ?? 8000, gap = opts.gap || 500, nap = opts.sleep || sleepMs;
   let alive = listHolders(dir, opts), waited = 0;
   while (alive.length && waited < maxMs) { nap(gap); waited += gap; alive = listHolders(dir, opts); }
   return { waited, alive };
 }
+
+// End the shell-class holders still alive, then report who remains. { stopped: [{pid,name,cmd}], alive: [pid...] }
+export function stopHolders(dir, opts = {}) {
+  const kill = opts.kill || ((pid) => process.kill(pid, "SIGKILL")), nap = opts.sleep || sleepMs;
+  const stopped = [];
+  for (const r of listHolderRows(dir, opts)) {
+    if (!STOPPABLE.test(r.name)) continue;
+    try { kill(r.pid); stopped.push(r); } catch { /* already gone, or not ours to end */ }
+  }
+  if (stopped.length) nap(opts.settle ?? 1500);
+  return { stopped, alive: listHolders(dir, opts) };
+}

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,6 @@
+// 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
+export const PLUGIN_LIBS = ["wk-hook.js", "rmguard.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/rmtree.js

@@ -3,6 +3,7 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
+import { dirForms } from "./holders.js";
 
 const sleepMs = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* no wait available */ } };
 
@@ -16,7 +17,7 @@ const sleepMs = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffe
 export function holderReport(dir, opts = {}) {
   const exec = opts.exec || ((cmd, args) => { const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 20000 }); return String(r.stdout || r.stderr || ""); });
   const isWin = opts.win ?? (process.platform === "win32");
-  const needle = String(dir).replace(/\\/g, "/").toLowerCase();
+  const needle = dirForms(dir);
   try {
     if (isWin) {
       const ps = "Get-CimInstance Win32_Process | ForEach-Object { $c = [string]$_.CommandLine; $p = [string]$_.ExecutablePath; \"$($_.ProcessId)`t$($_.ParentProcessId)`t$($_.Name)`t$c`t$p\" }";
@@ -32,7 +33,7 @@ function filterHolderRows(out, needle) {
     const f = line.split("\t");
     if (f.length < 3) continue;
     const hay = f.slice(3).join(" ").replace(/\\/g, "/").toLowerCase();
-    const named = hay.includes(needle), shellish = HOLDER_NAMES.test(String(f[2]).trim());
+    const named = needle.some((x) => hay.includes(x)), shellish = HOLDER_NAMES.test(String(f[2]).trim());
     if (named || shellish) rows.push((named ? "HOLDS-DIR " : "shell      ") + "pid=" + f[0] + " ppid=" + f[1] + " " + f[2] + " " + f.slice(3).join(" ").slice(0, 300));
   }
   return rows.length ? rows.slice(0, 60).join("\n") : "no process names the harness dir and no shell, node or python process is running";

package/lib/setup-run.js

@@ -9,7 +9,7 @@
 // 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 { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "./fslocked.js";
 import { homedir, tmpdir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 

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.32",
+  "version": "0.3.35",
   "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/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