karajan-code 4.70.3 → 5.0.0

package/src/commands/env.js

@@ -51,15 +51,14 @@ export function briefCommand({ config = null, flags = {}, role = null }) {
   return { role, brief: text };
 }
 
-export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
-  const projectDir = config?.projectDir || process.cwd();
-  // KJC-BUG-0273: what is dirty NOW is the person's; kj commits only what it generates below.
-  const dirtyBefore = contractChanges(projectDir);
-
-  // KJC-TSK-0709 — the board is chosen BEFORE the playbook renders (its
-  // tracking line depends on the backend): interactive installs ask when
-  // alternatives are reachable, headless installs name the default. The
-  // choice persists so it is only ever asked once.
+/**
+ * KJC-TSK-0709 — the board is chosen BEFORE the playbook renders (its
+ * tracking line depends on the backend): interactive installs ask when
+ * alternatives are reachable, headless installs name the default. The
+ * choice persists so it is only ever asked once.
+ * @returns {Promise<object>} the config with the effective backend
+ */
+async function withChosenBoard(config, projectDir) {
   try {
     const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
     const sel = await pickStateBackend({ projectDir, wizard, isTTY: Boolean(wizard), logger: console });
@@ -67,10 +66,151 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     // The effective backend feeds the render on EVERY non-error path —
     // chosen, declared-in-file or default — so the playbook never falls
     // back to hu-board while the selection said otherwise.
-    config = { ...config, state_backend: sel.backend, board: sel.boardName ? { ...config?.board, name: sel.boardName } : config?.board };
+    return { ...config, state_backend: sel.backend, board: sel.boardName ? { ...config?.board, name: sel.boardName } : config?.board };
   } catch (err) {
     console.log(`⚠ board selection failed (${err.message}) — continuing with the configured default`);
+    return config;
+  }
+}
+
+/** Stops the install with a pending block (exit 3): the playbook stays installed. */
+function pend(result, items, opts) {
+  result.exitCode = PENDING_EXIT_CODE;
+  const block = renderPendingBlock(items, opts);
+  console.log(block);
+  return block;
+}
+
+/**
+ * KJC-TSK-0685 (user rule): Karajan does not run without a board — it is
+ * what guarantees ordered, card-first work. Verify an OPERATIONAL access
+ * path to the declared backend BEFORE anything else; no path → block
+ * (exit 3) with the exact steps. The playbook stays installed.
+ * @returns {boolean} true when the install must stop
+ */
+function boardBlocked(result, config, projectDir) {
+  const access = verifyBoardAccess({ config, projectDir });
+  if (access.ok) {
+    if (access.backend !== "hu-board") console.log(`✓ board access verified: ${access.via}`);
+    return false;
+  }
+  result.boardError = access.needed.join(" | ");
+  pend(result,
+    [{ tool: `${access.name || access.backend} board`, action: "needs-user", reason: `Karajan does not run without a board. To use ${access.name || access.backend}: ${access.needed.join(" ")}` }],
+    { retry: "kj env install" });
+  return true;
+}
+
+/**
+ * KJC-BUG-0133 — installing IS activating. The setup flow used to order
+ * harden + the verdict gate as TEXT steps the agent runs (or narrates);
+ * a session that skipped them got a decorative method — field case
+ * 2026-08-02: installed karajan, then wrote everything by hand with
+ * nothing to stop it. env install now does them itself, idempotently.
+ * @returns {Promise<boolean>} true when the install must stop
+ */
+async function enforcementBlocked(result, config, projectDir) {
+  if (!existsSync(join(projectDir, ".git"))) {
+    pend(result,
+      [{ tool: "git", action: "needs-user", reason: "the enforcement gates live in git hooks — run `git init` (Karajan's guarantees do not exist without git)" }],
+      { retry: "kj env install" });
+    return true;
+  }
+  try {
+    const h = await hardenCommand({ projectDir, logger: console });
+    if (h?.ok === false) throw new Error(h.error || "kj harden failed");
+    // KJC-BUG-0188: a headless harden never binds an identity by itself, and
+    // it must not. Blocking here beats the Sentinel denying every git and gh
+    // call later, with nothing on screen tying that back to this install.
+    if (h?.identityPending) {
+      result.pendingBlock = pend(result,
+        [{ tool: "identity", action: "needs-user", reason: h.identityPending, command: h.identityCommand }],
+        { retry: "kj env install", why: "this clone has no declared identity, and kj never binds one on its own" });
+      return true;
+    }
+    const gate = await reviewGateCommand({ config, flags: { installGate: true } });
+    // KJC-BUG-0447: a gate no hook runs is decorative; never call it active.
+    if (!gate?.enforced) throw new Error("the review gate is declared but no pre-commit hook runs it");
+    console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
+    return false;
+  } catch (err) {
+    pend(result,
+      [{ tool: "enforcement", action: "needs-user", reason: `hooks/gate could not be installed: ${err.message} — without them the method is narratable` }],
+      { retry: "kj env install" });
+    return true;
   }
+}
+
+/**
+ * KJC-TSK-0683: on limited machines (no Ollama, no Docker) the DEFAULT
+ * provider falls back to the built-in ONNX embedder instead of blocking.
+ * Only for the first index and only when the user didn't pick a provider
+ * explicitly — the election is persisted (dims differ, it must stick).
+ */
+async function tryOnnxFallback({ config, projectDir, logger, why }) {
+  if (config?.rag?.embedder?.provider) return false;
+  console.log(`⚠ default embedder unavailable (${why}) — trying the built-in ONNX embedder (no install needed)…`);
+  try {
+    // KJC-BUG-0128: an empty store may carry a vec table at the wrong
+    // dim (the old probe created it at 768) — reset it so ONNX (384)
+    // can index. A store with data is never touched.
+    if (!resetEmptyStore(projectDir)) {
+      console.log("  the vector store already has data at another dimension — not switching automatically");
+      return false;
+    }
+    const totals = await ragIndexCommand({ config: onnxConfig(config), logger, flags: { withSources: true } });
+    if ((totals?.indexed ?? 0) > 0) {
+      const p = await persistOnnxChoice(projectDir);
+      console.log(`✓ RAG indexed with the built-in ONNX embedder — persisted in ${p}`);
+      console.log("  To move to Ollama later: install it, remove the rag.embedder block from .karajan/kj.config.yml,");
+      console.log("  delete the store (~/.karajan/rag.db) and run: kj rag index --with-sources");
+      return true;
+    }
+  } catch (fallbackErr) {
+    console.log(`  ONNX fallback also failed: ${fallbackErr.message}`);
+  }
+  return false;
+}
+
+/**
+ * ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
+ * so installing the environment guarantees the index exists. KJC-TSK-0659
+ * stop-on-sudo: an index that cannot be built is a BLOCKING condition —
+ * "success" with 0 chunks would leave every future session running the
+ * method against an empty RAG (field-reproduced: 0/727 without Ollama).
+ * The playbook stays installed; the command exits 3 so the driving agent
+ * stops, shows the block, and waits for the user.
+ */
+async function ensureRagIndex({ result, config, projectDir, logger }) {
+  const provider = config?.rag?.embedder?.provider || "ollama";
+  const blockRag = (why) => {
+    result.ragError = why;
+    const item = provider === "ollama"
+      ? { tool: "ollama", action: "needs-user", reason: `the RAG cannot index: ${why}` }
+      : { tool: `${provider} embedder`, action: "needs-user", reason: `the RAG cannot index: ${why} — check rag.embedder in kj config`, manualUrl: "kj config" };
+    pend(result, [item], { retry: "kj rag index --with-sources   (then re-run: kj env install)" });
+  };
+  const fallbackOrBlock = async (why) => {
+    if (!(await tryOnnxFallback({ config, projectDir, logger, why }))) blockRag(why);
+  };
+  try {
+    if (hasRagIndex(config, projectDir)) {
+      console.log("✓ RAG index present");
+      return;
+    }
+    console.log("⏳ no RAG index for this project — building it (first time only)…");
+    const totals = await ragIndexCommand({ config, logger, flags: { withSources: true } });
+    if ((totals?.indexed ?? 0) === 0 && (totals?.files ?? 0) > 0) await fallbackOrBlock(`0 of ${totals.files} files indexed — is the embedder running?`);
+  } catch (err) {
+    await fallbackOrBlock(err.message);
+  }
+}
+
+export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  // KJC-BUG-0273: what is dirty NOW is the person's; kj commits only what it generates below.
+  const dirtyBefore = contractChanges(projectDir);
+  config = await withChosenBoard(config, projectDir);
 
   const result = await installPlaybook({
     projectDir, target: flags.target || "all",
@@ -90,143 +230,31 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     console.log(`⚠ could not wire kj-rag-mcp into .mcp.json: ${err.message}`);
   }
 
-  // KJC-TSK-0685 (user rule): Karajan does not run without a board — it is
-  // what guarantees ordered, card-first work. Verify an OPERATIONAL access
-  // path to the declared backend BEFORE anything else; no path → block
-  // (exit 3) with the exact steps. The playbook stays installed.
-  const access = verifyBoardAccess({ config, projectDir });
-  if (!access.ok) {
-    result.boardError = access.needed.join(" | ");
-    result.exitCode = PENDING_EXIT_CODE;
-    console.log(renderPendingBlock(
-      [{ tool: `${access.name || access.backend} board`, action: "needs-user", reason: `Karajan does not run without a board. To use ${access.name || access.backend}: ${access.needed.join(" ")}` }],
-      { retry: "kj env install" },
-    ));
-    return result;
-  }
-  if (access.backend !== "hu-board") console.log(`✓ board access verified: ${access.via}`);
-
-  // KJC-BUG-0133 — installing IS activating. The setup flow used to order
-  // harden + the verdict gate as TEXT steps the agent runs (or narrates);
-  // a session that skipped them got a decorative method — field case
-  // 2026-08-02: installed karajan, then wrote everything by hand with
-  // nothing to stop it. env install now does them itself, idempotently.
-  if (flags.enforce !== false) {
-    if (!existsSync(join(projectDir, ".git"))) {
-      result.exitCode = PENDING_EXIT_CODE;
-      console.log(renderPendingBlock(
-        [{ tool: "git", action: "needs-user", reason: "the enforcement gates live in git hooks — run `git init` (Karajan's guarantees do not exist without git)" }],
-        { retry: "kj env install" },
-      ));
-      return result;
-    }
-    try {
-      const h = await hardenCommand({ projectDir, logger: console });
-      if (h?.ok === false) throw new Error(h.error || "kj harden failed");
-      // KJC-BUG-0188: a headless harden never binds an identity by itself, and
-      // it must not. Blocking here beats the Sentinel denying every git and gh
-      // call later, with nothing on screen tying that back to this install.
-      if (h?.identityPending) {
-        result.exitCode = PENDING_EXIT_CODE;
-        result.pendingBlock = renderPendingBlock(
-          [{ tool: "identity", action: "needs-user", reason: h.identityPending, command: h.identityCommand }],
-          { retry: "kj env install", why: "this clone has no declared identity, and kj never binds one on its own" },
-        );
-        console.log(result.pendingBlock);
-        return result;
-      }
-      await reviewGateCommand({ config, flags: { installGate: true } });
-      console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
-    } catch (err) {
-      result.exitCode = PENDING_EXIT_CODE;
-      console.log(renderPendingBlock(
-        [{ tool: "enforcement", action: "needs-user", reason: `hooks/gate could not be installed: ${err.message} — without them the method is narratable` }],
-        { retry: "kj env install" },
-      ));
-      return result;
-    }
-  }
-
-  // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
-  // so installing the environment guarantees the index exists. KJC-TSK-0659
-  // stop-on-sudo: an index that cannot be built is a BLOCKING condition —
-  // "success" with 0 chunks would leave every future session running the
-  // method against an empty RAG (field-reproduced: 0/727 without Ollama).
-  // The playbook stays installed; the command exits 3 so the driving agent
-  // stops, shows the block, and waits for the user.
-  if (flags.rag !== false) {
-    const provider = config?.rag?.embedder?.provider || "ollama";
-    const blockRag = (why) => {
-      result.ragError = why;
-      result.exitCode = PENDING_EXIT_CODE;
-      const item = provider === "ollama"
-        ? { tool: "ollama", action: "needs-user", reason: `the RAG cannot index: ${why}` }
-        : { tool: `${provider} embedder`, action: "needs-user", reason: `the RAG cannot index: ${why} — check rag.embedder in kj config`, manualUrl: "kj config" };
-      console.log(renderPendingBlock([item], { retry: "kj rag index --with-sources   (then re-run: kj env install)" }));
-    };
-    // KJC-TSK-0683: on limited machines (no Ollama, no Docker) the DEFAULT
-    // provider falls back to the built-in ONNX embedder instead of blocking.
-    // Only for the first index and only when the user didn't pick a provider
-    // explicitly — the election is persisted (dims differ, it must stick).
-    const explicitProvider = Boolean(config?.rag?.embedder?.provider);
-    const tryOnnxFallback = async (why) => {
-      if (explicitProvider) return false;
-      console.log(`⚠ default embedder unavailable (${why}) — trying the built-in ONNX embedder (no install needed)…`);
-      try {
-        // KJC-BUG-0128: an empty store may carry a vec table at the wrong
-        // dim (the old probe created it at 768) — reset it so ONNX (384)
-        // can index. A store with data is never touched.
-        if (!resetEmptyStore(projectDir)) {
-          console.log("  the vector store already has data at another dimension — not switching automatically");
-          return false;
-        }
-        const totals = await ragIndexCommand({ config: onnxConfig(config), logger, flags: { withSources: true } });
-        if ((totals?.indexed ?? 0) > 0) {
-          const p = await persistOnnxChoice(projectDir);
-          console.log(`✓ RAG indexed with the built-in ONNX embedder — persisted in ${p}`);
-          console.log("  To move to Ollama later: install it, remove the rag.embedder block from .karajan/kj.config.yml,");
-          console.log("  delete the store (~/.karajan/rag.db) and run: kj rag index --with-sources");
-          return true;
-        }
-      } catch (fallbackErr) {
-        console.log(`  ONNX fallback also failed: ${fallbackErr.message}`);
-      }
-      return false;
-    };
-    try {
-      if (hasRagIndex(config, projectDir)) {
-        console.log("✓ RAG index present");
-      } else {
-        console.log("⏳ no RAG index for this project — building it (first time only)…");
-        const totals = await ragIndexCommand({ config, logger, flags: { withSources: true } });
-        if ((totals?.indexed ?? 0) === 0 && (totals?.files ?? 0) > 0) {
-          const why = `0 of ${totals.files} files indexed — is the embedder running?`;
-          if (!(await tryOnnxFallback(why))) blockRag(why);
-        }
-      }
-    } catch (err) {
-      if (!(await tryOnnxFallback(err.message))) blockRag(err.message);
-    }
-  }
-  if (result.exitCode !== PENDING_EXIT_CODE) {
-    // KJC-TSK-0707 (PV-D) — privacy onboarding rides the install: kj asks,
-    // kj writes the denylist. Best-effort (stubbed in the SEA binary).
-    try {
-      const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
-      await ensurePrivacyList({ wizard, logger: console, isTTY: Boolean(wizard) });
-      wizard?.close();
-    } catch { /* privacy onboarding is best-effort */ }
-    console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
-    // KJC-BUG-0273: the contract is kj's to commit. Left to the agent, its own
-    // PR-size rules forbid a 1200-line commit of generated files and it stops.
-    const contract = commitContract({ projectDir, before: dirtyBefore, baseBranch: config?.base_branch || "main" });
-    if (contract.committed) console.log(`✓ contract committed by kj: ${contract.files.length} generated file(s), nothing for the agent to commit`);
-    else if (!contract.reason.startsWith("nothing")) console.log(`⚠ the contract kj generated is NOT committed (${contract.reason}): run \`kj env install\` again once that is fixed`);
-    // KJC-BUG-0133 (part 2): a mid-session install lands the playbook in
-    // CLAUDE.md, but the running session loaded its context BEFORE — nobody
-    // re-reads it. Print the method so it enters THIS conversation now.
-    console.log("\n— The Karajan method below is IN EFFECT from this very message. If your session started before this install, apply it from now on:\n");
-    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null, config }));
-  }
+  if (boardBlocked(result, config, projectDir)) return result;
+  if (flags.enforce !== false && await enforcementBlocked(result, config, projectDir)) return result;
+  if (flags.rag !== false) await ensureRagIndex({ result, config, projectDir, logger });
+  if (result.exitCode !== PENDING_EXIT_CODE) await finishInstall({ config, projectDir, dirtyBefore });
   return result;
 }
