@karajan-family/code 4.21.0

package/packages/hu-board/src/token-store.js

@@ -0,0 +1,56 @@
+/**
+ * Token persistence for HU Board (KJC-TSK-0355).
+ *
+ * Stored at `~/.karajan/hu-board/token` (or `$KJ_HOME/hu-board/token`)
+ * with mode 0600 — single-line, hex-encoded, 32 bytes of randomness.
+ * Idempotent: read existing token if file exists, otherwise generate
+ * + persist a new one.
+ *
+ * The token is ONLY enforced when the server binds to a non-loopback
+ * interface. See `auth.js` for the full threat model.
+ */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const TOKEN_BYTES = 32;
+
+/**
+ * Compute the on-disk token path. Delegates to db.js::getKjHome which
+ * (post-KJC-TSK-0420) honours KARAJAN_HOME > KJ_HOME > VITEST > default.
+ * @returns {string}
+ */
+import { getKjHome } from "./db.js";
+export function getTokenPath() {
+  return join(getKjHome(), "hu-board", "token");
+}
+
+/**
+ * Read the persisted token if it exists; otherwise generate a fresh
+ * one, write it (mode 0600), and return it. Returns `null` only if
+ * the filesystem operation itself fails (caller decides whether that
+ * disables auth or aborts startup).
+ *
+ * @returns {string|null}
+ */
+export function getOrCreateToken() {
+  const tokenPath = getTokenPath();
+  try {
+    if (existsSync(tokenPath)) {
+      const raw = readFileSync(tokenPath, "utf8").trim();
+      if (raw.length >= 16) return raw;
+      // Corrupt or empty file — overwrite below.
+    }
+    const token = randomBytes(TOKEN_BYTES).toString("hex");
+    mkdirSync(dirname(tokenPath), { recursive: true });
+    writeFileSync(tokenPath, token, { mode: 0o600 });
+    try { chmodSync(tokenPath, 0o600); } catch { /* best-effort on Windows */ }
+    return token;
+  } catch (err) {
+    // Don't crash the board over this — just disable auth and let the
+    // caller log a warning.
+    console.warn(`[token-store] failed to manage token file at ${tokenPath}: ${err.message}`);
+    return null;
+  }
+}

package/packages/hu-board/src/zombie-reaper.js

