wkappbot-code 0.3.10 → 0.3.12

package/bin/postinstall.js

@@ -2,71 +2,89 @@
 // 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` (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, globalBinDir, markRunning, parseDoctor, platformOf, selfTest, withPathFirst, 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"];
+  // 0.3.12: no --no-npm -- the worker installs the pinned OpenCode (npm -g, so `opencode` lands on PATH beside wkappbot-code);
+  // the selftests keep their machine untouched by adding --no-npm through WKAPPBOT_CODE_INSTALL_ARGS.
+  const args = [CLI, "install"];
   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)
+  // the global npm bin dir holds `opencode` right after the install, whether or not the user PATH names it yet
+  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 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/wkappbot-code.js

@@ -40,6 +40,7 @@ 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 } from "../lib/rmtree.js"; import { plainFileUrl } from "../lib/fileurl.js";
 import { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
+import { files as setupFiles, 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"));
@@ -382,7 +383,21 @@ function recordPrior(prev) {
     hooksDirExisted: existsSync(HOOKS_DIR()), shimsExisting: shimCandidates().filter((p) => existsSync(p) || isSymlink(p)) };
 }
 
+// A user's own `wkappbot-code install` right after `npm i -g` must not race the background setup worker (both wrote the
+// same core file; SDK run 42504778443, install rc 1): wait for a live worker's postinstall.running to go, at most 10 min.
+function waitForSetupWorker() {
+  if (process.env.WKAPPBOT_CODE_SETUP_WORKER === "1") return;   // the worker's own install
+  const f = setupFiles(homedir());
+  const alive = () => { try { const r = JSON.parse(readFileSync(f.running, "utf8")); const age = Date.now() - Date.parse(r.at || 0); return age >= 0 && age < 30 * 60 * 1000; } catch { return false; } };
+  if (!alive()) return;
+  log("waiting for the background setup to finish (log: " + f.log + ")");
+  const nap = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  for (let i = 0; i < 600 && alive(); i++) nap(1000);
+  log(alive() ? "background setup still running after 10 min; installing anyway" : "background setup finished; continuing");
+}
+
 function install(o) {
+  waitForSetupWorker();
   const prev = readState(o);
   const st = { version: PKG.version, at: new Date().toISOString(), prior: recordPrior(prev) };
   let bad = 0;
@@ -396,7 +411,9 @@ function install(o) {
     if (have === OPENCODE_VERSION) log("opencode " + have + " already installed");
     else {
       log("npm install -g opencode-ai@" + OPENCODE_VERSION + " (was: " + (have || "none") + ")");
-      execFileSync("npm", ["install", "-g", "opencode-ai@" + OPENCODE_VERSION, "--no-audit", "--no-fund"], { shell: process.platform === "win32",  stdio: "inherit" });
+      // 0.3.12: a failed OpenCode install (offline, no npm rights) must not abort the harness, plugin and config parts below.
+      try { execFileSync("npm", ["install", "-g", "opencode-ai@" + OPENCODE_VERSION, "--no-audit", "--no-fund"], { shell: process.platform === "win32",  stdio: "inherit" }); }
+      catch (e) { bad++; log("opencode: npm install FAILED (" + String(e.message).split("\n")[0] + ") -- run: npm install -g opencode-ai@" + OPENCODE_VERSION); }
     }
   }
   const dest = binDest(o);
@@ -494,6 +511,15 @@ function uninstall(o) {
   for (const p of st.shims || []) {
     if (isSymlink(p) || existsSync(p)) { rmSync(p, { force: true }); log("shim: removed " + p); }
   }
+  // 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);
+  let linkRemoved = "";
+  for (const p of new Set(shimCandidates().concat([join(homedir(), ".local", "bin", "wkappbot")]))) {
+    if (!isSymlink(p) || (st.shims || []).includes(p)) continue;
+    let tgt = ""; try { tgt = resolve(dirname(p), readlinkSync(p)); } catch {}
+    if (tgt && real(tgt) === real(core)) { rmSync(p, { force: true }); linkRemoved = p; log("shim: removed " + p + " (a link to the core this install placed, " + core + ")"); }
+    else log("shim: kept " + p + " (not a link to " + core + ")");
+  }
   // 4. the harness dirs we created, the plugin entry and our config folder
   // 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) => {
@@ -515,7 +541,7 @@ function uninstall(o) {
   } catch {}
   rmTree(STATE_HOME());
   rmTree(join(configDir(o), "wkappbot-code"));
-  log("uninstall done. Kept: opencode-ai, the wkappbot core (" + ((st.bin && st.bin.dest) || binDest(o)) + ") and its skills, and this CLI (npm rm -g wkappbot-code)");
+  log("uninstall done." + (linkRemoved ? " Removed the link " + linkRemoved + "." : "") + " Kept: opencode-ai, the wkappbot core (" + core + ") and its skills, and this CLI (npm rm -g wkappbot-code)");
   return rc;
 }
 
@@ -616,6 +642,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/config.js

@@ -16,6 +16,8 @@ export const PROVIDERS = [
   ["GROQ_API_KEY", "groq", "groq/llama-3.3-70b-versatile"],
   ["OPENROUTER_API_KEY", "openrouter", "openrouter/anthropic/claude-sonnet-4.5"],
 ];
+// The free OpenCode tier: no API key, no login (opencode.ai Zen free models). Used only when the user set nothing.
+export const FREE_MODEL = "opencode/big-pickle";
 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).
@@ -34,6 +36,8 @@ export function detect({ env = process.env, user = {}, pluginUrl = "", kih = "",
     else {
       const a = authProviders(env)[0];
       if (a) it.model = { value: defaultModel(a), source: "opencode auth login (" + a + ")" };
+      // 0.3.12: nothing set anywhere -> the free OpenCode tier (no key, no login), so a fresh install opens a working start screen
+      else it.model = { value: FREE_MODEL, source: "OpenCode free default, no key needed" };
     }
   }
   if (it.model) it.provider = { value: it.model.value.split("/")[0], source: it.model.source };

package/lib/setup-run.js

@@ -0,0 +1,153 @@
+// 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, 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 { delimiter, dirname, 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.
+// 0.3.12: `opencode` is looked up on PATH first, then beside this CLI (argv1 = the npm bin dir where `npm i -g opencode-ai`
+// linked it), so a global prefix that is not on the user PATH still opens it.
+export function launchOpenCode(env = process.env, argv1 = process.argv[1] || "") {
+  const run = (cmd, e) => spawnSync(cmd, [], { stdio: "inherit", shell: IS_WIN, env: e });
+  let r = run("opencode", env);
+  if (r.error && argv1) r = run("opencode", withPathFirst({ ...env }, dirname(argv1)));
+  if (r.error) return null;
+  return r.status ?? 1;
+}
+
+// The npm global bin dir (where `npm i -g` links binaries): prefix/bin, or the prefix itself on Windows. "" when unknown.
+export function globalBinDir(env = process.env) {
+  const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", env, shell: IS_WIN, timeout: 30000 });
+  const p = r.status === 0 ? String(r.stdout || "").trim().split(/\r?\n/).pop() : "";
+  return p ? (IS_WIN ? p : join(p, "bin")) : "";
+}
+// env with dir first on PATH (the key is spelled Path on Windows).
+export function withPathFirst(env, dir) {
+  if (!dir) return env;
+  const k = Object.keys(env).find((x) => x.toLowerCase() === "path") || "PATH";
+  env[k] = dir + delimiter + (env[k] || "");
+  return env;
+}

package/lib/wk-bin-acquire.sh

@@ -130,7 +130,9 @@ repo_file() {
   echo "$REPO/bin/$rel"
 }
 
-# install_file SRC DEST LABEL -- copy via .new then mv; "up to date" when DEST already matches.
+# install_file SRC DEST LABEL -- copy via a per-process .new.PID then mv; "up to date" when DEST already matches.
+# The temp name is unique per process: two installs at once (npm's background setup and a user's own
+# `wkappbot-code install`, SDK run 42504778443) both wrote DEST.new and one failed with cp: File exists.
 install_file() {
   command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "install_file" || true
   local src="$1" dest="$2" label="$3" sum verb="installed"
@@ -141,9 +143,11 @@ install_file() {
   fi
   if [ "$WK_DRY" = 1 ]; then verb="would install"; fi
   run mkdir -p "$(dirname "$dest")"
-  run cp "$src" "$dest.new"
-  run chmod +x "$dest.new"
-  run mv -f "$dest.new" "$dest"
+  local tmp="$dest.new.$$"
+  run rm -f "$tmp"
+  run cp "$src" "$tmp"
+  run chmod +x "$tmp"
+  run mv -f "$tmp" "$dest"
   echo "$verb: $dest (source: $label) sha256=$sum"
 }
 

package/package.json

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