+
+/** Privacy onboarding, the contract commit and the method printed into the running session. */
+async function finishInstall({ config, projectDir, dirtyBefore }) {
+  // KJC-TSK-0707 (PV-D) — privacy onboarding rides the install: kj asks,
+  // kj writes the denylist. Best-effort (stubbed in the SEA binary).
+  try {
+    const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
+    await ensurePrivacyList({ wizard, logger: console, isTTY: Boolean(wizard) });
+    wizard?.close();
+  } catch { /* privacy onboarding is best-effort */ }
+  console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+  // KJC-BUG-0273: the contract is kj's to commit. Left to the agent, its own
+  // PR-size rules forbid a 1200-line commit of generated files and it stops.
+  const contract = commitContract({ projectDir, before: dirtyBefore, baseBranch: config?.base_branch || "main" });
+  if (contract.committed) console.log(`✓ contract committed by kj: ${contract.files.length} generated file(s), nothing for the agent to commit`);
+  else if (!contract.reason.startsWith("nothing")) console.log(`⚠ the contract kj generated is NOT committed (${contract.reason}): run \`kj env install\` again once that is fixed`);
+  // KJC-BUG-0133 (part 2): a mid-session install lands the playbook in
+  // CLAUDE.md, but the running session loaded its context BEFORE — nobody
+  // re-reads it. Print the method so it enters THIS conversation now.
+  console.log("\n— The Karajan method below is IN EFFECT from this very message. If your session started before this install, apply it from now on:\n");
+  console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null, config }));
+}

