wkappbot-code 0.3.9 → 0.3.11

package/bin/postinstall.js

@@ -2,71 +2,86 @@
 // wkappbot-code postinstall -- npm runs this after `npm install wkappbot-code` (local or -g).
 // Owner order 2026-11-06: the Default cloud environment's setup script is `npm install wkappbot-code`, and new cloud
 // ROOTs still started with no hooks, because the package had no install script and npm only copied files.
+// Owner order 2026-11-08: "npm install wkappbot-code should do the initial setup and the tests automatically" -- on
+// Windows, macOS and Linux alike, not only on a cloud VM.
 // CONTRACT: (a) ALWAYS exits 0 and returns within a moment -- the real work runs DETACHED and logs to
-// ~/.wkappbot-code/postinstall.log, then writes ~/.wkappbot-code/postinstall.done; (b) on a Claude Code cloud VM
-// (CLAUDE_CODE_REMOTE set, or a Linux HOME of /root that holds .claude) it runs `wkappbot-code install --no-npm`,
-// which lays the web harness, wires ~/.claude/settings.json (PreToolUse, Stop, UserPromptSubmit, SessionStart through
-// the lite harness), the global git hooks, the wkskill/wk-verify shims and the public skills, keeping every user
-// setting; idempotent: a done marker of the same version skips it; (c) on any other machine it only prints the one
-// command to run. WKAPPBOT_CODE_NO_POSTINSTALL=1 skips it (the selftest sets it so npm-installs in its cases never
-// touch the machine running it). WKAPPBOT_CODE_DEV_SEAT=1 adds --dev-seat (the full pwsh harness instead of lite);
-// WKAPPBOT_CODE_INSTALL_ARGS adds install flags. A user install takes the lite harness: on a stranger's cloud VM the
-// owner's full fleet harness (busy-fleet, letter gates, emergency-edit) would be the wrong default.
+// ~/.wkappbot-code/postinstall.log; (b) the worker runs `wkappbot-code install --no-npm` (lays the web harness, wires
+// ~/.claude/settings.json through the lite harness -- PreToolUse, Stop, UserPromptSubmit, SessionStart -- the global git
+// hooks, the wkskill/wk-verify shims and the public skills, keeping every user setting), then `wkappbot-code doctor`,
+// then a short self-test (lib/setup-run.js: core --version, skill read on-load, one hook allow, one hook refuse), and
+// writes ~/.wkappbot-code/postinstall.done {version, installRc, doctor:{pass,warn,fail,skip}, selftest:{n,m}, ...};
+// postinstall.running exists while the worker lives; (c) the first `wkappbot-code` run afterwards prints ONE summary
+// line (lib/setup-run.js printBanner) and opens OpenCode; (d) idempotent: a done file of the same version with
+// installRc 0 skips the rerun. WKAPPBOT_CODE_NO_POSTINSTALL=1 skips everything (the selftest sets it so npm-installs
+// in its cases never touch the machine running it). WKAPPBOT_CODE_DEV_SEAT=1 adds --dev-seat (the full pwsh harness
+// instead of lite); WKAPPBOT_CODE_INSTALL_ARGS adds install flags. A user install takes the lite harness: on a
+// stranger's machine the owner's full fleet harness (busy-fleet, letter gates, emergency-edit) would be the wrong default.
 // Spec: wkappbot skill read agent-harness-landscape-2026-howto
-import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { buildDone, files, markRunning, parseDoctor, platformOf, selfTest, writeDone } from "../lib/setup-run.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const CLI = join(HERE, "wkappbot-code.js");
-const STATE = join(homedir(), ".wkappbot-code");
-const LOG = join(STATE, "postinstall.log");
-const DONE = join(STATE, "postinstall.done");
+const F = files(homedir());
+const STATE = F.dir, LOG = F.log, DONE = F.done;
 
 function version() {
   try { return JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version || "?"; } catch { return "?"; }
 }
