wkappbot-code 0.3.0 → 0.3.1

package/README.md

@@ -26,13 +26,12 @@ bash wkappbot-code/selftest.sh           # RESULT N/N; --synthetic-only where no
 
 ### One command installs everything
 
-Get the CLI by one of four roads, then run `wkappbot-code install` once:
+Get the CLI by one of three roads, then run `wkappbot-code install` once:
 
 ```bash
 npm i -g https://kiexpert.github.io/wkappbot-kih/wkappbot-code/wkappbot-code.tgz   # web: the scrub-gated tgz the SDK workflow ships daily (SHA256SUMS + version.json beside it)
 npm i -g wkappbot-code                                                        # registry (published only when the SDK has NPM_TOKEN)
-npm i -g --install-links git+https://github.com/kiexpert/wkappbot-kih.git     # git: the repo ROOT package exposes the same bin
-npm pack ./wkappbot-code && npm i -g ./wkappbot-code-0.3.0.tgz                  # from a checkout
+npm pack ./wkappbot-code && npm i -g ./wkappbot-code-0.3.1.tgz                  # from a checkout
 
 wkappbot-code install      # every part below, idempotent
 wkappbot-code doctor       # one PASS/WARN/FAIL/SKIP row per part
@@ -40,7 +39,6 @@ wkappbot-code --version
 # the old command name wk-appbot-code (0.2.x) still works: it is a second bin entry for the same file
 ```
 
-The git road needs `--install-links`: without it npm 10 links the bin to a temp clone it then deletes.
 
 | part | what `install` lays down | skip with |
 |---|---|---|
@@ -72,4 +70,5 @@ The kih lite hooks stay live in the guest. Each question is a prompt event, and
 
 ## Floor
 
-Signing, submitting and paying stay human-only. Never install kih or anything built from it onto the SK laptop.
+
+Signing, submitting and paying stay human-only.

package/bin/wkappbot-code.js

@@ -14,6 +14,10 @@
 //                  a READ-ONLY copy with no git remote. A user's own skill edits go to the private
 //                  home ~/.wkappbot/private-skills (a local git repo, no remote)  skip: --no-skills
 //   wkappbot-code doctor  [opts]       one PASS/WARN/FAIL/SKIP row per part (exit 1 if a required part fails)
+//   wkappbot-code update  [opts]       newer version.json -> tgz sha256-checked -> npm i -g -> install --update (lib/update.js)
+//   wkappbot-code config  [opts]       detect provider/model/plugin/harness, edit at a TTY, merge into opencode.json (lib/config.js)
+// install/doctor/config check for a newer version at most once a day (WKAPPBOT_CODE_NO_UPDATE_CHECK=1 turns it off;
+// --auto-update or WKAPPBOT_CODE_AUTO_UPDATE=1 applies it). config opts: --yes, --project, --set key=value
 // opts: --config-dir DIR, --kih-dir DIR, --bin-dest FILE, --hq-dir DIR
 // env (mock and relocation): WK_BIN_BASE (SDK release base), WK_HARNESS_BASE (web harness base),
 //   WK_HARNESS_DIR (~/.wk-harness), WK_BIN_DEST, WK_APPBOT_HQ, WK_LINK_DIR, WK_PRIVATE_SKILLS,