package/src/commands/go.js

@@ -11,6 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { checkBinary } from "../utils/agent-detect.js";
+import { agentAuthFiles } from "../utils/agent-home.js";
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 import { bootstrapCommand } from "./bootstrap.js";
 import { boardCommand } from "./board.js";
@@ -21,12 +22,14 @@ export const MAGGLE_AGENTS = [
   { name: "claude", label: "Claude Code (Anthropic)", authPaths: [".claude.json", ".claude"], install: "npm install -g @anthropic-ai/claude-code", login: "claude   (sigue el enlace de inicio de sesión que te muestre)" },
   { name: "codex", label: "Codex (OpenAI)", authPaths: [".codex/auth.json"], install: "npm install -g @openai/codex", login: "codex login" },
 ];
-export async function detectMaggleAgents({ home = os.homedir(), checkBin = checkBinary } = {}) {
+export async function detectMaggleAgents({ home = os.homedir(), env = process.env, checkBin = checkBinary } = {}) {
   return Promise.all(
     MAGGLE_AGENTS.map(async (a) => {
       let installed = false;
       try { installed = (await checkBin(a.name)).ok; } catch { /* not installed */ }
-      const authenticated = installed && a.authPaths.some((p) => existsSync(path.join(home, p)));
+      // KJC-TSK-1344: the session lives where CLAUDE_CONFIG_DIR / CODEX_HOME point.
+      const files = agentAuthFiles(a.name, { home, env }) ?? a.authPaths.map((p) => path.join(home, p));
+      const authenticated = installed && files.some((f) => existsSync(f));
       return { ...a, installed, authenticated };
     }),
   );
@@ -64,53 +67,83 @@ function defaultLaunch(agent, prompt) {
     });
   });
 }