-export function isCloudVm(env = process.env, home = homedir(), platform = process.platform) {
+export function isCloudVm(env = process.env, home = homedir(), platform = platformOf(env)) {
   if (env.CLAUDE_CODE_REMOTE) return true;
   return platform === "linux" && home === "/root" && existsSync(join(home, ".claude"));
 }
-function stamp(msg) { try { mkdirSync(STATE, { recursive: true }); writeFileSync(LOG, new Date().toISOString() + " " + msg + "\n", { flag: "a" }); } catch {} }
+function stamp(msg) { try { mkdirSync(STATE, { recursive: true }); appendFileSync(LOG, new Date().toISOString() + " " + msg + "\n"); } catch {} }
 
-// --run: the detached worker. Runs the installer to the end, then records the done marker with its exit code.
+// --run: the detached worker. install, then doctor, then the self-test, then the done file.
 async function runWorker() {
   const args = [CLI, "install", "--no-npm"];
   if (process.env.WKAPPBOT_CODE_DEV_SEAT === "1") args.push("--dev-seat");
   // extra install flags, e.g. "--no-bin --no-skills" (the selftest; a seat without the SDK release assets)
   args.push(...String(process.env.WKAPPBOT_CODE_INSTALL_ARGS || "").split(/\s+/).filter((a) => /^--[a-z-]+$/.test(a)));
+  // the children are the worker's own: they must not print the first-run banner (it is for the user's next command)
+  const env = { ...process.env, WKAPPBOT_CODE_NO_UPDATE_CHECK: "1", WKAPPBOT_CODE_SETUP_WORKER: "1" };
   stamp("worker start: node " + args.join(" "));
   const out = openSync(LOG, "a");
-  const rc = await new Promise((res) => {
-    const c = spawn(process.execPath, args, { stdio: ["ignore", out, out], env: { ...process.env, WKAPPBOT_CODE_NO_UPDATE_CHECK: "1" } });
+  const installRc = await 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));
   });
-  try { writeFileSync(DONE, JSON.stringify({ version: version(), rc, at: new Date().toISOString() }) + "\n"); } catch {}
-  stamp("worker done rc " + rc);
+  stamp("install rc " + installRc + "; doctor");
+  const dr = spawnSync(process.execPath, [CLI, "doctor"], { encoding: "utf8", env, timeout: 300000 });
+  const dtext = (dr.stdout || "") + (dr.stderr || "");
+  try { appendFileSync(LOG, dtext); } catch {}
+  const doctor = parseDoctor(dtext);
+  stamp("doctor pass " + doctor.pass + " warn " + doctor.warn + " fail " + doctor.fail + " skip " + doctor.skip + "; self-test");
+  let st = { n: 0, m: 4, items: [{ ok: false, name: "self-test", detail: "did not run" }] };
+  try { st = selfTest({ env, home: homedir() }); } catch (e) { st.items[0].detail = String(e); }
+  for (const i of st.items) stamp("selftest " + (i.ok ? "PASS " : "FAIL ") + i.name + (i.ok ? "" : " -- " + i.detail));
+  try { writeDone(homedir(), buildDone({ version: version(), installRc, doctor, selftest: st, env: process.env })); } catch (e) { stamp("done file error: " + e); }
+  stamp("worker done: install rc " + installRc + ", doctor " + doctor.pass + "/" + (doctor.pass + doctor.warn + doctor.fail) + ", selftest " + st.n + "/" + st.m);
 }
 
 function main() {
   if (process.argv[2] === "--run") return runWorker().catch(() => {}).finally(() => process.exit(0));
   if (process.env.WKAPPBOT_CODE_NO_POSTINSTALL === "1") return;
-  if (!isCloudVm()) {
-    console.log("[wkappbot-code] installed. To wire the harness and OpenCode on this machine run: npx wkappbot-code install   (then: wkappbot-code doctor)");
-    return;
-  }
+  const cloud = isCloudVm();
   try {
     const d = JSON.parse(readFileSync(DONE, "utf8"));
-    if (d.version === version() && d.rc === 0) { console.log("[wkappbot-code] cloud VM: harness already wired by " + d.version + " (" + DONE + ")"); return; }
+    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 });
+  const c = spawn(process.execPath, [fileURLToPath(import.meta.url), "--run"], { detached: true, stdio: ["ignore", out, out], env: process.env, windowsHide: true });
   c.unref();
-  console.log("[wkappbot-code] cloud VM detected: wiring the Claude Code harness in the background (log: " + LOG + ", done marker: " + DONE + ")");
+  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");
 }
 
 try { main(); } catch (e) { try { stamp("postinstall error: " + e); } catch {} }

package/bin/prepack.js