@@ -30,6 +34,8 @@ 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 { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
 
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
@@ -41,7 +47,7 @@ const IS_WIN = process.platform === "win32";
 
 function parseArgs(argv) {
   const o = { cmd: argv[0] || "help", npm: true, bin: true, harness: true, skills: true, webHarness: false,
-    configDir: "", kihDir: "", binDest: "", hqDir: "" };
+    configDir: "", kihDir: "", binDest: "", hqDir: "", update: false, autoUpdate: false, yes: false, project: false, sets: [] };
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--no-npm") o.npm = false;
@@ -53,6 +59,11 @@ function parseArgs(argv) {
     else if (a === "--kih-dir") o.kihDir = argv[++i] || "";
     else if (a === "--bin-dest") o.binDest = argv[++i] || "";
     else if (a === "--hq-dir") o.hqDir = argv[++i] || "";
+    else if (a === "--update") o.update = true;
+    else if (a === "--auto-update") o.autoUpdate = true;
+    else if (a === "--yes" || a === "-y") o.yes = true;
+    else if (a === "--project") o.project = true;
+    else if (a === "--set") o.sets.push(argv[++i] || "");
     else { console.error("unknown option: " + a); process.exit(64); }
   }
   return o;
@@ -101,15 +112,7 @@ export function platformId(platform = process.platform, arch = process.arch) {
 
 // Merge our plugin entry into a user config: drop any older wisdom-kernel entry, append the new one.
 export function mergeConfig(user, template, url, kih) {
-  const out = { ...user };
-  const ours = [url, { kihDir: kih }];
-  const keep = (Array.isArray(user.plugin) ? user.plugin : []).filter((p) => !String(Array.isArray(p) ? p[0] : p).includes("wisdom-kernel"));
-  out.plugin = [...keep, ours];
-  if (!out.$schema && template.$schema) out.$schema = template.$schema;
-  if (!out.provider) out.provider = template.provider;
-  else if (template.provider) for (const [k, v] of Object.entries(template.provider)) if (!(k in out.provider)) out.provider[k] = v;
-  if (!out.permission) out.permission = template.permission;
-  return out;
+  return buildConfig(user, { plugin: { value: url }, harness: { value: kih } }, template);
 }
 
 // ---- part: bin ------------------------------------------------------------------------------------
@@ -266,7 +269,7 @@ function installSkills(o, dest) {
 }
 
 // ---- install --------------------------------------------------------------------------------------
-function installPlugin(o, kih) {
+function installPlugin(o, kih, kihSource) {
   const cfg = configDir(o);
   mkdirSync(join(cfg, "wkappbot-code"), { recursive: true });
   const dest = join(cfg, "wkappbot-code", "wisdom-kernel.js");
@@ -275,29 +278,36 @@ function installPlugin(o, kih) {
   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"));
-  const target = join(cfg, "opencode.json");
-  let next, note = "";
+  const target = o.project ? join(process.cwd(), "opencode.json") : join(cfg, "opencode.json");
+  let user = {}, raw = "";
   if (existsSync(target)) {
-    const raw = readFileSync(target, "utf8");
-    let user;
+    raw = readFileSync(target, "utf8");
     try { user = JSON.parse(raw); } catch { user = null; }
-    if (!user) {
-      // JSONC or broken: never rewrite what we cannot parse; leave a sidecar to merge by hand.
-      const side = join(cfg, "wkappbot-code.json");
-      writeFileSync(side, JSON.stringify(mergeConfig({}, tmpl, url, kih), null, 2) + "\n");
-      log(target + " is not plain JSON; left untouched, wrote " + side + " -- merge its plugin entry by hand");
-      return;
-    }
-    next = mergeConfig(user, tmpl, url, kih);
-    if (JSON.stringify(next, null, 2) + "\n" === raw) note = " (unchanged)";
-    else {
+  }
+  const it = detect({ user: user || {}, pluginUrl: url, kih, kihSource: kihSource || "kih checkout" });
+  for (const k of applySets(it, o.sets)) log("config: unknown --set key " + k + " (provider|model|plugin|harness)");
+  printDetected(it, log);
+  if (process.stdin.isTTY && process.stdout.isTTY && !o.yes) askEach(it);
+  if (!user) {
+    // JSONC or broken: never rewrite what we cannot parse; leave a sidecar to merge by hand.
+    const side = join(dirname(target), "wkappbot-code.json");
+    writeFileSync(side, JSON.stringify(buildConfig({}, it, tmpl), null, 2) + "\n");
+    log(target + " is not plain JSON; left untouched, wrote " + side + " -- merge its plugin entry by hand");
+    return;
+  }
+  const text = JSON.stringify(buildConfig(user, it, tmpl), null, 2) + "\n";
+  let note = "";
+  if (raw && text === raw) note = " (unchanged)";
+  else {
+    if (raw) {
       const bak = target + ".bak-" + stamp();
       copyFileSync(target, bak);
       note = " (merged; backup " + bak + ")";
     }
-  } else next = mergeConfig({}, tmpl, url, kih);
-  writeFileSync(target + ".tmp", JSON.stringify(next, null, 2) + "\n");
-  renameSync(target + ".tmp", target);
+    for (const l of lineDiff(raw, text)) log("diff " + l);
+    writeFileSync(target + ".tmp", text);
+    renameSync(target + ".tmp", target);
+  }
   log("plugin: " + url);
   log("config: " + target + note);
 }
@@ -305,6 +315,7 @@ function installPlugin(o, kih) {
 function install(o) {
   const st = { version: PKG.version, at: new Date().toISOString() };
   let bad = 0;
+  if (o.update) log("install --update: refreshing the core, the harness and the public skills");
   if (o.npm) {
     const have = opencodeVersion();
     if (have === OPENCODE_VERSION) log("opencode " + have + " already installed");
@@ -330,7 +341,7 @@ function install(o) {
   }
   st.skills = o.skills ? installSkills(o, dest) : { skipped: true };
   if (o.skills && !st.skills.ok) { bad++; log("skills: FAILED -- " + (st.skills.note || "on-load missing from the HQ")); }
-  installPlugin(o, kih);
+  installPlugin(o, kih, (st.harness.mode === "web" && st.harness.ok) ? "web harness" : "kih checkout");
   st.kihDir = kih;
   writeFileSync(statePath(o), JSON.stringify(st, null, 2) + "\n");
   log("kih:    " + (kih || "NOT FOUND -- plugin fails open until --kih-dir or WK_KIH_DIR points at a kih checkout"));
@@ -358,6 +369,8 @@ function doctor(o) {
   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);
+  const oc = configRow(join(cfg, "opencode.json"));
+  add("opencode-config", oc.ok, oc.detail, false);
   // bin: the core answers --version
   const dest = o.binDest ? resolve(o.binDest) : (st.bin && st.bin.dest) || binDest(o);
   let core = "";
@@ -372,6 +385,14 @@ function doctor(o) {
   const hk = hasHook(k);
   if (st.harness && st.harness.skipped && !hk) add("kih-hook", false, "skipped (--no-harness)", false, true);
   else add("kih-hook", hk, k ? k + (st.harness && st.harness.mode ? "  (" + st.harness.mode + ")" : "") : "not found", !!(st.harness && st.harness.mode === "web"));
+  // guards: which guard set the plugin can run. The full set needs PowerShell; without it the plugin falls back to
+  // the bash lite harness (intent lock, study lock), so this row WARNs instead of passing silently (QA 2026-11-06).
+  if (hk) {
+    const psDirs = String(process.env.PATH || "").split(IS_WIN ? ";" : ":");
+    const ps = ["pwsh", "pwsh.exe", "powershell.exe", "powershell"].find((n) => psDirs.some((d) => d && existsSync(join(d, n))));
+    const lite = existsSync(join(k, "tools", "wkharness-lite.sh"));
+    add("guards", !!ps, ps ? "full guard set (" + ps + ")" : lite ? "no PowerShell on PATH: lite guards only (intent lock, study lock); install pwsh 7 for the full set" : "no PowerShell and no lite harness: every tool call is let through", !ps && !lite);
+  }
   // skills: the HQ holds on-load and the core prints it
   const hq = (st.skills && st.skills.hq) || hqDir(o, dest);
   if (st.skills && st.skills.skipped) add("skills", false, "skipped (--no-skills)", false, true);
@@ -399,6 +420,8 @@ function doctor(o) {
   const rem = existsSync(join(ph, ".git")) ? gitRemotes(ph) : [];
   const remNote = rem && rem.length ? "; private home " + ph + " HAS remote(s) " + rem.join(",") : "; private home " + ph + " has no remote";
   add("skill-push", login === OWNER_LOGIN && !(rem && rem.length), "= owner-only; a push would use github login " + login + remNote, false);
+  const ur = updateRow(PKG.version);
+  add("update", !!ur.ok, ur.detail, false, !!ur.skip);
   let bad = 0;
   for (const r of rows) {
     console.log((r.skip ? "SKIP " : r.ok ? "PASS " : r.required ? "FAIL " : "WARN ") + r.name + "  " + r.detail);
@@ -408,13 +431,23 @@ function doctor(o) {
 }
 
 const o = parseArgs(process.argv.slice(2));
+// install --update (from update) and these flags are forwarded to the re-run install of a fresh version.
+const fwd = process.argv.slice(3).filter((a) => a !== "--auto-update");
+const upd = () => runUpdate({ current: PKG.version, cliPath: process.argv[1], installArgs: fwd, log: console.log });
+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();
+}
 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 "doctor": process.exit(doctor(o));
+  case "update": process.exit(upd());
+  case "config": installPlugin(o, kihDir(o), kihCheckout(o) ? "kih checkout" : "web harness"); process.exit(0);
   default:
     console.log("usage: wkappbot-code --version | install [--no-npm] [--no-bin] [--no-harness] [--no-skills] [--web-harness]\n" +
-      "         [--config-dir DIR] [--kih-dir DIR] [--bin-dest FILE] [--hq-dir DIR] | doctor [--config-dir DIR]");
+      "         [--config-dir DIR] [--kih-dir DIR] [--bin-dest FILE] [--hq-dir DIR] [--update] [--auto-update] | doctor [--config-dir DIR]\n" +
+      "       | update [install opts] | config [--yes] [--project] [--set key=value] [--config-dir DIR]");
     process.exit(o.cmd === "help" || o.cmd === "--help" ? 0 : 64);
 }

package/lib/config.js

@@ -0,0 +1,122 @@
+// config.js -- the minimum opencode config for wkappbot-code (owner 2026-11-06: detect the needed items, let the user
+// edit them, then generate). Four items only: provider and model (from which API-key env var is PRESENT, or an
+// existing `opencode auth` login -- values are never read or printed), the wisdom-kernel plugin URL, the harness dir.
+// The file is MERGED: a backup first, every user key kept in place, no secret written (providers read env vars).
+// Spec: wkappbot skill read agent-harness-landscape-2026-howto
+import { existsSync, readFileSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const KEYS = ["provider", "model", "plugin", "harness"];
+// env var -> opencode provider id -> default model ("provider/model", editable with --set model=...)
+export const PROVIDERS = [
+  ["ANTHROPIC_API_KEY", "anthropic", "anthropic/claude-sonnet-5-5"],
+  ["OPENAI_API_KEY", "openai", "openai/gpt-5"],
+  ["GEMINI_API_KEY", "google", "google/gemini-2.5-pro"],
+  ["GROQ_API_KEY", "groq", "groq/llama-3.3-70b-versatile"],
+  ["OPENROUTER_API_KEY", "openrouter", "openrouter/anthropic/claude-sonnet-4.5"],
+];
+const defaultModel = (prov) => { const d = PROVIDERS.find((p) => p[1] === prov); return d ? d[2] : prov + "/default"; };
+
+// Provider ids of an existing `opencode auth login` (key names only).
+export function authProviders(env = process.env) {
+  const p = join(env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "opencode", "auth.json");
+  try { return Object.keys(JSON.parse(readFileSync(p, "utf8")) || {}); } catch { return []; }
+}
+
+// Detect the four items. user = the existing config object ({} when none).
+export function detect({ env = process.env, user = {}, pluginUrl = "", kih = "", kihSource = "kih checkout" } = {}) {
+  const it = {};
+  if (user && user.model) it.model = { value: String(user.model), source: "existing config" };
+  else {
+    const hit = PROVIDERS.find(([k]) => env[k]);
+    if (hit) it.model = { value: hit[2], source: "env " + hit[0] + " present" };
+    else {
+      const a = authProviders(env)[0];
+      if (a) it.model = { value: defaultModel(a), source: "opencode auth login (" + a + ")" };
+    }
+  }
+  if (it.model) it.provider = { value: it.model.value.split("/")[0], source: it.model.source };
+  if (pluginUrl) it.plugin = { value: pluginUrl, source: "installed package" };
+  if (kih) it.harness = { value: kih, source: kihSource };
+  return it;
+}
+
+export function printDetected(it, log) {
+  for (const k of KEYS) log(it[k] ? "detected " + k + " = " + it[k].value + " (" + it[k].source + ")" : "missing " + k);
+}
+
+// Keep provider and model consistent after an override.
+function reconcile(it, changed) {
+  if (changed === "model" && it.model) it.provider = { value: it.model.value.split("/")[0], source: it.model.source, forced: true };
+  if (changed === "provider" && it.provider && (!it.model || it.model.value.split("/")[0] !== it.provider.value))
+    it.model = { value: defaultModel(it.provider.value), source: it.provider.source, forced: true };
+}
+
+// --set key=value overrides (provider|model|plugin|harness). Returns the unknown keys.
+export function applySets(it, sets) {
+  const bad = [];
+  for (const s of sets) {
+    const i = s.indexOf("=");
+    const k = i > 0 ? s.slice(0, i) : s;
+    if (!KEYS.includes(k)) { bad.push(k); continue; }
+    it[k] = { value: s.slice(i + 1), source: "--set", forced: true };
+    reconcile(it, k);
+  }
+  return bad;
+}
+
+function readLineSync() {
+  const b = Buffer.alloc(1);
+  let s = "";
+  for (;;) {
+    let n = 0;
+    try { n = readSync(0, b, 0, 1, null); } catch (e) { if (e.code === "EAGAIN") continue; break; }
+    if (n === 0) break;
+    const c = b.toString("utf8");
+    if (c === "\n") break;
+    s += c;
+  }
+  return s.replace(/\r$/, "");
+}
+
+// At a TTY: one question per item; Enter keeps the detected value.
+export function askEach(it, out = process.stdout) {
+  for (const k of KEYS) {
+    out.write(k + " [" + (it[k] ? it[k].value : "none") + "]: ");
+    const a = readLineSync().trim();
+    if (a) { it[k] = { value: a, source: "typed", forced: true }; reconcile(it, k); }
+  }
+}
+
+// Merge the items into the user's config: user keys stay where they are; the wisdom-kernel plugin entry is replaced;
+// the template's provider/permission are added only where the user has none; model only when absent or overridden.
+export function buildConfig(user, it, template) {
+  const out = { ...user };
+  if (!out.$schema && template.$schema) out.$schema = template.$schema;
+  const ours = [it.plugin ? it.plugin.value : "", { kihDir: it.harness ? it.harness.value : "" }];
+  const keep = (Array.isArray(user.plugin) ? user.plugin : []).filter((p) => !String(Array.isArray(p) ? p[0] : p).includes("wisdom-kernel"));
+  out.plugin = [...keep, ours];
+  if (!out.provider) out.provider = template.provider;
+  else if (template.provider) for (const [k, v] of Object.entries(template.provider)) if (!(k in out.provider)) out.provider[k] = v;
+  if (!out.permission) out.permission = template.permission;
+  if (it.model && (it.model.forced || !user.model)) out.model = it.model.value;
+  return out;
+}
+
+// A small line diff for the printout: removed lines first, then added lines.
+export function lineDiff(before, after) {
+  const A = before.split("\n"), B = after.split("\n");
+  const sa = new Set(A), sb = new Set(B);
+  return [...A.filter((l) => l && !sb.has(l)).map((l) => "- " + l), ...B.filter((l) => l && !sa.has(l)).map((l) => "+ " + l)];
+}
+
+// The doctor row for an opencode.json path: { ok, detail }.
+export function configRow(target) {
+  let c = null;
+  try { c = JSON.parse(readFileSync(target, "utf8")); } catch { return { ok: false, detail: existsSync(target) ? target + " is not plain JSON" : "missing " + target }; }
+  const wired = (c.plugin || []).some((p) => String(Array.isArray(p) ? p[0] : p).includes("wisdom-kernel"));
+  const model = c.model ? String(c.model) : "";
+  if (model && wired) return { ok: true, detail: "provider " + model.split("/")[0] + ", model " + model + ", plugin wired" };
+  return { ok: false, detail: [model ? "" : "missing model", wired ? "" : "plugin not wired"].filter(Boolean).join(", ") + " in " + target };
+}

package/lib/update.js

@@ -0,0 +1,127 @@
+// update.js -- wkappbot-code self-update (owner 2026-11-06: an auto-update in the launcher, with QA).
+// Remote: <base>/version.json = {"name":"wkappbot-code","version":"X.Y.Z","tgz":"wkappbot-code.tgz","sha256":"<64 hex>"}
+// as the SDK Pages workflow publishes it; "tgz" (or "url"/"file") is resolved relative to version.json, and a missing
+// sha256 is read from SHA256SUMS beside it. WKAPPBOT_CODE_UPDATE_URL overrides the address (tests);
+// 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 { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_UPDATE_URL = "https://kiexpert.github.io/wkappbot-kih/wkappbot-code/version.json";
+export const updateUrl = () => process.env.WKAPPBOT_CODE_UPDATE_URL || DEFAULT_UPDATE_URL;
+export const stampPath = () => join(homedir(), ".wkappbot-code", "last-update-check");
+const DAY_MS = 24 * 3600 * 1000;
+
+// -1 / 0 / 1 on the first three numeric parts ("0.3.10" > "0.3.9").
+export function cmpVer(a, b) {
+  const p = (v) => String(v || "").replace(/^v/, "").split(/[.+-]/).slice(0, 3).map((n) => parseInt(n, 10) || 0);
+  const x = p(a), y = p(b);
+  for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0) ? 1 : -1;
+  return 0;
+}
+
+function curl(url, out, secs) {
+  const r = spawnSync("curl", ["-fsSL", "-m", String(secs), url, "-o", out], { encoding: "utf8" });
+  return r.status === 0 ? "" : "curl " + url + " rc " + r.status + (r.stderr ? " " + r.stderr.trim() : "");
+}
+const rel = (base, p) => { try { return new URL(p, base).href; } catch { return p; } };
+
+// Read the remote version.json: { ok, version, sha256, tgzUrl } or { ok: false, err }.
+export function readRemote(secs = 20) {
+  const url = updateUrl();
+  const tmp = mkdtempSync(join(tmpdir(), "wkappbot-code-upd-"));
+  try {
+    const err = curl(url, join(tmp, "v.json"), secs);
+    if (err) return { ok: false, err };
+    let v = null;
+    try { v = JSON.parse(readFileSync(join(tmp, "v.json"), "utf8")); } catch { return { ok: false, err: "version.json is not JSON" }; }
+    if (!v || !v.version) return { ok: false, err: "version.json has no version" };
+    // A page for another package (or an unnamed one) is never an update: no downgrade, no cross-install.
+    if (!["wkappbot-code", "wk-appbot-code"].includes(String(v.name || ""))) return { ok: false, foreign: true, err: "version.json names package " + JSON.stringify(v.name || "") + ", not wkappbot-code" };
+    const tgzUrl = rel(url, v.url || v.tgz || v.file || "wkappbot-code.tgz");
+    let sha = String(v.sha256 || "").toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(sha) && !curl(rel(url, "SHA256SUMS"), join(tmp, "sums"), secs)) {
+      const name = tgzUrl.split("/").pop();
+      for (const l of readFileSync(join(tmp, "sums"), "utf8").split("\n")) {
+        const m = /^([0-9a-f]{64})\s+\*?(\S+)$/i.exec(l.trim());
+        if (m && m[2].split("/").pop() === name) sha = m[1].toLowerCase();
+      }
+    }
+    return { ok: true, version: String(v.version), sha256: sha, tgzUrl, source: "pages" };
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+}
+
+// The second source (owner 2026-11-06: NPM_TOKEN added, the SDK publishes to the registry): npm view, silent offline.
+// WKAPPBOT_CODE_NO_REGISTRY=1 skips it (tests).
+export function readRegistry(secs = 15) {
+  if (process.env.WKAPPBOT_CODE_NO_REGISTRY === "1") return { ok: false, err: "registry check off" };
+  const r = spawnSync("npm", ["view", "wkappbot-code", "version"], { encoding: "utf8", timeout: secs * 1000 });
+  const v = (r.stdout || "").trim().split("\n").pop();
+  return r.status === 0 && /^\d+\.\d+\.\d+/.test(v) ? { ok: true, version: v, source: "registry" } : { ok: false, err: "npm view rc " + r.status };
+}
+const readAny = (secs) => { const p = readRemote(secs); if (p.ok || p.foreign) return p; const g = readRegistry(secs); return g.ok ? g : p; };
+
+// `wkappbot-code update`: a newer remote is downloaded, sha256-checked, installed with npm i -g, then the NEW CLI
+// re-runs `install --update` (core, harness, public skills). A sha mismatch changes nothing. Returns the exit code.
+export function runUpdate({ current, cliPath, installArgs = [], log = console.log }) {
+  const r = readAny(30);
+  if (r.foreign) { log("PASS update: no update (" + r.err + ")"); return 0; }
+  if (!r.ok) { log("FAIL update: cannot read " + updateUrl() + " -- " + r.err + " (registry: none)"); return 1; }
+  if (cmpVer(r.version, current) <= 0) { log("PASS update: up to date (installed " + current + ", latest " + r.version + " from " + r.source + ")"); return 0; }
+  if (r.source === "registry") {
+    // npm verifies the registry tarball's own integrity hash.
+    log("PASS update: " + r.version + " available (installed " + current + ") on the npm registry");
+    const g = spawnSync("npm", ["install", "-g", "wkappbot-code@" + r.version, "--no-audit", "--no-fund", "--silent"], { encoding: "utf8" });
+    if (g.status !== 0) { log("FAIL update: npm install -g wkappbot-code@" + r.version + " rc " + g.status); return 1; }
+    log("PASS update: npm install -g wkappbot-code " + r.version);
+    return reinstall(cliPath, installArgs, log);
+  }
+  log("PASS update: " + r.version + " available (installed " + current + ") at " + r.tgzUrl);
+  if (!/^[0-9a-f]{64}$/.test(r.sha256)) { log("FAIL update: no sha256 published for " + r.version + "; nothing changed"); return 1; }
+  const tmp = mkdtempSync(join(tmpdir(), "wkappbot-code-upd-"));
+  try {
+    const tgz = join(tmp, "wkappbot-code-" + r.version + ".tgz");
+    const err = curl(r.tgzUrl, tgz, 300);
+    if (err) { log("FAIL update: download -- " + err + "; nothing changed"); return 1; }
+    const got = createHash("sha256").update(readFileSync(tgz)).digest("hex");
+    if (got !== r.sha256) { log("FAIL update: sha256 MISMATCH (expected " + r.sha256 + ", got " + got + "); nothing changed"); return 1; }
+    log("PASS update: sha256 ok " + got);
+    const n = spawnSync("npm", ["install", "-g", tgz, "--no-audit", "--no-fund", "--silent"], { encoding: "utf8" });
+    if (n.status !== 0) { log("FAIL update: npm install -g rc " + n.status + " " + (n.stderr || "").trim()); return 1; }
+    log("PASS update: npm install -g wkappbot-code " + r.version);
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+  return reinstall(cliPath, installArgs, log);
+}
+
+// The NEW CLI (npm's bin link now points at it) refreshes the core, the harness and the public skills.
+function reinstall(cliPath, installArgs, log) {
+  const i = spawnSync(process.execPath, [cliPath, "install", "--update", ...installArgs],
+    { stdio: "inherit", env: { ...process.env, WKAPPBOT_CODE_NO_UPDATE_CHECK: "1" } });
+  log((i.status === 0 ? "PASS" : "FAIL") + " update: install --update rc " + i.status);
+  return i.status === 0 ? 0 : 1;
+}
+
+// The quiet check every other subcommand runs: at most once per 24 h (stamp written first), silent on any failure.
+// Returns the newer remote version, else "".
+export function quietCheck(current, log = console.log) {
+  if (process.env.WKAPPBOT_CODE_NO_UPDATE_CHECK === "1") return "";
+  const sp = stampPath();
+  try { if (Date.now() - statSync(sp).mtimeMs < DAY_MS) return ""; } catch {}
+  try { mkdirSync(dirname(sp), { recursive: true }); writeFileSync(sp, new Date().toISOString() + "\n"); } catch {}
+  let r = null;
+  try { r = readAny(5); } catch { return ""; }
+  if (!r || !r.ok || cmpVer(r.version, current) <= 0) return "";
+  log("wkappbot-code " + r.version + " available -- run wkappbot-code update");
+  return r.version;
+}
+
+// The doctor row: { ok, skip, detail } -- PASS when current is the latest (or newer), WARN when older, SKIP offline.
+export function updateRow(current) {
+  if (process.env.WKAPPBOT_CODE_NO_UPDATE_CHECK === "1") return { skip: true, detail: "current " + current + " (check off: WKAPPBOT_CODE_NO_UPDATE_CHECK=1)" };
+  let r = null;
+  try { r = readAny(10); } catch (e) { r = { ok: false, err: String(e) }; }
+  if (!r.ok) return { skip: true, detail: "current " + current + " / latest ? (offline: " + r.err + ")" };
+  return { ok: cmpVer(current, r.version) >= 0, detail: "current " + current + " / latest " + r.version + " (" + r.source + ")" };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wkappbot-code",
-  "version": "0.3.0",
-  "description": "wkappbot-code -- Wisdom Kernel: the pinned OpenCode bridge plus the kih harness plugin, the wkappbot core, the web harness and the latest public skills in one install",
+  "version": "0.3.1",
+  "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",
   "bin": {
     "wkappbot-code": "bin/wkappbot-code.js",

package/plugin/wisdom-kernel.js

@@ -17,17 +17,17 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // OpenCode tool id -> Claude tool name the kih guards already know.
-export const TOOL_MAP = {
+const TOOL_MAP = {
   bash: "Bash", edit: "Edit", write: "Write", read: "Read",
   glob: "Glob", grep: "Grep", list: "LS", patch: "Edit", multiedit: "MultiEdit",
   webfetch: "WebFetch", websearch: "WebSearch", task: "Agent", todowrite: "TodoWrite",
 };
 
 // pre arm budget: a hung hook is killed and the call fails OPEN, like a Claude hook timeout.
-export const PRE_TIMEOUT_MS = Number(process.env.WK_APPBOT_PRE_TIMEOUT_MS || 60000);
+const PRE_TIMEOUT_MS = Number(process.env.WK_APPBOT_PRE_TIMEOUT_MS || 60000);
 
 // OpenCode args (camelCase) -> Claude tool_input (snake_case) for the tools the guards inspect.
-export function toClaudeInput(tool, args) {
+function toClaudeInput(tool, args) {
   const a = args || {};
   switch (tool) {
     case "bash": {
@@ -55,12 +55,12 @@ export function toClaudeInput(tool, args) {
   }
 }
 
-export function claudeToolName(tool) {
+function claudeToolName(tool) {
   return TOOL_MAP[tool] || tool;
 }
 
 // The Claude-shaped hook payload for one OpenCode tool call.
-export function buildPreToolUsePayload(input, args, cwd) {
+function buildPreToolUsePayload(input, args, cwd) {
   return {
     hook_event_name: "PreToolUse",
     session_id: input.sessionID,
@@ -72,7 +72,7 @@ export function buildPreToolUsePayload(input, args, cwd) {
   };
 }
 
-export function buildPostToolUsePayload(input, output, cwd) {
+function buildPostToolUsePayload(input, output, cwd) {
   const p = buildPreToolUsePayload(input, input.args, cwd);
   p.hook_event_name = "PostToolUse";
   p.tool_response = { output: output && output.output, title: output && output.title };
@@ -80,7 +80,7 @@ export function buildPostToolUsePayload(input, output, cwd) {
 }
 
 // kih root: WK_KIH_DIR, else the checkout this file sits in (wkappbot-code/plugin -> ../..).
-export function resolveKihDir() {
+function resolveKihDir() {
   if (process.env.WK_KIH_DIR) return process.env.WK_KIH_DIR;
   try {
     const up = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -89,11 +89,36 @@ export function resolveKihDir() {
   return "";
 }
 
-// Pipe JSON into "wkharness-run.sh <arm>"; resolves {code, stdout, stderr}. Never rejects.
+// Pipe JSON into "<hook> <arm>" (wkharness-run.sh, or wkharness-lite.sh without PowerShell); resolves {code, stdout, stderr}. Never rejects.
 // No hook found = fail-open (code 0, skipped) so a missing kih never bricks OpenCode.
-export function runHook(arm, payload, opts = {}) {
+// PowerShell on PATH? The full harness (wkharness-run.sh) runs its guards in PowerShell; without one it exits 127,
+// which used to read as "no verdict" and let EVERY call through (QA 2026-11-06, fresh Linux HOME).
+function onPath(names) {
+  const dirs = String(process.env.PATH || "").split(process.platform === "win32" ? ";" : ":");
+  for (const d of dirs) for (const n of names) { try { if (d && existsSync(join(d, n))) return true; } catch {} }
+  return false;
+}
+let _ps = null;
+function hasPowerShell() {
+  if (process.env.WK_APPBOT_FORCE_LITE === "1") return false;
+  if (_ps === null) _ps = onPath(["pwsh", "pwsh.exe", "powershell.exe", "powershell"]);
+  return _ps;
+}
+
+// Which hook script serves an arm: the full harness when PowerShell is there, else the bash lite harness
+// (tools/wkharness-lite.sh: study lock, intent lock, stop lint). The prompt and session arms exist only in lite.
+function pickHook(arm, kih) {
+  if (!kih) return "";
+  const full = join(kih, ".claude", "hooks", "wkharness-run.sh"), lite = join(kih, "tools", "wkharness-lite.sh");
+  const liteArm = arm === "prompt" || arm === "session";
+  if (!liteArm && hasPowerShell() && existsSync(full)) return full;
+  if (existsSync(lite)) return lite;
+  return liteArm ? "" : full;
+}
+
+function runHook(arm, payload, opts = {}) {
   const kih = opts.kihDir ?? resolveKihDir();
-  const hook = opts.hook || process.env.WK_APPBOT_HOOK || (kih && join(kih, ".claude", "hooks", "wkharness-run.sh"));
+  const hook = opts.hook || process.env.WK_APPBOT_HOOK || pickHook(arm, kih);
   return new Promise((done) => {
     let settled = false;
     const finish = (r) => { if (!settled) { settled = true; if (timer) clearTimeout(timer); done(r); } };
@@ -125,7 +150,7 @@ export function runHook(arm, payload, opts = {}) {
 }
 
 // Claude contract: exit 2 refuses; so does a stdout JSON deny/block verdict.
-export function isRefusal(r) {
+function isRefusal(r) {
   if (r.timedOut || r.skipped) return false;
   if (r.code === 2) return true;
   try {
@@ -135,7 +160,7 @@ export function isRefusal(r) {
 }
 
 // A stdout deny JSON names its own reason; stderr then may hold only warn lines (wkharness-run.sh wk_pre_emit).
-export function refusalReason(r) {
+function refusalReason(r) {
   try {
     const j = JSON.parse(r.stdout);
     const why = (j.hookSpecificOutput && j.hookSpecificOutput.permissionDecisionReason) || j.reason;
@@ -160,9 +185,23 @@ export const WisdomKernel = async (ctx = {}, options = {}) => {
     "tool.execute.after": async (input, output) => {
       try { await runHook("post", buildPostToolUsePayload(input || {}, output, cwd), { kihDir: k, timeoutMs: 30000 }); } catch {}
     },
+    // UserPromptSubmit: arms the intent lock for the next real tool call (fail-open, never blocks the message).
+    "chat.message": async (input, output) => {
+      try {
+        const parts = (output && output.parts) || [];
+        const prompt = parts.filter((p) => p && p.type === "text" && !p.synthetic).map((p) => p.text || "").join("\n");
+        if (!prompt) return;
+        await runHook("prompt", { hook_event_name: "UserPromptSubmit", session_id: input && input.sessionID, cwd, prompt, agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
+      } catch {}
+    },
     event: async (arg) => {
       try {
         const event = arg && arg.event;
+        if (event && event.type === "session.created") {
+          const info = (event.properties && event.properties.info) || {};
+          await runHook("session", { hook_event_name: "SessionStart", session_id: info.id, cwd, source: "startup", agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
+          return;
+        }
         if (!event || event.type !== "session.idle") return;
         const sid = event.properties && event.properties.sessionID;
         await runHook("stop-archive", { hook_event_name: "Stop", session_id: sid, cwd, agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
@@ -171,4 +210,8 @@ export const WisdomKernel = async (ctx = {}, options = {}) => {
   };
 };
 
+// Helpers for the selftest ride on the plugin function, never as module exports (OpenCode calls every export).
+WisdomKernel.internals = { TOOL_MAP, PRE_TIMEOUT_MS, toClaudeInput, claudeToolName, buildPreToolUsePayload,
+  buildPostToolUsePayload, resolveKihDir, runHook, isRefusal, refusalReason, hasPowerShell, pickHook };
+
 export default WisdomKernel;