+const failed = () => {
+  process.exitCode = 1;
+  return 1;
+};
+
+// No agent ready: say what only the person can do (log in, or install one).
+function explainNoAgent(agents, logger) {
+  const needLogin = agents.filter((a) => a.installed && !a.authenticated);
+  if (needLogin.length > 0) {
+    logger.error?.("Tienes el agente instalado pero falta iniciar sesión — eso solo puedes hacerlo tú (la cuenta es tuya; Karajan nunca toca tus credenciales):");
+    for (const a of needLogin) logger.error?.(`  ${a.label}:  ${a.login}`);
+    logger.error?.("Cuando hayas iniciado sesión, vuelve a escribir: kj go");
+    return;
+  }
+  logger.error?.("Karajan trabaja con un agente de IA que aún no tienes instalado. Elige uno, instálalo con su comando, e inicia sesión con TU cuenta (la cuenta es tuya):");
+  for (const a of agents) logger.error?.(`  ${a.label}:  ${a.install}`);
+  logger.error?.("Después, vuelve a escribir: kj go");
+}
+
+// At most one question, and only when more than one agent is ready.
+async function chooseAgent(ready, { flags, deps }) {
+  if (ready.length === 1) return ready[0];
+  const ask = deps.ask ?? createCliAskQuestion({ flags });
+  const answer = await ask("¿Con cuál de tus agentes quieres trabajar?", { options: ready.map((a) => a.name), default: ready[0].name });
+  return ready.find((a) => a.name === String(answer).trim()) ?? ready[0];
+}
+
+// Prepare ONCE: decisions already taken are never re-asked. Resolves false
+// when something is left for the person's hands (already said above).
+async function prepareOnce({ projectDir, config, logger, deps }) {
+  if (existsSync(path.join(projectDir, ".karajan", "review-gate"))) return true;
+  logger.info?.("Preparando tu proyecto (solo la primera vez)…");
+  // BOOT-A paso 3 (KJC-TSK-0857): el orden vive en UN sitio, kj bootstrap.
+  // Antes esta puerta cableaba su propia secuencia (git init y env install),
+  // así que la puerta del maggle y la técnica podían separarse sin que nadie
+  // se diera cuenta. Ahora las dos hacen lo mismo.
+  const booted = await (deps.bootstrap ?? bootstrapCommand)({ config, logger, flags: {}, deps: {} });
+  if (!booted.ok) {
+    logger.error?.(`Falta una cosa que solo puedes hacer tú, la tienes justo arriba (${booted.pending}). Cuando la hagas, vuelve a escribir: kj go`);
+    return false;
+  }
+  const prepared = deps.prepare ? await deps.prepare({ config, logger }) : null;
+  // Algo depende de tus manos (arriba tienes el detalle). Sin eso el
+  // proyecto quedaría a medias, así que paramos aquí en vez de seguir.
+  if (prepared?.exitCode) {
+    logger.error?.("Falta una cosa que solo puedes hacer tú, la tienes justo arriba. Cuando la hagas, vuelve a escribir: kj go");
+    return false;
+  }
+  return true;
+}
+
+// The board is the muggle's window — unless the project turned it off
+// (hu_board.enabled false is respected: KJC-BUG-0152). A board failure is
+// said and never stops the conversation from starting. Resolves whether it opened.
+async function openBoard({ config, logger, deps, windowMode }) {
+  if (config.hu_board?.enabled === false) return false;
+  const openPath = windowMode ? "/?maggle=1&window=1" : "/?maggle=1";
+  try {
+    await (deps.board ?? defaultBoard)({ config, logger, openPath });
+    return true;
+  } catch (err) {
+    logger.warn?.(`El tablero no pudo abrirse (${err.message}) — la conversación arranca igual.`);
+    return false;
+  }
+}
+
 export async function goCommand({ config = {}, logger = console, flags = {}, deps = {} } = {}) {
   const projectDir = config.projectDir || process.cwd();
   const agents = await (deps.detect ?? detectMaggleAgents)();
   const ready = agents.filter((a) => a.installed && a.authenticated);
-  const needLogin = agents.filter((a) => a.installed && !a.authenticated);
   if (ready.length === 0) {
-    if (needLogin.length > 0) {
-      logger.error?.("Tienes el agente instalado pero falta iniciar sesión — eso solo puedes hacerlo tú (la cuenta es tuya; Karajan nunca toca tus credenciales):");
-      for (const a of needLogin) logger.error?.(`  ${a.label}:  ${a.login}`);
-      logger.error?.("Cuando hayas iniciado sesión, vuelve a escribir: kj go");
-    } else {
-      logger.error?.("Karajan trabaja con un agente de IA que aún no tienes instalado. Elige uno, instálalo con su comando, e inicia sesión con TU cuenta (la cuenta es tuya):");
-      for (const a of agents) logger.error?.(`  ${a.label}:  ${a.install}`);
-      logger.error?.("Después, vuelve a escribir: kj go");
-    }
-    process.exitCode = 1;
-    return 1;
-  }
-  let chosen = ready[0];
-  if (ready.length > 1) {
-    const ask = deps.ask ?? createCliAskQuestion({ flags });
-    const answer = await ask("¿Con cuál de tus agentes quieres trabajar?", { options: ready.map((a) => a.name), default: ready[0].name });
-    chosen = ready.find((a) => a.name === String(answer).trim()) ?? ready[0];
+    explainNoAgent(agents, logger);
+    return failed();
   }
+  const chosen = await chooseAgent(ready, { flags, deps });
   logger.info?.(`Trabajarás con ${chosen.label}.`);
-  // Prepare ONCE: decisions already taken are never re-asked.
-  if (!existsSync(path.join(projectDir, ".karajan", "review-gate"))) {
-    logger.info?.("Preparando tu proyecto (solo la primera vez)…");
-    // BOOT-A paso 3 (KJC-TSK-0857): el orden vive en UN sitio, kj bootstrap.
-    // Antes esta puerta cableaba su propia secuencia (git init y env install),
-    // así que la puerta del maggle y la técnica podían separarse sin que nadie
-    // se diera cuenta. Ahora las dos hacen lo mismo.
-    const booted = await (deps.bootstrap ?? bootstrapCommand)({ config, logger, flags: {}, deps: {} });
-    if (!booted.ok) {
-      logger.error?.(`Falta una cosa que solo puedes hacer tú, la tienes justo arriba (${booted.pending}). Cuando la hagas, vuelve a escribir: kj go`);
-      process.exitCode = 1;
-      return 1;
-    }
-    const prepared = deps.prepare ? await deps.prepare({ config, logger }) : null;
-    // Algo depende de tus manos (arriba tienes el detalle). Sin eso el
-    // proyecto quedaría a medias, así que paramos aquí en vez de seguir.
-    if (prepared?.exitCode) {
-      logger.error?.("Falta una cosa que solo puedes hacer tú, la tienes justo arriba. Cuando la hagas, vuelve a escribir: kj go");
-      process.exitCode = 1;
-      return 1;
-    }
-  }
+  if (!(await prepareOnce({ projectDir, config, logger, deps }))) return failed();
   const prompt = (deps.prompt ?? buildGoPrompt)();
   // --window (MGL-E, ADR 0008): la conversación vive DENTRO del board — el
   // daemon hereda por env (HU_BOARD_TERMINAL_CWD/AGENT/PROMPT) el cwd, el
@@ -123,19 +156,7 @@ export async function goCommand({ config = {}, logger = console, flags = {}, dep
     process.env.HU_BOARD_TERMINAL_AGENT = chosen.name;
     process.env.HU_BOARD_TERMINAL_PROMPT = prompt;
   }
-  // The board is the muggle's window — unless the project turned it off
-  // (hu_board.enabled false is respected: KJC-BUG-0152). A board failure is
-  // said and never stops the conversation from starting.
-  let boardOpened = false;
-  if (config.hu_board?.enabled !== false) {
-    const openPath = windowMode ? "/?maggle=1&window=1" : "/?maggle=1";
-    try {
-      await (deps.board ?? defaultBoard)({ config, logger, openPath });
-      boardOpened = true;
-    } catch (err) {
-      logger.warn?.(`El tablero no pudo abrirse (${err.message}) — la conversación arranca igual.`);
-    }
-  }
+  const boardOpened = await openBoard({ config, logger, deps, windowMode });
   if (windowMode && boardOpened) {
     logger.info?.("Tu conversación vive en la ventana del navegador que se acaba de abrir. Si el tablero ya estaba arrancado de antes, reinícialo con kj board stop && kj go --window para que recoja este proyecto.");
     process.exitCode = 0;