@@ -43,7 +43,9 @@ if (!existsSync(join(stage, "tools", "wkharness-lite.sh"))) die("the baked tree
 rmSync(OUT, { recursive: true, force: true });
 mkdirSync(OUT, { recursive: true });
 const tgz = join(OUT, "wk-harness-min.tar.gz");
-const t = spawnSync("tar", ["--exclude=./.git", "--exclude=./bin/linux-x64", "-czf", sh(tgz), "-C", sh(stage), "."], { encoding: "utf8" });
+// A RELATIVE archive name, run in OUT: GNU tar on Git for Windows reads "D:/a/..." as host "D" (rsh) and fails with
+// "Cannot connect to D: resolve failed" (SDK windows-latest 2026-11-06); bsdtar and GNU tar both take a relative -f.
+const t = spawnSync("tar", ["--exclude=./.git", "--exclude=./bin/linux-x64", "-czf", "wk-harness-min.tar.gz", "-C", sh(stage), "."], { encoding: "utf8", cwd: OUT });
 if (t.status !== 0) die("tar rc " + t.status + " " + t.stderr);
 const sha = createHash("sha256").update(readFileSync(tgz)).digest("hex");
 writeFileSync(tgz + ".sha256", sha + "  wk-harness-min.tar.gz\n");

package/bin/wkappbot-code.js

@@ -38,8 +38,9 @@ import {
 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 { quietCheck, runUpdate, updateRow } from "../lib/update.js"; import { rmTreeHard } from "../lib/rmtree.js"; import { plainFileUrl } from "../lib/fileurl.js";
 import { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
+import { launchOpenCode, printBanner } 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"));
@@ -48,8 +49,8 @@ const OWNER_LOGIN = "kiexpert";
 // The harness this package carries (harness/, baked by bin/prepack.js at pack time) comes first: it needs no checkout
 // and no network (spokesman 2026-11-06, a Default-environment VM). WK_HARNESS_BASE overrides; the web page serves an unbaked tree.
 const BUNDLED_HARNESS = () => join(PKG_DIR, "harness");
-const HARNESS_BASE = () => (process.env.WK_HARNESS_BASE || (existsSync(join(BUNDLED_HARNESS(), "install.sh")) ? pathToFileURL(BUNDLED_HARNESS()).href
-  : "https://kiexpert.github.io/wkappbot-kih/webvm/x64/harness")).replace(/\/+$/, "");
+const HARNESS_BASE = () => plainFileUrl(process.env.WK_HARNESS_BASE || (existsSync(join(BUNDLED_HARNESS(), "install.sh")) ? pathToFileURL(BUNDLED_HARNESS()).href
+  : "https://kiexpert.github.io/wkappbot-kih/webvm/x64/harness")).replace(/\/+$/, "");   // plainFileUrl: curl on Windows reads RUNNER%7E1 literally
 const HARNESS_DIR = () => process.env.WK_HARNESS_DIR || join(homedir(), ".wk-harness");
 const HOOKS_DIR = () => join(homedir(), ".wk-harness-hooks");   // tools/wk-global-hooks.sh install default
 const SETTINGS = () => process.env.WK_SETTINGS || join(homedir(), ".claude", "settings.json");
@@ -371,7 +372,7 @@ function installPlugin(o, kih, kihSource) {
 // The machine state an uninstall must give back, recorded ONCE (a re-install never overwrites the first record, or
 // it would record our own dispatcher as the "prior" hooksPath). Shim paths are those install may create.
 function shimCandidates() {
-  return [join(linkDir(), "wkappbot"), join(HARNESS_LINKS(), "wkskill"), join(HARNESS_LINKS(), "wk-verify")];
+  return [join(linkDir(), "wkappbot"), join(HARNESS_LINKS(), "wkskill"), join(HARNESS_LINKS(), "wk-verify"), join(HARNESS_LINKS(), "wkskill.cmd"), join(HARNESS_LINKS(), "wk-verify.cmd")];   // Windows (Git Bash) .cmd twins from harness-install.sh: recorded like the rest, so uninstall removes them, never a user file
 }
 const PRE_SETTINGS = () => join(STATE_HOME(), "settings.pre-install.json");
 function recordPrior(prev) {
@@ -453,8 +454,10 @@ function uninstall(o) {
   if (!st.version) log("no install record at " + statePath(o) + "; removing only what is ours by name");
   // 1. global core.hooksPath back to its recorded value (only when it still points at a dir we wrote)
   const cur = globalHooksPath();
+  // REAL paths: macOS /var is a symlink to /private/var, so git and HOME may spell one dir two ways (SDK run 42252316617).
+  const real = (x) => { const r = resolve(x.replace(/^~(?=\/|$)/, homedir())); try { return realpathSync.native(r); } catch { return r; } };   // .native expands a Windows 8.3 name (RUNNER~1) that git config spells in the long form
   const oursHp = (p) => !!p && [HOOKS_DIR(), join(HARNESS_DIR(), ".githooks"), st.kihDir && join(st.kihDir, ".githooks")]
-    .filter(Boolean).some((x) => resolve(p.replace(/^~(?=\/|$)/, homedir())) === resolve(x));
+    .filter(Boolean).some((x) => real(p) === real(x));
   if (cur !== (pr.hooksPath ?? null) && (cur === null || oursHp(cur))) {
     const r = pr.hooksPath ? gitGlobal("core.hooksPath", pr.hooksPath) : gitGlobal("--unset", "core.hooksPath");
     log("hooksPath: " + (cur || "unset") + " -> " + (pr.hooksPath || "unset") + (r.status === 0 ? "" : " (git rc " + r.status + ")"));
@@ -493,11 +496,10 @@ function uninstall(o) {
     if (isSymlink(p) || existsSync(p)) { rmSync(p, { force: true }); log("shim: removed " + p); }
   }
   // 4. the harness dirs we created, the plugin entry and our config folder
-  // Windows releases a just-closed handle late (EBUSY/EPERM/ENOTEMPTY), so every tree delete retries and, when it
-  // still fails, names the path and goes on with the rest instead of aborting the uninstall half way.
+  // Windows frees a closed handle late (ENOTEMPTY): lib/rmtree.js retries ~6 s, then a per-entry pass names the blocker; a failure goes on.
   const rmTree = (p, what) => {
-    try { rmSync(p, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 }); if (what) log(what + ": removed " + p); }
-    catch (e) { rc = 1; log((what || "remove") + ": could not remove " + p + " (" + (e.code || e.message) + ") -- delete it by hand"); }
+    const r = rmTreeHard(p); if (r.ok) { if (what) log(what + ": removed " + p); return; }
+    rc = 1; log((what || "remove") + ": could not remove " + p + " -- blocked by " + r.blockers.slice(0, 5).join("; ") + " -- delete it by hand");
   };
   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");
@@ -615,6 +617,10 @@ if (["install", "doctor", "config"].includes(o.cmd) && !o.update) {
   const nv = quietCheck(PKG.version, console.log);
   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.
+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);

package/lib/fileurl.js

@@ -0,0 +1,12 @@
+// fileurl.js -- a file:// base that curl can open on every platform.
+// pathToFileURL percent-encodes "~" ("RUNNER~1" -> "RUNNER%7E1") and Windows curl does not decode a file:// path, so a
+// Windows profile with a short name, a space or a non-ASCII letter failed to read the harness. plainFileUrl hands curl the plain path.
+import { fileURLToPath } from "node:url";
+
+export function plainFileUrl(u) {
+  if (!/^file:\/\//i.test(u)) return u;
+  let p;
+  try { p = fileURLToPath(u); } catch { return u; }
+  p = p.replace(/\\/g, "/");
+  return "file://" + (p.startsWith("/") ? "" : "/") + p;
+}

package/lib/rmtree.js

@@ -0,0 +1,35 @@
+// rmtree.js -- delete a tree on a platform that releases a just-closed handle late (Windows: EBUSY/EPERM/ENOTEMPTY).
+// rmTreeHard(p, rm) -> { ok, blockers[] }: a long bounded retry first, then a per-entry pass that names what stays.
+import { existsSync, lstatSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+const sleepMs = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* no wait available */ } };
+
+// rm is injectable so the selftest can fake a held handle (default: fs.rmSync with Node's own retry)
+export function rmTreeHard(p, rm = (q, o) => rmSync(q, o), opts = {}) {
+  const tries = opts.tries || 6, gap = opts.gap || 1000;
+  const once = (q) => rm(q, { recursive: true, force: true, maxRetries: 10, retryDelay: 300 });
+  let last = null;
+  for (let i = 0; i < tries; i++) {
+    try { once(p); if (!existsSync(p)) return { ok: true, blockers: [] }; last = new Error("ENOTEMPTY"); }
+    catch (e) { last = e; }
+    sleepMs(gap);
+  }
+  // per-entry pass: remove what can go and name every entry (and nested file) that cannot
+  const blockers = [];
+  const walk = (d) => {
+    let names = [];
+    try { names = readdirSync(d); } catch (e) { blockers.push(d + " (" + (e.code || e.message) + ")"); return; }
+    for (const n of names) {
+      const q = join(d, n);
+      let dir = false; try { dir = lstatSync(q).isDirectory(); } catch { /* vanished */ }
+      if (dir) walk(q);
+      try { rm(q, { recursive: true, force: true }); } catch (e) { blockers.push(q + " (" + (e.code || e.message) + ")"); }
+    }
+  };
+  if (existsSync(p)) walk(p);
+  try { rm(p, { recursive: true, force: true }); } catch (e) { if (existsSync(p)) blockers.push(p + " (" + (e.code || e.message) + ")"); }
+  if (!existsSync(p)) return { ok: true, blockers: [] };
+  if (!blockers.length) blockers.push(p + " (" + ((last && (last.code || last.message)) || "not removed") + ")");
+  return { ok: false, blockers };
+}

package/lib/setup-run.js

@@ -0,0 +1,135 @@
+// wkappbot-code lib/setup-run.js -- what `npm install wkappbot-code` does after the files land, and what the first
+// `wkappbot-code` run says about it (owner order 2026-11-08: "npm install wkappbot-code should do the initial setup and
+// the tests automatically", "typing wkappbot-code should show the OpenCode start screen").
+//   worker  bin/postinstall.js --run: install --no-npm, then doctor, then selfTest() below, then ONE postinstall.done
+//           JSON {version, installRc, rc, doctor:{pass,warn,fail,skip}, selftest:{n,m}, platform, at, items}.
+//   banner  bannerFor() / printBanner(): the one line the first run prints ("setup ok, doctor 9/9, selftest 4/4", the
+//           failing item with the log path, or "setup still running"), shown ONCE per done file (postinstall.seen).
+// 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 { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNNING_STALE_MS = 30 * 60 * 1000;   // a worker that left no done file for 30 minutes is dead, not "still running"
+const IS_WIN = process.platform === "win32";
+
+// WKAPPBOT_CODE_FAKE_PLATFORM is the selftest's way to run the non-cloud road "as win32 / darwin" on one machine.
+export const platformOf = (env = process.env) => env.WKAPPBOT_CODE_FAKE_PLATFORM || process.platform;
+export const stateDir = (home = homedir()) => join(home, ".wkappbot-code");
+export const files = (home = homedir()) => {
+  const d = stateDir(home);
+  return { dir: d, log: join(d, "postinstall.log"), running: join(d, "postinstall.running"), done: join(d, "postinstall.done"), seen: join(d, "postinstall.seen") };
+};
+const readJson = (f) => { try { return JSON.parse(readFileSync(f, "utf8")); } catch { return null; } };
+// Same MSYS rule as wkappbot-code.js shPath: the sh Git for Windows starts reads "D:\a\x" as host D.
+const shPath = (p) => (IS_WIN && /^[A-Za-z]:[\\/]/.test(p) ? "/" + p[0].toLowerCase() + p.slice(2).replace(/\\/g, "/") : p);
+
+// ---- doctor ---------------------------------------------------------------------------------------
+// doctor prints one `PASS|WARN|FAIL|SKIP name  detail` row per part; SKIP rows are not counted in the n/m.
+export function parseDoctor(text) {
+  const c = { pass: 0, warn: 0, fail: 0, skip: 0, failed: [] };
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const m = /^(PASS|WARN|FAIL|SKIP) (\S+)/.exec(line);
+    if (!m) continue;
+    c[m[1].toLowerCase()]++;
+    if (m[1] === "FAIL") c.failed.push(m[2]);
+  }
+  return c;
+}
+
+// ---- self-test ------------------------------------------------------------------------------------
+function installState(env, home) {
+  const cfg = env.OPENCODE_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(home, ".config"), "opencode");
+  return readJson(join(cfg, "wkappbot-code", "install-state.json")) || {};
+}
+const hookPayload = (cmd) => JSON.stringify({ hook_event_name: "PreToolUse", session_id: "wkappbot-code-selftest", cwd: tmpdir(), tool_name: "Bash", tool_input: { command: cmd } });
+
+// Four items: the core answers --version, the core prints skill on-load, the lite hook ALLOWS a plain command (rc 0) and
+// REFUSES git --no-verify (rc 2). Returns {n, m, items:[{name, ok, detail}]}.
+export function selfTest({ env = process.env, home = homedir() } = {}) {
+  const st = installState(env, home);
+  const dest = (st.bin && st.bin.dest) || env.WK_BIN_DEST || join(home, ".local", "share", "wkappbot", IS_WIN ? "wkappbot.exe" : "wkappbot");
+  const kih = st.kihDir || env.WK_HARNESS_DIR || join(home, ".wk-harness");
+  const lite = join(kih, "tools", "wkharness-lite.sh");
+  const items = [];
+  const add = (name, ok, detail) => items.push({ name, ok: !!ok, detail: String(detail || "").replace(/\s+/g, " ").slice(0, 200) });
+  const scratch = mkdtempSync(join(tmpdir(), "wk-appbot-selftest-"));
+  const shell = IS_WIN && /\.(cmd|bat)$/i.test(dest);   // node refuses to start a .cmd without a shell
+  try {
+    const core = (args) => (existsSync(dest) ? spawnSync(dest, args, { encoding: "utf8", timeout: 120000, cwd: scratch, shell, env: { ...env, WKAPPBOT_NO_REMOTE_CHECK: "1" } }) : null);
+    let r = core(["--version"]);
+    add("core --version", r && r.status === 0 && (r.stdout || "").trim(), r ? "rc " + r.status + " " + (r.stdout || r.stderr) : dest + " absent");
+    r = core(["skill", "read", "on-load"]);
+    add("skill read on-load", r && /\bID\s*:\s*on-load\b/.test(r.stdout || ""), r ? "rc " + r.status : dest + " absent");
+    const hook = (cmd) => (existsSync(lite)
+      ? spawnSync("sh", [shPath(lite), "pre"], { encoding: "utf8", timeout: 60000, input: hookPayload(cmd), env: { ...env, WKHARNESS_LITE_DIR: shPath(join(scratch, "lite")) } }) : null);
+    r = hook("ls /");
+    add("hook allow", r && r.status === 0, r ? "rc " + r.status + " " + (r.stderr || "") : lite + " absent");
+    r = hook("git commit --no-verify -m selftest");
+    add("hook refuse", r && r.status === 2, r ? "rc " + r.status + " " + (r.stderr || "") : lite + " absent");
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+  return { n: items.filter((i) => i.ok).length, m: items.length, items };
+}
+
+// ---- done / running -------------------------------------------------------------------------------
+export function markRunning(home, version) {
+  const f = files(home);
+  mkdirSync(f.dir, { recursive: true });
+  rmSync(f.done, { force: true });   // the old verdict belongs to the old install
+  writeFileSync(f.running, JSON.stringify({ version, at: new Date().toISOString(), pid: process.pid }) + "\n");
+}
+export function writeDone(home, rec) {
+  const f = files(home);
+  const tmp = f.done + ".tmp";
+  writeFileSync(tmp, JSON.stringify(rec) + "\n");
+  renameSync(tmp, f.done);   // the done file appears whole or not at all (the selftest polls for it)
+  rmSync(f.running, { force: true });
+}
+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(),
+    items: selftest.items.filter((i) => !i.ok).map((i) => i.name + ": " + i.detail), doctorFailed: doctor.failed };
+}
+
+// ---- banner ---------------------------------------------------------------------------------------
+// Pure: the line to print for a state ("" = nothing to say) and whether it counts as seen. `now` is a ms clock.
+export function bannerFor({ done, running, seen, logPath, now = Date.now() }) {
+  if (running && !done) {
+    const age = now - Date.parse(running.at || 0);
+    if (age >= 0 && age < RUNNING_STALE_MS) return { line: "[wkappbot-code] setup still running (log: " + logPath + ") -- opening OpenCode anyway", mark: false };
+    return { line: "[wkappbot-code] setup did not finish (worker started " + (running.at || "?") + ", no result); log: " + logPath + " -- rerun: wkappbot-code install", mark: false };
+  }
+  if (!done || (seen && seen === done.at)) return { line: "", mark: false };
+  const d = done.doctor || {}, s = done.selftest || {};
+  const total = (d.pass || 0) + (d.warn || 0) + (d.fail || 0);
+  const tail = "doctor " + (d.pass || 0) + "/" + total + (d.warn ? " (" + d.warn + " warn)" : "") + ", selftest " + (s.n || 0) + "/" + (s.m || 0);
+  const installRc = done.installRc ?? done.rc;
+  if (installRc === 0 && !d.fail && s.n === s.m && s.m > 0) return { line: "[wkappbot-code] setup ok, " + tail, mark: true };
+  const bad = [];
+  if (installRc !== 0) bad.push("install rc " + installRc);
+  for (const f of done.doctorFailed || []) bad.push("doctor " + f + " FAIL");
+  for (const i of done.items || []) bad.push("selftest " + i);
+  if (!bad.length) bad.push(d.fail ? "doctor " + d.fail + " FAIL" : "selftest " + (s.n || 0) + "/" + (s.m || 0));
+  return { line: "[wkappbot-code] setup needs attention: " + bad.slice(0, 3).join("; ") + " (" + tail + "); log: " + logPath, mark: true };
+}
+export function printBanner({ home = homedir(), out = console.log, now = Date.now() } = {}) {
+  const f = files(home);
+  const done = readJson(f.done), running = readJson(f.running);
+  let seen = ""; try { seen = readFileSync(f.seen, "utf8").trim(); } catch {}
+  const b = bannerFor({ done, running, seen, logPath: f.log, now });
+  if (b.line) out(b.line);
+  if (b.mark && done) { try { writeFileSync(f.seen, done.at + "\n"); } catch {} }
+  return b.line;
+}
+
+// ---- bare launch ----------------------------------------------------------------------------------
+// `wkappbot-code` with no arguments opens OpenCode (its start screen). Returns the exit code, or null when opencode
+// cannot be started (not on PATH): the caller then prints the usage as before.
+export function launchOpenCode(env = process.env) {
+  const r = spawnSync("opencode", [], { stdio: "inherit", shell: IS_WIN, env });
+  if (r.error) return null;
+  return r.status ?? 1;
+}

package/lib/winpath.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# winpath.sh -- sourced by selftest-opencode-e2e.sh and selftest-win-paths.sh. wk_winpath PATH prints the form a NATIVE
+# Windows program takes: `cygpath -m` (C:/x/y) when cygpath is on PATH, else PATH unchanged. A failed conversion also
+# leaves the path as it was. bash 3.2 safe (macOS /bin/bash).
+wk_winpath() {
+  local w
+  if command -v cygpath >/dev/null 2>&1; then
+    w="$(cygpath -m "$1" 2>/dev/null)"
+    if [ -n "$w" ]; then printf '%s\n' "$w"; return 0; fi
+  fi
+  printf '%s\n' "$1"
+}

package/lib/wk-hook.js

@@ -164,13 +164,84 @@ export function refusalReason(r) {
 // a call in one of these classes is REFUSED instead of allowed: a public package must never let rm -rf HOME through
 // because pwsh happened to be missing. Returns the class label, or "".
 const HOME_T = /^(~|\$HOME|\$\{HOME\}|\/root|\/home\/[^/]+|\/Users\/[^/]+)\/?(\*|\.\*)?$/;
+// The shell line as the risk floor reads it. A heredoc body (after <<'TAG', <<TAG or <<-TAG, up to the line TAG) is
+// dropped, and a quoted string is ONE word with its quotes removed, so its text is never read as a git flag or a path.
+// Words handed to a shell (sh/bash -c, eval) are also returned in seg.inner and are checked again as a command line.
+const SHELL_NAME_RE = /^(sh|bash|zsh|dash|ksh)$/;
+export function shellSegments(cmd) {
+  const s = String(cmd || "");
+  const segs = [];
+  let seg = { words: [], inner: [], redirect: false };
+  let word = null, quote = "", pending = [], i = 0;
+  const add = (ch) => { word = (word === null ? "" : word) + ch; };
+  const endWord = () => {
+    if (word === null) return;
+    const head = seg.words[0] || "";
+    const prev = seg.words[seg.words.length - 1];
+    if ((prev === "-c" && SHELL_NAME_RE.test(head)) || head === "eval") seg.inner.push(word);
+    seg.words.push(word);
+    word = null;
+  };
+  const endSeg = () => {
+    endWord();
+    if (seg.words.length || seg.redirect) segs.push(seg);
+    seg = { words: [], inner: [], redirect: false };
+  };
+  while (i < s.length) {
+    const ch = s[i];
+    if (quote === "'") { if (ch === "'") quote = ""; else add(ch); i++; continue; }
+    if (quote === '"') {
+      if (ch === '"') quote = "";
+      else if (ch === "\\" && i + 1 < s.length && /["\\$`]/.test(s[i + 1])) { add(s[i + 1]); i++; }
+      else add(ch);
+      i++; continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; if (word === null) word = ""; i++; continue; }
+    if (ch === "\\" && i + 1 < s.length) { add(s[i + 1]); i += 2; continue; }
+    if (ch === "<" && s[i + 1] === "<" && s[i + 2] !== "<") {
+      endWord();
+      let j = i + 2;
+      const dash = s[j] === "-";
+      if (dash) j++;
+      while (s[j] === " " || s[j] === "\t") j++;
+      let tag = "";
+      if (s[j] === "'" || s[j] === '"') { const q = s[j]; j++; while (j < s.length && s[j] !== q && s[j] !== "\n") tag += s[j++]; j++; }
+      else while (j < s.length && !/[\s;&|<>()'"]/.test(s[j])) tag += s[j++];
+      if (tag) pending.push({ tag, dash });
+      i = j; continue;
+    }
+    if (ch === "\n") {
+      endSeg(); i++;
+      for (const h of pending) {
+        for (;;) {
+          if (i >= s.length) break;
+          let e = s.indexOf("\n", i);
+          if (e < 0) e = s.length;
+          const line = s.slice(i, e).replace(/\r$/, "");
+          i = e + 1;
+          if ((h.dash ? line.replace(/^\t+/, "") : line) === h.tag) break;
+        }
+      }
+      pending = [];
+      continue;
+    }
+    if (/\s/.test(ch)) { endWord(); i++; continue; }
+    if (ch === ";" || ch === "|" || ch === "&" || ch === "(" || ch === ")") { endSeg(); i++; continue; }
+    if (ch === ">") { endWord(); seg.redirect = true; i++; continue; }
+    if (ch === "<") { endWord(); i++; continue; }
+    add(ch); i++;
+  }
+  endSeg();
+  return segs;
+}
+
 export function riskClass(tool, input, cwd) {
   const t = claudeToolName(tool);
   const i = input || {};
   if (t === "Bash") {
-    const c = String(i.command || "");
-    for (const seg of c.split(/&&|\|\||[;|\n]/)) {
-      const w = seg.trim().split(/\s+/).map((x) => x.replace(/^['"]|['"]$/g, ""));
+    for (const seg of shellSegments(i.command)) {
+      const w = seg.words;
+      for (const inner of seg.inner) { const r = riskClass(tool, { command: inner }, cwd); if (r) return r; }
       const gi = w.indexOf("git");
       if (gi >= 0) {
         const g = w.slice(gi + 1);
@@ -190,7 +261,7 @@ export function riskClass(tool, input, cwd) {
           if (tg.some((x) => /(^|\/)\.git(\/|$)/.test(x))) return "write under .git";
         }
       }
-      if (/(^|[\s/'"=>])\.git(\/|\s|$)/.test(seg) && (/>/.test(seg) || /^(rm|mv|cp|tee|truncate|dd|ln|chmod|sed)\b/.test(seg.trim()))) return "write under .git";
+      if (w.some((x) => /(^|\/)\.git(\/|$)/.test(x)) && (seg.redirect || /^(rm|mv|cp|tee|truncate|dd|ln|chmod|sed)$/.test(w[0] || ""))) return "write under .git";
     }
     return "";
   }
@@ -219,6 +290,21 @@ export function isFastRead(tool, input) {
   return true;
 }
 
+// SHIM PATH (SDK ROOT C 2026-11-06, run 42289814533): OpenCode's bash tool runs /bin/zsh on macOS, whose default PATH
+// has no ~/.local/bin, so "zsh:1: command not found: wkskill" and a Mac user could never pay the intent lock. A bash call
+// that names wkskill or wk-verify gets the shim dir (WK_LINK_DIR, else ~/.local/bin, where harness install.sh links
+// them) prepended to PATH for that one command; nothing else changes. Returns the command to run (unchanged when the
+// shim is absent or the command names neither shim).
+export function withShimPath(tool, args, linkDir) {
+  if (claudeToolName(tool) !== "Bash" || !args || typeof args.command !== "string") return args && args.command;
+  const c = args.command;
+  if (!/(^|[\s;&|(`])(wkskill|wk-verify)(\s|$)/.test(c)) return c;
+  const dir = linkDir || process.env.WK_LINK_DIR || join(homedir(), ".local", "bin");
+  if (!existsSync(join(dir, "wkskill")) && !existsSync(join(dir, "wk-verify"))) return c;
+  if (c.startsWith("PATH=")) return c;
+  return "PATH=" + JSON.stringify(dir) + ':"$PATH"; export PATH; ' + c;
+}
+
 // PER-CALL INJECTION (owner 2026-11-06: "so we must force our settings onto every model call OpenCode makes").
 // experimental.chat.system.transform appends RULES to the system array of EVERY model request, so a model that never
 // saw kih (Qwen, a fresh provider) still gets the reflex body. Short, fixed, no secrets. RULES_MARK makes the append
@@ -251,7 +337,9 @@ export function onLoadLines(kihDir) {
       res(lines.slice(0, 3).map((l) => l.slice(0, 240)));
     };
     try {
-      const c = spawn(cands.find((p) => p === "wkskill" || existsSync(p)), ["read", "on-load"], { stdio: ["ignore", "pipe", "ignore"] });
+      const target = cands.find((p) => p === "wkskill" || existsSync(p)), opt = { stdio: ["ignore", "pipe", "ignore"] };
+      // Windows: a shell-less spawn cannot run a .cmd shim, the bare wkskill name (PATHEXT) or an extensionless sh script
+      const c = process.platform !== "win32" ? spawn(target, ["read", "on-load"], opt) : /\.exe$/i.test(target) ? spawn(target, ["read", "on-load"], opt) : /\.(cmd|bat)$/i.test(target) || target === "wkskill" ? spawn(target, ["read", "on-load"], { ...opt, shell: true }) : spawn("sh", [target.replace(/\\/g, "/"), "read", "on-load"], opt);
       c.stdout.on("data", (d) => { out += d; if (out.length > 65536) c.kill("SIGKILL"); });
       c.on("error", finish); c.on("close", finish);
       setTimeout(() => { try { c.kill("SIGKILL"); } catch {} finish(); }, 8000).unref();

package/package.json

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

@@ -51,6 +51,8 @@ export const WisdomKernel = async (ctx = {}, options = {}) => {
             (tail ? ": " + tail : "") + ". Fix the harness (wkappbot-code doctor) and retry.");
         }
       }
+      // macOS /bin/zsh has no ~/.local/bin on PATH: a wkskill call gets the shim dir for that one command (lib/wk-hook.js).
+      try { if (args && typeof args.command === "string") args.command = H.withShimPath(inp.tool, args); } catch {}
     },
     "tool.execute.after": async (input, output) => {
       try {