@@ -0,0 +1,206 @@
+/**
+ * Zombie session reaper for the HU Board (board-polish #2,
+ * KJC dogfooding 2026-05-07).
+ *
+ * Why this exists
+ * ===============
+ *
+ * Sessions in the SQLite db can stay "in flight" forever when the
+ * orchestrator process dies between iterations: their `status` stays
+ * `coding` / `stalled` / `paused`, the UI keeps surfacing them as
+ * actionable, and `kj board start` weeks later still pops a
+ * "Karajan needs an answer" modal for a checkpoint nobody owns
+ * anymore.
+ *
+ * Concretely, on 2026-05-07 the user opened the board on a fresh
+ * `kj board start` and saw the popup of an HU from 2026-04-27 — 9
+ * days dead, status still `paused`. The fix per his explicit
+ * mandate:
+ *
+ *   "No puede quedarse nada zombie. Debe haber algun sistema que lo
+ *    compruebe al arrancar y mate esos zombies."
+ *
+ * Thresholds (per his decision in the same session):
+ *   - status in (coding | stalled) and >= 6h since updated_at  → reap
+ *   - status === paused and >= 24h since updated_at            → reap
+ *   - everything else                                          → skip
+ *
+ * What "reap" means: write `status: "failed"` BOTH to the DB row
+ * AND to the underlying `~/.karajan/sessions/<id>/session.json`,
+ * append a structured checkpoint of the form
+ *   { stage: 'zombie-reap', reason: <reason>, at: <iso> }
+ * so the audit trail survives. The session row stays in place
+ * (we don't DELETE — the user can still inspect what happened).
+ *
+ * Why update the JSON on disk too
+ * -------------------------------
+ *
+ * The board's `fullScan()` reads every session.json on startup and
+ * upserts the row, OVERWRITING any DB-only mutation. If the reaper
+ * only updated the DB, the next reboot would reset the status back
+ * to `paused`/`stalled` because the JSON still says so. Persisting
+ * to disk makes the reap permanent on the first reboot — the user
+ * sees the cleanup once, and never again.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_CODING_HOURS = 6;
+const DEFAULT_PAUSED_HOURS = 24;
+const CODING_LIKE_STATUSES = new Set(["coding", "stalled", "running", "in_progress"]);
+const PAUSED_STATUSES = new Set(["paused", "checkpoint", "awaiting_answer"]);
+
+/**
+ * Decide whether a single session row qualifies as zombie at `now`.
+ * Pure function — no I/O. Used by both the reaper itself and the
+ * unit tests.
+ *
+ * @param {{ id: string, status: string, updated_at?: string|null,
+ *           created_at?: string|null }} session
+ * @param {{ now: number, codingHours: number, pausedHours: number }} ctx
+ * @returns {{ zombie: boolean, reason?: string }}
+ */
+export function classifyZombie(session, ctx) {
+  if (!session || !session.status) return { zombie: false };
+  const status = String(session.status).toLowerCase();
+  // Reference timestamp: prefer updated_at (the daemon writes that on
+  // every checkpoint sync), fall back to created_at (in case the row
+  // was inserted but never touched again).
+  const refIso = session.updated_at || session.created_at;
+  if (!refIso) return { zombie: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { zombie: false };
+  const ageHours = (ctx.now - refTs) / 3_600_000;
+  if (ageHours <= 0) return { zombie: false };
+  if (CODING_LIKE_STATUSES.has(status) && ageHours >= ctx.codingHours) {
+    return { zombie: true, reason: `${status} ${ageHours.toFixed(1)}h inactive (>= ${ctx.codingHours}h)` };
+  }
+  if (PAUSED_STATUSES.has(status) && ageHours >= ctx.pausedHours) {
+    return { zombie: true, reason: `${status} ${ageHours.toFixed(1)}h inactive (>= ${ctx.pausedHours}h)` };
+  }
+  return { zombie: false };
+}
+
+/**
+ * Filter a list of session rows down to the zombie ones. Pure.
+ *
+ * @param {Array<object>} sessions
+ * @param {{ now?: number, codingHours?: number, pausedHours?: number }} [opts]
+ * @returns {Array<{ session: object, reason: string }>}
+ */
+export function findZombieSessions(sessions, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    codingHours: opts.codingHours ?? DEFAULT_CODING_HOURS,
+    pausedHours: opts.pausedHours ?? DEFAULT_PAUSED_HOURS,
+  };
+  const out = [];
+  for (const session of sessions || []) {
+    const verdict = classifyZombie(session, ctx);
+    if (verdict.zombie) out.push({ session, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Append a `zombie-reap` checkpoint to a JSON-encoded checkpoints
+ * blob (the on-disk format). Returns the new JSON string.
+ *
+ * Defensive about malformed input: if the existing blob isn't a
+ * JSON array, replaces it with a fresh array containing the new
+ * entry — never throws.
+ */
+export function appendZombieCheckpoint(existingJson, reason, isoTimestamp) {
+  let arr = [];
+  if (existingJson) {
+    try {
+      const parsed = JSON.parse(existingJson);
+      if (Array.isArray(parsed)) arr = parsed;
+    } catch { /* fall through with empty arr */ }
+  }
+  arr.push({ stage: "zombie-reap", reason, at: isoTimestamp });
+  return JSON.stringify(arr);
+}
+
+/**
+ * Default location of the on-disk session JSON files. Delegates to
+ * db.js::getKjHome (KJC-TSK-0420): KARAJAN_HOME > KJ_HOME > VITEST > default.
+ * @returns {string}
+ */
+import { getKjHome } from "./db.js";
+function getSessionsDir() {
+  return path.join(getKjHome(), "sessions");
+}
+
+/**
+ * Persist `status: "failed"` and the new zombie-reap checkpoint to
+ * the on-disk session.json. This stops the next `fullScan()` from
+ * resurrecting the zombi.
+ *
+ * Safe-by-default: if the file is missing, malformed, or the write
+ * fails, this returns `false` and the caller logs a warning. We
+ * never throw and we never block the daemon's startup.
+ *
+ * @param {string} sessionId
+ * @param {string} reason
+ * @param {string} reapedAtIso
+ * @param {{ sessionsDir?: string }} [opts]
+ * @returns {boolean} true when the file was rewritten successfully
+ */
+export function markSessionFailedOnDisk(sessionId, reason, reapedAtIso, opts = {}) {
+  const dir = opts.sessionsDir || getSessionsDir();
+  const file = path.join(dir, sessionId, "session.json");
+  let raw;
+  try { raw = fs.readFileSync(file, "utf8"); } catch { return false; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return false; }
+  if (!parsed || typeof parsed !== "object") return false;
+  parsed.status = "failed";
+  parsed.updated_at = reapedAtIso;
+  parsed.checkpoints = Array.isArray(parsed.checkpoints) ? parsed.checkpoints : [];
+  parsed.checkpoints.push({ stage: "zombie-reap", reason, at: reapedAtIso });
+  try {
+    fs.writeFileSync(file, JSON.stringify(parsed, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Reap every zombie session in the DB AND in the underlying
+ * session.json files. Side-effecting. Returns the list of reaped
+ * sessions so the server can log them.
+ *
+ * @param {object} deps
+ * @param {object} deps.db        better-sqlite3 Database handle
+ * @param {object} [deps.opts]    threshold + sessionsDir overrides
+ * @param {Function} [deps.now]   () => number, for tests
+ * @returns {Array<{ id: string, status_before: string, reason: string, disk_persisted: boolean }>}
+ */
+export function reapZombieSessions({ db, opts = {}, now = () => Date.now() }) {
+  if (!db) return [];
+  const allSessions = db.prepare(
+    "SELECT id, status, updated_at, created_at, checkpoints FROM sessions WHERE status NOT IN ('failed', 'approved', 'cancelled', 'done')",
+  ).all();
+  const zombies = findZombieSessions(allSessions, { ...opts, now: now() });
+  if (zombies.length === 0) return [];
+  const update = db.prepare(
+    "UPDATE sessions SET status = 'failed', checkpoints = ?, updated_at = ? WHERE id = ?",
+  );
+  const reapedAt = new Date(now()).toISOString();
+  const reaped = [];
+  for (const { session, reason } of zombies) {
+    const newCheckpoints = appendZombieCheckpoint(session.checkpoints, reason, reapedAt);
+    update.run(newCheckpoints, reapedAt, session.id);
+    const diskPersisted = markSessionFailedOnDisk(session.id, reason, reapedAt, {
+      sessionsDir: opts.sessionsDir,
+    });
+    reaped.push({
+      id: session.id,
+      status_before: session.status,
+      reason,
+      disk_persisted: diskPersisted,
+    });
+  }
+  return reaped;
+}

package/scripts/ai-attribution-guard.yml

@@ -0,0 +1,84 @@
+# AI Attribution Guard — GitHub Action
+#
+# Copy this file to .github/workflows/ai-attribution-guard.yml in any repo.
+# Blocks PRs that contain AI attribution comments or Co-Authored-By lines.
+# No dependencies, no Node.js required. Pure bash + grep.
+
+name: AI Attribution Guard
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  scan:
+    name: Scan for AI attribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check PR diff for AI attribution
+        # KJC-BUG-0072 — never interpolate ${{ github.* }} directly inside a
+        # `run:` block on pull_request workflows. Pin to env vars instead.
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          DIFF=$(git diff "origin/${BASE_REF}...HEAD" \
+            -- ':!*.png' ':!*.jpg' ':!*.svg' ':!*.ico' \
+               ':!*.lock' ':!package-lock.json' ':!yarn.lock' \
+               ':!*.min.js' ':!*.min.css' \
+               ':!.githooks/*' \
+            | grep '^+' \
+            | grep -v '^+++' \
+            || true)
+
+          [ -z "$DIFF" ] && echo "No diff to scan" && exit 0
+
+          # Attribution patterns (not functional references like provider: "claude")
+          ATTR='(Generated|Created|Written|Made|Built|Authored|Assisted|Powered|Produced) (by|with|using|via) .*(Claude|Anthropic|OpenAI|ChatGPT|GPT-[0-9]|Copilot|Gemini|Cursor|Windsurf|Codeium)'
+          COAUTH='Co-Authored-By:.*\b(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)\b'
+          COMMENT='(//|#|/\*|\*|<!--|--)\s*.*(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini).*(generated|assisted|helped|created|wrote|built|made)'
+
+          FOUND=""
+          for PAT in "$ATTR" "$COAUTH" "$COMMENT"; do
+            MATCH=$(echo "$DIFF" | grep -i -E "$PAT" || true)
+            [ -n "$MATCH" ] && FOUND="${FOUND}${MATCH}\n"
+          done
+
+          if [ -n "$FOUND" ]; then
+            echo "::error::AI attribution detected in PR diff"
+            echo -e "$FOUND"
+            echo ""
+            echo "Remove AI attribution comments/lines and push again."
+            exit 1
+          fi
+
+          echo "AI attribution guard: clean"
+
+      - name: Check commit messages
+        # KJC-BUG-0072 — same hardening as the diff scan: env-pin the ref.
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          COMMITS=$(git log --format='%s%n%b' "origin/${BASE_REF}...HEAD")
+
+          COAUTH='Co-Authored-By:.*\b(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)\b'
+          ATTR='(Generated|Created|Written|Built|Authored) (by|with|using) .*(Claude|Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Cursor|Windsurf|Codeium)'
+
+          FOUND=""
+          for PAT in "$COAUTH" "$ATTR"; do
+            MATCH=$(echo "$COMMITS" | grep -i -E "$PAT" || true)
+            [ -n "$MATCH" ] && FOUND="${FOUND}${MATCH}\n"
+          done
+
+          if [ -n "$FOUND" ]; then
+            echo "::error::AI attribution detected in commit messages"
+            echo -e "$FOUND"
+            echo ""
+            echo "Amend commits to remove AI attribution and force-push."
+            exit 1
+          fi
+
+          echo "Commit messages: clean"

package/scripts/audit-test-diet.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * scripts/audit-test-diet.mjs — semantic loss-of-meaning auditor (KJC-TSK-0345).
+ * Categories: empty-no-expect, skipped-pending, imports-orphan, deprecated-export,
+ * subsumed-candidate. Each finding carries confidence (high|low). Complements
+ * tests/_diet/audit.mjs (which classifies by LOC bucket only).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT = resolve(HERE, "..");
+const SKIP_DIRS = new Set(["_diet", "fixtures", "node_modules"]);
+
+export function walkTests(rootDir, testsSubdir = "tests") {
+  const out = [];
+  const base = join(rootDir, testsSubdir);
+  if (!existsSync(base)) return out;
+  const stack = [base];
+  while (stack.length) {
+    for (const e of readdirSync(stack.pop(), { withFileTypes: true })) {
+      const p = join(e.parentPath ?? base, e.name);
+      if (e.isDirectory() && !SKIP_DIRS.has(e.name)) stack.push(p);
+      else if (e.isFile() && /\.test\.(m?js|ts)$/.test(e.name)) out.push(p);
+    }
+  }
+  return out;
+}
+
+export function parseImports(source) {
+  const imports = [];
+  const re = /^[ \t]*import\s+(?:([\w*\s{},]+?)\s+from\s+)?['"]([^'"]+)['"]/gm;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const named = [];
+    const braced = (m[1] || "").match(/\{([^}]+)\}/);
+    if (braced) for (const part of braced[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/)[0].trim();
+      if (name) named.push(name);
+    }
+    imports.push({ specifier: m[2], named });
+  }
+  return imports;
+}
+
+export function resolveSrcImport(testFile, specifier, rootDir) {
+  if (!specifier.startsWith(".") && !specifier.startsWith("#")) return null;
+  const base = specifier.startsWith("#") ? resolve(rootDir, specifier.replace(/^#/, "src/")) : resolve(dirname(testFile), specifier);
+  for (const c of [base, `${base}.js`, `${base}.mjs`, join(base, "index.js")]) {
+    if (existsSync(c) && statSync(c).isFile()) return c;
+  }
+  return null;
+}
+
+export function extractItNames(source) {
+  const names = new Set();
+  for (const m of source.matchAll(/\b(?:it|test)(?:\.(?:only|skip|todo))?\s*\(\s*['"`]([^'"`]+)['"`]/g)) names.add(m[1]);
+  return names;
+}
+
+export function extractExports(source) {
+  const names = new Set();
+  for (const m of source.matchAll(/export\s+(?:async\s+)?(?:function|class|const|let|var)\s+([A-Za-z_$][\w$]*)/g)) names.add(m[1]);
+  for (const m of source.matchAll(/export\s*\{([^}]+)\}/g)) for (const part of m[1].split(",")) {
+    const name = part.trim().split(/\s+as\s+/).pop().trim();
+    if (name) names.add(name);
+  }
+  if (/export\s+default\b/.test(source)) names.add("default");
+  return names;
+}
+
+export function auditFile(testFile, rootDir) {
+  const source = readFileSync(testFile, "utf-8");
+  const rel = relative(rootDir, testFile);
+  const findings = [];
+  const hasIt = /\b(?:it|test)\s*\(/.test(source);
+  if (hasIt && !/\bexpect\s*\(/.test(source)) findings.push({ category: "empty-no-expect", confidence: "high", detail: "it()/test() blocks with no expect()" });
+  if (/\b(?:it|test|describe)\.skip\s*\(|\bxit\s*\(|\bxtest\s*\(|\b(?:it|test)\.todo\s*\(/.test(source)) {
+    findings.push({ category: "skipped-pending", confidence: "high", detail: "uses .skip / xit / xtest / .todo" });
+  }
+  const srcImports = [];
+  for (const imp of parseImports(source)) {
+    if (!imp.specifier.startsWith(".") && !imp.specifier.startsWith("#")) continue;
+    const resolved = resolveSrcImport(testFile, imp.specifier, rootDir);
+    if (!resolved) { findings.push({ category: "imports-orphan", confidence: "high", detail: `cannot resolve '${imp.specifier}'` }); continue; }
+    if (imp.named.length) {
+      const missing = imp.named.filter((n) => !extractExports(readFileSync(resolved, "utf-8")).has(n));
+      if (missing.length) findings.push({ category: "deprecated-export", confidence: "low", detail: `${imp.specifier} no longer exports: ${missing.join(", ")}` });
+    }
+    srcImports.push({ resolved: relative(rootDir, resolved), named: imp.named });
+  }
+  return { path: rel, srcImports, findings, itNames: extractItNames(source) };
+}
+
+export function findSubsumed(perFile) {
+  const bySrc = new Map();
+  for (const f of perFile) for (const imp of f.srcImports) {
+    if (!bySrc.has(imp.resolved)) bySrc.set(imp.resolved, []);
+    bySrc.get(imp.resolved).push({ path: f.path, named: new Set(imp.named), itNames: f.itNames });
+  }
+  const out = [];
+  for (const [src, consumers] of bySrc) {
+    if (consumers.length < 2) continue;
+    const sorted = [...consumers].sort((a, b) => a.named.size - b.named.size);
+    const narrow = sorted[0]; const broad = sorted[sorted.length - 1];
+    if (narrow.path === broad.path || narrow.named.size === 0 || broad.named.size === 0) continue;
+    if (!(narrow.named.size < broad.named.size && [...narrow.named].every((n) => broad.named.has(n)))) continue;
+    // Require ≥50% of narrow's it() names to also appear in broad's. Imports
+    // alone are a false-positive trap: two tests can share helpers and assert
+    // on disjoint behavior (e.g. tests/budget.test.js vs tests/utils/budget.test.js).
+    if (narrow.itNames.size === 0) continue;
+    const overlap = [...narrow.itNames].filter((n) => broad.itNames.has(n)).length;
+    if (overlap / narrow.itNames.size < 0.5) continue;
+    out.push({ category: "subsumed-candidate", confidence: "low", path: narrow.path, detail: `${overlap}/${narrow.itNames.size} it() names also in ${broad.path}; subset of imports from ${src}` });
+  }
+  return out;
+}
+
+export function auditTestDiet(rootDir = DEFAULT_ROOT) {
+  const files = walkTests(rootDir);
+  const perFile = files.map((f) => auditFile(f, rootDir));
+  const findings = [];
+  for (const f of perFile) for (const x of f.findings) findings.push({ path: f.path, ...x });
+  for (const s of findSubsumed(perFile)) findings.push(s);
+  return { generatedAt: new Date().toISOString(), rootDir, totals: { filesAudited: files.length, findings: findings.length }, findings };
+}
+
+export function renderMarkdown(report) {
+  const byCat = new Map();
+  for (const f of report.findings) {
+    if (!byCat.has(f.category)) byCat.set(f.category, []);
+    byCat.get(f.category).push(f);
+  }
+  const lines = [`# Semantic test-diet audit`, ``, `Generated: ${report.generatedAt}`, `Files audited: ${report.totals.filesAudited}`, `Findings: ${report.totals.findings}`, ``];
+  for (const [cat, items] of byCat) {
+    lines.push(`## ${cat} (${items.length})`, ``);
+    for (const it of items) lines.push(`- \`${it.path}\` — ${it.detail} (confidence: ${it.confidence})`);
+    lines.push(``);
+  }
+  return lines.join("\n");
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const report = auditTestDiet(DEFAULT_ROOT);
+  const outDir = join(DEFAULT_ROOT, "audit");
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, "test-diet-semantic.json"), JSON.stringify(report, null, 2));
+  writeFileSync(join(outDir, "test-diet-semantic.md"), renderMarkdown(report));
+  console.log(`audit: ${report.totals.filesAudited} files, ${report.totals.findings} findings -> audit/test-diet-semantic.{json,md}`);
+}

package/scripts/build-sea.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * build-sea.mjs — Build a Node.js Single Executable Application (SEA) binary.
+ *
+ * Steps:
+ *   1. esbuild bundles src/cli.js -> dist/kj-bundle.cjs (CJS, all deps inlined)
+ *   2. Generate SEA preparation blob via node --experimental-sea-config
+ *   3. Copy the current node binary to dist/kj (or dist/kj.exe on Windows)
+ *   4. Inject the blob into the binary with postject
+ *   5. (macOS only) Re-sign the binary with ad-hoc signature
+ *
+ * Requirements (installed as devDependencies — run `npm ci` first):
+ *   - esbuild
+ *   - postject
+ *
+ * Usage:
+ *   node scripts/build-sea.mjs
+ */
+
+import { execSync } from "node:child_process";
+import { cpSync, mkdirSync, writeFileSync, statSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "..");
+const DIST = path.join(ROOT, "dist");
+
+const isWindows = process.platform === "win32";
+const isMac = process.platform === "darwin";
+const binaryName = isWindows ? "kj.exe" : "kj";
+const binaryPath = path.join(DIST, binaryName);
+
+function run(cmd, opts = {}) {
+  console.log(`  $ ${cmd}`);
+  execSync(cmd, { cwd: ROOT, stdio: "inherit", ...opts });
+}
+
+function formatBytes(bytes) {
+  const mb = bytes / (1024 * 1024);
+  return `${mb.toFixed(1)} MB`;
+}
+
+async function main() {
+  try {
+    console.log("\n=== Karajan Code — SEA Build ===\n");
+
+    // ── Step 0: Prepare dist directory ──────────────────────────────
+    mkdirSync(DIST, { recursive: true });
+
+    // ── Step 1: Bundle with esbuild ─────────────────────────────────
+    console.log("[1/5] Bundling with esbuild...");
+    const { seaBuildOptions } = await import("./esbuild-sea.config.mjs");
+    const esbuild = await import("esbuild");
+    await esbuild.build(seaBuildOptions);
+    console.log("      -> dist/kj-bundle.cjs created.\n");
+
+    // ── 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"),
+      JSON.stringify(seaConfig, null, 2),
+    );
+    run("node --experimental-sea-config dist/sea-config.json");
+    console.log("      -> dist/sea-prep.blob created.\n");
+
+    // ── Step 3: Copy node binary ────────────────────────────────────
+    console.log("[3/5] Copying node binary...");
+    cpSync(process.execPath, binaryPath);
+    console.log(`      -> ${binaryName} copied.\n`);
+
+    // ── Step 3.5: Remove signature on macOS (required before postject)
+    if (isMac) {
+      console.log("[3.5] Removing macOS code signature...");
+      run(`codesign --remove-signature ${binaryPath}`);
+      console.log("      -> Signature removed.\n");
+    }
+
+    // ── Step 4: Inject blob with postject ───────────────────────────
+    console.log("[4/5] Injecting SEA blob with postject...");
+    // On macOS the blob MUST land as section NODE_SEA_BLOB inside a segment
+    // named NODE_SEA. Without --macho-segment-name postject writes it to a
+    // default segment the SEA loader never inspects, so the binary segfaults
+    // on startup (KJC-BUG-0096, nodejs/postject#76). The flag is Mach-O only —
+    // ELF (Linux) and PE (Windows) don't take it — so add it only on macOS.
+    const postjectCmd = [
+      `npx postject ${binaryPath}`,
+      "NODE_SEA_BLOB dist/sea-prep.blob",
+      "--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2",
+      ...(isMac ? ["--macho-segment-name NODE_SEA"] : []),
+    ].join(" ");
+    run(postjectCmd);
+    console.log("      -> Blob injected.\n");
+
+    // ── Step 4.5: Re-sign on macOS ──────────────────────────────────
+    if (isMac) {
+      console.log("[4.5] Re-signing binary (ad-hoc)...");
+      run(`codesign --sign - ${binaryPath}`);
+      console.log("      -> Binary signed.\n");
+    }
+
+    // ── Done ────────────────────────────────────────────────────────
+    const stat = statSync(binaryPath);
+    console.log("[5/5] Done!");
+    console.log(`      Binary: ${binaryPath}`);
+    console.log(`      Size:   ${formatBytes(stat.size)}`);
+    console.log("");
+  } catch (err) {
+    console.error("\n=== SEA Build FAILED ===\n");
+    console.error(err.message || err);
+    console.error(
+      "\nNote: esbuild may fail to bundle certain ESM-only dependencies",
+    );
+    console.error(
+      "or native modules. Check the error above for details.\n",
+    );
+    process.exit(1);
+  }
+}
+
+main();