karajan-code 3.12.2 → 3.13.0

package/README.md

@@ -190,7 +190,7 @@ None of these are required. Karajan auto-skips any scanner that isn't installed,
 | Tool | Scope | Install | Installable from `kj init`? | What you get |
 |------|-------|---------|-----------------------------|--------------|
 | **SonarQube** | Any stack | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | ✅ Yes (wizard configures Docker container + token) | Code quality + security rules with line-precision in `kj audit` |
-| **OSV-Scanner** | Any stack | `go install github.com/google/osv-scanner@latest` | ❌ No (install manually) | Dependency CVE coverage broader than `npm audit` |
+| **OSV-Scanner** | Any stack | `go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest` | ❌ No (install manually) | Dependency CVE coverage broader than `npm audit` |
 | **Semgrep** | Any stack | `pipx install semgrep` | ❌ No (install manually) | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
 | **Lighthouse** | **Frontend only** | `npm install -g lighthouse` | ❌ No (install manually) | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.12.2",
+  "version": "3.13.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/scripts/build-sea.mjs

@@ -19,7 +19,7 @@
  */
 
 import { execSync } from "node:child_process";
-import { cpSync, mkdirSync, writeFileSync, statSync } from "node:fs";
+import { cpSync, mkdirSync, writeFileSync, statSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -59,10 +59,32 @@ async function main() {
 
     // ── Step 2: Generate SEA blob ───────────────────────────────────
     console.log("[2/5] Generating SEA preparation blob...");
+    // Templates travel as SEA assets (KJC-BUG-0104): the binary ships no
+    // templates/ directory, so kj init / role prompts / onboard resolved
+    // paths like $HOME/templates/skills and hit ENOENT. The runtime
+    // (src/utils/templates-root.js) reads the index asset and extracts
+    // the files to ~/.karajan/embedded-templates/<version>/ on first use.
+    const { collectTemplateFiles } = await import("./esbuild-sea.config.mjs");
+    const pkgVersion = JSON.parse(
+      readFileSync(path.join(ROOT, "package.json"), "utf8"),
+    ).version;
+    const templateFiles = collectTemplateFiles();
+    writeFileSync(
+      path.join(DIST, "templates-index.json"),
+      JSON.stringify({ version: pkgVersion, files: templateFiles }),
+    );
+    // Absolute paths: node resolves asset paths against the CWD (not the
+    // config file), so anything relative is ambiguous.
+    const assets = { "templates-index.json": path.join(DIST, "templates-index.json") };
+    for (const rel of templateFiles) {
+      assets[`templates/${rel}`] = path.join(ROOT, "templates", rel);
+    }
+    console.log(`      -> ${templateFiles.length} template assets embedded.`);
     const seaConfig = {
       main: "dist/kj-bundle.cjs",
       output: "dist/sea-prep.blob",
       disableExperimentalSEAWarning: true,
+      assets,
     };
     writeFileSync(
       path.join(DIST, "sea-config.json"),

package/scripts/esbuild-sea.config.mjs

@@ -10,7 +10,7 @@
 
 import path from "node:path";
 import fs from "node:fs/promises";
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -213,6 +213,27 @@ const auditHistoryStubPlugin = {
 };
 
 /** @type {import('esbuild').BuildOptions} */
+/**
+ * List every built-in template file, as paths relative to templates/
+ * (KJC-BUG-0104). The SEA binary ships them as SEA assets — build-sea.mjs
+ * turns this list into the sea-config `assets` map plus an index the
+ * runtime (src/utils/templates-root.js) uses to extract them on first use.
+ * Exported (instead of living in build-sea.mjs, which runs main() on
+ * import) so tests can exercise it.
+ */
+export function collectTemplateFiles(rootDir = path.join(ROOT, "templates")) {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else files.push(path.relative(rootDir, p));
+    }
+  };
+  walk(rootDir);
+  return files.sort();
+}
+
 export const seaBuildOptions = {
   entryPoints: ["src/cli.js"],
   outfile: "dist/kj-bundle.cjs",

package/src/audit/osv-findings.js

@@ -48,7 +48,7 @@ export async function collectOsvFindings(projectDir, logger = null) {
     // err.code 1 is NORMAL — we still want the stdout. Real failures are
     // ENOENT (binary missing) or stdout empty.
     if (err.code === "ENOENT") {
-      if (logger?.warn) logger.warn("osv-scanner not found in PATH — install via 'go install github.com/google/osv-scanner@latest'");
+      if (logger?.warn) logger.warn("osv-scanner not found in PATH — install via 'go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest'");
       return { available: false, reason: "osv-scanner not installed" };
     }
     if (err.killed) {

package/src/commands/init.js

@@ -7,6 +7,7 @@ import { ollamaUp, waitForOllamaReady, normalizeOllamaConfig } from "../rag/olla
 import { checkOllamaCapability, pullOllamaModel } from "../rag/ollama-capability.js";
 import { exists, ensureDir } from "../utils/fs.js";
 import { getKarajanHome } from "../utils/paths.js";
+import { getTemplatesRoot } from "../utils/templates-root.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
@@ -441,7 +442,7 @@ async function ensureReviewRules(reviewRulesPath, logger) {
 
 async function ensureCoderRules(coderRulesPath, logger) {
   if (await exists(coderRulesPath)) return;
-  const templatePath = path.resolve(import.meta.dirname, "../../templates/coder-rules.md");
+  const templatePath = path.join(getTemplatesRoot(), "coder-rules.md");
   let content;
   try {
     content = await fs.readFile(templatePath, "utf8");
@@ -537,7 +538,7 @@ async function scaffoldCiGateway(config, flags, logger) {
   const workflowDir = path.join(projectDir, ".github", "workflows");
   await ensureDir(workflowDir);
 
-  const templatesDir = path.resolve(import.meta.dirname, "../../templates/workflows");
+  const templatesDir = path.join(getTemplatesRoot(), "workflows");
   const workflows = ["kj-ci-gateway.yml", "automerge.yml", "houston-override.yml"];
 
   for (const wf of workflows) {
@@ -611,7 +612,7 @@ async function bootstrapOllama({ flags, config, logger, interactive }) {
 async function installSkills(logger, interactive) {
   const projectDir = process.cwd();
   const commandsDir = path.join(projectDir, ".claude", "commands");
-  const skillsTemplateDir = path.resolve(import.meta.dirname, "../../templates/skills");
+  const skillsTemplateDir = path.join(getTemplatesRoot(), "skills");
 
   let doInstall = true;
   if (interactive) {

package/src/commands/onboard.js

@@ -6,6 +6,7 @@ import { collectAll } from "../onboarder/collectors/index.js";
 import { OnboarderRole } from "../roles/onboarder-role.js";
 import { resolveRole } from "../config.js";
 import { getKarajanHome } from "../utils/paths.js";
+import { getTemplatesRoot } from "../utils/templates-root.js";
 
 export function briefPath(projectDir) {
   const slug = path.basename(projectDir).replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase() || "project";
@@ -28,7 +29,7 @@ export async function onboardCommand({ config, logger, flags = {} }) {
     return { path: out, bundle, brief: null };
   }
   const roleCfg = resolveRole(config, "onboarder") || resolveRole(config, "architect");
-  const templatePath = new URL("../../templates/roles/onboarder.md", import.meta.url).pathname;
+  const templatePath = path.join(getTemplatesRoot(), "roles", "onboarder.md");
   const instructions = existsSync(templatePath) ? await readFile(templatePath, "utf8") : "";
   const role = new OnboarderRole({ instructions, config, ...roleCfg });
   // KJC-BUG-0061 Bug B: BaseRole.run() refuses to execute unless init()

package/src/harden/advisory.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { findManagedBlock } from "../utils/managed-markers.js";
+import { findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 import { detectStackRoots } from "./stack-roots.js";
 
@@ -98,6 +99,13 @@ function readArtifactContent(searchDir, foundAt) {
 
 /** Map a classified state to a recommendation + human rationale. */
 function recommend(state) {
+  if (state.status === "SATISFIED_BY_ALTERNATIVE") {
+    return {
+      recommendation: "keep",
+      rationale: `covered by ${state.foundAt} (${state.alternativeTool}) — kj won't add a second linter/formatter`,
+      mergeable: false,
+    };
+  }
   if (state.status === "MISSING") return { recommendation: "install", rationale: `kj would add ${state.file}`, mergeable: true };
   if (state.status === "USER_OWNED") {
     const n = state.improvements?.length ?? 0;
@@ -109,11 +117,20 @@ function recommend(state) {
   return { recommendation: "update", rationale: `kj v${state.currentVersion} available (you have v${state.managedVersion})`, mergeable: true };
 }
 
-/** Classify a single artifact found (or not) under `searchDir`. */
-export function classifyArtifact(searchDir, artifact) {
+/**
+ * Classify a single artifact found (or not) under `searchDir`. `altDirs`
+ * widens the cross-tool alternative lookup (a root-level biome.json covers a
+ * monorepo's language roots); the user's OWN config of the same tool still
+ * wins over an alternative.
+ */
+export function classifyArtifact(searchDir, artifact, altDirs = [searchDir]) {
   const foundAt = findArtifactFile(searchDir, artifact);
   const base = { foundAt, managedVersion: null, upToDate: null, improvements: [] };
   let state = { ...base, status: "MISSING" };
+  if (!foundAt) {
+    const alt = findAlternative(altDirs, artifact.id);
+    if (alt) state = { ...base, status: "SATISFIED_BY_ALTERNATIVE", foundAt: alt.foundAt, alternativeTool: alt.tool };
+  }
   if (foundAt) {
     const content = readArtifactContent(searchDir, foundAt);
     if (artifact.blockId && content.includes(`kj:managed:${artifact.blockId}`)) {
@@ -139,8 +156,10 @@ export function compareHarden({ projectDir = process.cwd(), profile = "standard"
   for (const { dir, language } of detectStackRoots(projectDir, { only, exclude })) {
     const searchDir = dir === "." ? projectDir : join(projectDir, dir);
     for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
-      const res = classifyArtifact(searchDir, toArtifact(cfg));
-      artifacts.push({ dir, ...res, foundAt: res.foundAt && dir !== "." ? join(dir, res.foundAt) : res.foundAt });
+      const res = classifyArtifact(searchDir, toArtifact(cfg), [searchDir, projectDir]);
+      // Alternative matches may live at the repo root — keep their path unprefixed.
+      const prefix = res.foundAt && dir !== "." && res.status !== "SATISFIED_BY_ALTERNATIVE";
+      artifacts.push({ dir, ...res, foundAt: prefix ? join(dir, res.foundAt) : res.foundAt });
     }
   }
   return { artifacts };

package/src/harden/alternatives.js

@@ -0,0 +1,50 @@
+/**
+ * Cross-tool alternatives for `kj harden` (KJC-TSK-0614).
+ *
+ * A user's Biome config replaces BOTH eslint and prettier — seeding kj's
+ * configs next to biome.json installs a second, conflicting linter/formatter
+ * that fights the user's own hooks. The advisory's EQUIVALENTS map only
+ * covers same-tool filename variants; this map covers whole-tool
+ * substitutions, and the three surfaces (advisory, config-engine, check)
+ * consult it before treating an artifact as missing.
+ *
+ * Detection is config-file based on purpose: deterministic, and a false
+ * negative just means kj proposes its default (the pre-0614 behaviour),
+ * never that it overwrites the user's tool.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const ALTERNATIVES = {
+  eslint: [{ tool: "biome", files: ["biome.json", "biome.jsonc"] }],
+  prettier: [{ tool: "biome", files: ["biome.json", "biome.jsonc"] }],
+};
+
+/**
+ * First alternative tool that satisfies `artifactId`, searching each dir in
+ * order (a language root first, then the repo root — a root-level biome.json
+ * covers the whole monorepo). Null when none applies.
+ *
+ * @param {string[]} searchDirs
+ * @param {string} artifactId - "eslint" | "prettier" | ...
+ * @returns {{ tool: string, foundAt: string }|null}
+ */
+export function findAlternative(searchDirs, artifactId) {
+  for (const alt of ALTERNATIVES[artifactId] ?? []) {
+    for (const dir of searchDirs) {
+      for (const rel of alt.files) {
+        if (existsSync(join(dir, rel))) return { tool: alt.tool, foundAt: rel };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Artifact id for a config-template entry — same convention as the
+ * advisory's toArtifact: prettier is the only marker-less JSON config.
+ */
+export function artifactIdForConfig(cfg) {
+  return cfg.blockId ?? "prettier";
+}

package/src/harden/check.js

@@ -11,6 +11,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { runCommand } from "../utils/process.js";
+import { artifactIdForConfig, findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 import { PROFILE_HOOKS } from "./hook-templates.js";
 import { detectStackRoots } from "./stack-roots.js";
@@ -53,8 +54,18 @@ export async function checkHarden({ projectDir = process.cwd(), profile = "stand
       checks.push(presence(projectDir, cfg.file, `config:${cfg.file}`, "missing — run kj harden"));
     }
     for (const { dir, language } of roots) {
+      const rootDir = dir === "." ? projectDir : join(projectDir, dir);
       for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
         const rel = dir === "." ? cfg.file : join(dir, cfg.file);
+        // A config covered by the user's own tool (biome.json ⇒ eslint+prettier)
+        // is not drift — kj must not demand a second linter/formatter (KJC-TSK-0614).
+        if (!existsSync(join(projectDir, rel))) {
+          const alt = findAlternative([rootDir, projectDir], artifactIdForConfig(cfg));
+          if (alt) {
+            checks.push({ id: `config:${rel}`, ok: true, detail: `covered by ${alt.foundAt} (${alt.tool})` });
+            continue;
+          }
+        }
         checks.push(presence(projectDir, rel, `config:${rel}`, `missing for ${language} — run kj harden`));
       }
     }

package/src/harden/config-engine.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { artifactIdForConfig, findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 
 const BLOCK_VERSION = 1;
@@ -18,13 +19,26 @@ function writeFile(target, content) {
   writeFileSync(target, content);
 }
 
-/** Seed a list of config entries into `targetDir`, labelling each by `prefix`. */
-function seedInto(targetDir, configs, dryRun, prefix, results) {
+/**
+ * Seed a list of config entries into `targetDir`, labelling each by `prefix`.
+ * `altDirs` widens the cross-tool alternative lookup (KJC-TSK-0614): a config
+ * covered by the user's own tool (biome.json ⇒ eslint+prettier) is never
+ * seeded — kj must not install a second, conflicting linter/formatter.
+ */
+function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [targetDir]) {
   for (const cfg of configs) {
     const target = join(targetDir, cfg.file);
     const exists = existsSync(target);
     const file = prefix === "." ? cfg.file : join(prefix, cfg.file);
 
+    if (!exists) {
+      const alt = findAlternative(altDirs, artifactIdForConfig(cfg));
+      if (alt) {
+        results.push({ file, action: "covered", by: alt.foundAt });
+        continue;
+      }
+    }
+
     if (cfg.json) {
       const action = exists ? "skipped" : "inserted";
       if (!dryRun && !exists) writeFile(target, `${cfg.body}\n`);
@@ -69,7 +83,9 @@ export function installConfigsForRoots({ projectDir = process.cwd(), roots = [],
   const results = [];
   seedInto(projectDir, UNIVERSAL_CONFIGS, dryRun, ".", results);
   for (const { dir, language } of roots) {
-    seedInto(join(projectDir, dir), CONFIGS_BY_LANGUAGE[language] ?? [], dryRun, dir, results);
+    const rootDir = join(projectDir, dir);
+    // A root-level biome.json covers every language root of the monorepo.
+    seedInto(rootDir, CONFIGS_BY_LANGUAGE[language] ?? [], dryRun, dir, results, [rootDir, projectDir]);
   }
   return { dryRun, configs: results };
 }

package/src/orchestrator/config-init.js

@@ -10,6 +10,7 @@ import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
+import { getTemplatesRoot } from "../utils/templates-root.js";
 import { BudgetTracker, extractUsageMetrics } from "../utils/budget.js";
 import { computeKjComparison } from "../budget/comparison.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
@@ -76,7 +77,7 @@ export async function autoInit(projectDir, logger) {
   logger.info("No .karajan/ found — auto-initializing project scaffolding");
   await ensureDir(karajanDir);
 
-  const templatesDir = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "..", "templates");
+  const templatesDir = getTemplatesRoot();
 
   const filesToCopy = [
     { src: "coder-rules.md", dest: "coder-rules.md" },

package/src/prompts/prompt-resolver.js

@@ -26,8 +26,8 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { getKarajanHome } from "../utils/paths.js";
+import { getTemplatesRoot } from "../utils/templates-root.js";
 import { normalizeProvider } from "../utils/provider-env.js";
 
 /**
@@ -50,14 +50,7 @@ export function resolveRolePromptPaths(role, provider, projectDir) {
   if (projectDir) homes.push(path.join(projectDir, ".karajan", "roles"));
   homes.push(path.join(getKarajanHome(), "roles"));
 
-  const builtInRoot = path.resolve(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "..",
-    "..",
-    "templates",
-    "roles"
-  );
-  homes.push(builtInRoot);
+  homes.push(path.join(getTemplatesRoot(), "roles"));
 
   const perProvider = [];
   const defaults = [];

package/src/utils/install-hints.js

@@ -97,7 +97,11 @@ const INSTALL_CANDIDATES = {
     { manager: "pip", command: "pip install semgrep" },
   ],
   "osv-scanner": [
-    { manager: "go", command: "go install github.com/google/osv-scanner@latest" },
+    // The module root has no main package — the binary lives in the cmd/
+    // subpackage, and since v2 the module path carries the /v2 suffix.
+    // `go install github.com/google/osv-scanner@latest` resolves the module
+    // (v1.x) but fails with "does not contain package" (KJC-BUG-0105).
+    { manager: "go", command: "go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest" },
     { manager: "brew", command: "brew install osv-scanner" },
   ],
   lighthouse: [

package/src/utils/templates-root.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isSea, getAsset } from "node:sea";
+import { getKarajanHome } from "./paths.js";
+
+// npm install / source tree: the real templates/ directory next to src/.
+const SOURCE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "templates",
+);
+
+const INDEX_ASSET = "templates-index.json";
+
+/**
+ * Root directory of the built-in templates (KJC-BUG-0104).
+ *
+ * The SEA binary ships only the JS bundle — templates/ never travels as
+ * files, and `import.meta.dirname`-relative resolution lands on the
+ * binary's own directory (e.g. `$HOME/templates/skills` → ENOENT). In SEA
+ * builds the templates travel as SEA assets (see scripts/build-sea.mjs);
+ * they are extracted once per version into ~/.karajan/embedded-templates/
+ * and served from there, so every fs-based consumer keeps working.
+ */
+export function getTemplatesRoot() {
+  if (!isSeaRuntime()) return SOURCE_ROOT;
+  const index = JSON.parse(getAsset(INDEX_ASSET, "utf8"));
+  const destRoot = path.join(getKarajanHome(), "embedded-templates", index.version);
+  return extractEmbeddedTemplates({
+    destRoot,
+    files: index.files,
+    readAsset: (rel) => getAsset(`templates/${rel}`, "utf8"),
+  });
+}
+
+function isSeaRuntime() {
+  try {
+    return isSea();
+  } catch {
+    // isSea() unexpectedly threw ⇒ treat as npm / source tree, never block.
+    return false;
+  }
+}
+
+/**
+ * Extract the embedded template files into destRoot (idempotent: a
+ * .complete marker skips re-extraction). Exported for unit testing.
+ */
+export function extractEmbeddedTemplates({ destRoot, files, readAsset }) {
+  const marker = path.join(destRoot, ".complete");
+  if (fs.existsSync(marker)) return destRoot;
+  for (const rel of files) {
+    const dest = path.join(destRoot, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, readAsset(rel));
+  }
+  fs.writeFileSync(marker, "");
+  return destRoot;
+}

package/src/utils/update-check.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { isSea } from "node:sea";
 import { getKarajanHome } from "./paths.js";
@@ -104,30 +105,46 @@ export async function printUpdateNotice(currentVersion) {
 }
 
 /**
- * Run the npm-channel self-update (`kj update`). Captures npm's output instead
- * of streaming it: a successful update shows only the progress + result line,
- * so npm's deprecation / allow-scripts / funding noise — build plumbing, not
- * actionable for whoever runs the command — never reaches the user. On failure
- * the captured stdout/stderr IS surfaced, so real errors (native build,
- * permissions) stay diagnosable — never a silent failure.
+ * Run the self-update (`kj update`), channel-aware (KJC-BUG-0106).
+ *
+ * npm channel: `npm install -g` with CAPTURED output — success shows only
+ * progress + result; npm's deprecation / allow-scripts / funding noise never
+ * reaches the user. On failure the captured output IS surfaced.
+ *
+ * sea channel (standalone binary): npm-installing would update a copy the
+ * PATH never resolves — the running binary stays old while `kj update`
+ * reports success. Instead the binary installer is re-run (downloaded to a
+ * temp file first, never piped from the network straight into a shell).
+ *
+ * Both channels end with a PATH probe: `kj --version` must report the new
+ * version, otherwise a stale copy shadows the update and the command fails
+ * LOUDLY naming the likely cause — never a silent "updated" that isn't.
  *
  * @param {Object} opts
  * @param {string} opts.currentVersion - version of the running kj
  * @param {(cmd: string, args: string[]) => Promise<{stdout: string, stderr: string}>} [opts.exec] - injectable runner (defaults to execa)
  * @param {Console} [opts.logger]
- * @returns {Promise<{ ok: boolean, alreadyLatest?: boolean, latest?: string }>}
+ * @param {"npm"|"sea"} [opts.channel] - injectable channel (defaults to detectInstallChannel())
+ * @param {typeof fetch} [opts.fetchFn] - injectable fetch (registry lookup + installer download)
+ * @returns {Promise<{ ok: boolean, alreadyLatest?: boolean, latest?: string, manual?: boolean }>}
  */
-export async function performSelfUpdate({ currentVersion, exec, logger = console } = {}) {
+export async function performSelfUpdate({ currentVersion, exec, logger = console, channel, fetchFn = fetch } = {}) {
   const run = exec || (async (cmd, args) => (await import("execa")).execa(cmd, args));
+  const ch = channel || detectInstallChannel();
   logger.log(`Current version: ${currentVersion}`);
   logger.log("Checking for updates...");
 
   let latest;
   try {
-    const { stdout } = await run("npm", ["view", PACKAGE_NAME, "version"]);
-    latest = stdout.trim();
+    // Registry over HTTP, not `npm view` — standalone-binary machines may
+    // not have npm at all.
+    const res = await fetchFn(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      headers: { Accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`registry responded ${res.status}`);
+    latest = (await res.json()).version;
   } catch (err) {
-    logger.error(`Update failed: ${err.shortMessage || err.message}`);
+    logger.error(`Update failed: could not check the registry (${err.message})`);
     return { ok: false };
   }
 
@@ -136,18 +153,64 @@ export async function performSelfUpdate({ currentVersion, exec, logger = console
     return { ok: true, alreadyLatest: true, latest };
   }
 
+  if (ch === "sea" && process.platform === "win32") {
+    // Executing a downloaded .ps1 from inside the binary is not supported
+    // yet — hand the user the exact command instead of half-updating.
+    logger.log(`Update available: ${currentVersion} → ${latest} (standalone binary).`);
+    logger.log(`${updateInstruction({ channel: "sea" })}`);
+    return { ok: true, latest, manual: true };
+  }
+
   logger.log(`Updating ${currentVersion} → ${latest}... (this can take a few minutes)`);
   try {
-    // No stdio:inherit — capture and drop npm's warnings on the success path.
-    await run("npm", ["install", "-g", `${PACKAGE_NAME}@latest`]);
-    logger.log(`Updated to ${latest}. Restart Claude to pick up the new MCP server.`);
-    return { ok: true, latest };
+    if (ch === "sea") {
+      // Re-run the binary installer: download to a temp file, then execute —
+      // never pipe the network straight into a shell.
+      const res = await fetchFn(INSTALL_SH_URL);
+      if (!res.ok) throw new Error(`installer download failed (${res.status})`);
+      const tmpScript = path.join(os.tmpdir(), `kj-install-${process.pid}.sh`);
+      await fs.writeFile(tmpScript, await res.text(), { mode: 0o700 });
+      try {
+        await run("sh", [tmpScript]);
+      } finally {
+        await fs.rm(tmpScript, { force: true });
+      }
+    } else {
+      // No stdio:inherit — capture and drop npm's warnings on the success path.
+      await run("npm", ["install", "-g", `${PACKAGE_NAME}@latest`]);
+    }
   } catch (err) {
     if (err.stdout) logger.error(err.stdout);
     if (err.stderr) logger.error(err.stderr);
     logger.error(`Update failed: ${err.shortMessage || err.message}`);
     return { ok: false };
   }
+
+  // The install succeeded — but is the kj the USER runs actually the new one?
+  const onPath = await verifyKjOnPath({ run, latest, logger });
+  if (!onPath) return { ok: false };
+  logger.log(`Updated to ${latest}. Restart Claude to pick up the new MCP server.`);
+  return { ok: true, latest };
+}
+
+/**
+ * Probe `kj --version` through the PATH and confirm it reports `latest`.
+ * A mismatch means a stale copy shadows the freshly installed one (e.g. a
+ * standalone binary in ~/.local/bin in front of the npm global prefix).
+ */
+async function verifyKjOnPath({ run, latest, logger }) {
+  let reported;
+  try {
+    const { stdout } = await run("kj", ["--version"]);
+    reported = String(stdout).trim();
+  } catch (err) {
+    logger.error(`Update installed ${latest}, but running \`kj --version\` failed: ${err.shortMessage || err.message}`);
+    return false;
+  }
+  if (reported.includes(latest)) return true;
+  logger.error(`Update installed ${latest}, but the \`kj\` on your PATH still reports ${reported}.`);
+  logger.error("A stale copy is shadowing the update. Check `which -a kj` and remove the old one, or update through the channel that owns the first entry.");
+  return false;
 }
 
 /** Simple semver compare: returns >0 if a > b, <0 if a < b, 0 if equal */