karajan-code 4.31.1 → 4.32.0

package/package.json

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

package/src/checks/project-checks.js

@@ -23,6 +23,7 @@ import { runCommand } from "../utils/process.js";
 import { checkBinary } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { STRATEGY } from "./types.js";
+import { createRepoStateCheck } from "./repo-state.js";
 
 /**
  * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
@@ -241,5 +242,9 @@ export function getProjectChecks({ projectDir }) {
     createToolCheck({ signal: "terraform", tool: "terraform", label: "Terraform (project signal)", signals }),
     createEnvConsistencyCheck({ projectDir, signals }),
     createGhRemoteCheck({ projectDir }),
+    // BOOT-B (KJC-TSK-0858): the state of the repo itself, which no other
+    // check looks at — the order it was set up in, whether the contract
+    // travels, whether this clone declares who works it.
+    createRepoStateCheck({ projectDir }),
   ];
 }

package/src/checks/repo-state.js

@@ -0,0 +1,89 @@
+/**
+ * BOOT-B (KJC-TSK-0858, epic KJC-PCS-0088) — the state of the REPOSITORY.
+ *
+ * The cold-start map of 20-sep found projects raised outside the method, and
+ * nobody noticed until a gate blocked with no explanation: the harness
+ * installed before git, the gate marker never committed (so a clone inherits
+ * nothing), no identity declared (so the Sentinel later denies every git and
+ * gh call). None of the other checks looks at this: they check tools, ports,
+ * index coverage, the method's own report — never whether the repo itself was
+ * set up in the right order.
+ *
+ * Two rules, both learned the hard way in this codebase:
+ *  - The bootstrap phase is NOT a defect. A repo with no commit yet is
+ *    starting, and saying otherwise is the false alarm that teaches people to
+ *    ignore the output.
+ *  - Every symptom carries the literal command that repairs it. A diagnosis
+ *    nobody can act on is a complaint.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const STRATEGY_MANUAL = "manual";
+
+const git = (projectDir, args) => execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+const gitOk = (projectDir, args) => { try { git(projectDir, args); return true; } catch { return false; } };
+
+/** @internal Exported for dynamic import from tests. */
+export function createRepoStateCheck({ projectDir }) {
+  return {
+    name: "repo-state",
+    label: "estado del repositorio",
+    strategy: STRATEGY_MANUAL,
+    describe: "Detect a project raised or carried outside the method (order, contract, identity)",
+    async detect() {
+      const dir = projectDir;
+      const has = (rel) => existsSync(join(dir, rel));
+      const hardened = has(".karajan/hooks/pre-commit") || has(".karajan/review-gate");
+
+      // 1. No repository. The gates live in git hooks, so there is nothing to
+      //    govern yet — and if the harness is already there, it governs nothing.
+      if (!has(".git")) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: hardened
+            ? "el proyecto está sin repositorio y el harness ya está escrito: no gobierna nada"
+            : "el proyecto está sin repositorio, así que ningún gate del método puede actuar",
+          fix: "kj bootstrap (crea el repositorio y deja el método en orden), o git init si prefieres hacerlo a mano",
+        };
+      }
+
+      // 2. The harness written before git existed: nothing tracks the contract,
+      //    so cloning inherits nothing even though this clone looks hardened.
+      const hasCommits = gitOk(dir, ["rev-parse", "--verify", "HEAD"]);
+      if (!hasCommits) {
+        return hardened
+          ? { ok: true, severity: "info", detail: "fase de arranque: el método está escrito y falta el primer commit" }
+          : { ok: true, severity: "info", detail: "fase de arranque: repositorio recién creado, sin método todavía" };
+      }
+
+      const symptoms = [];
+      // Against HEAD, not the index (catch de codex): a file merely STAGED is
+      // not inherited by a clone, which is the whole point of this symptom.
+      const committed = (rel) => gitOk(dir, ["cat-file", "-e", `HEAD:${rel}`]);
+      if (hardened && !committed(".karajan/review-gate") && !committed(".karajan/hooks/pre-commit")) {
+        symptoms.push({
+          detail: "el harness está instalado pero su contrato no está en git: quien clone no hereda ningún gate",
+          fix: "git add .karajan/review-gate .karajan/hooks && git commit -m \"chore: el contrato del método\"",
+        });
+      }
+      if (hardened && !has(".karajan/identity.local.yml")) {
+        symptoms.push({
+          detail: "este clon no declara identidad, y el Sentinel denegará cada git y cada gh hasta que la declares",
+          fix: "kj identity set --gh <usuario> --email <correo>",
+        });
+      }
+
+      if (symptoms.length === 0) return { ok: true, severity: "info", detail: "el repositorio está en orden" };
+      return {
+        ok: false,
+        severity: "warn",
+        detail: symptoms.map((s) => s.detail).join(" · "),
+        fix: symptoms.map((s) => s.fix).join("  ·  "),
+      };
+    },
+  };
+}

package/src/cli/advanced-commands.js

@@ -9,6 +9,9 @@
 export const CORE_COMMANDS = [
   "go",
   "start",
+  // BOOT-A (KJC-TSK-0857): starting a project from nothing is as core as it
+  // gets — it is the first command a new project ever runs.
+  "bootstrap",
   "init",
   "run",
   "plan",

package/src/cli/register-meta.js

@@ -5,6 +5,8 @@ import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
 import { startCommand } from "../commands/start.js";
 import { goCommand } from "../commands/go.js";
+import { bootstrapCommand } from "../commands/bootstrap.js";
+import { PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 import { identityCommand } from "../commands/identity.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
@@ -158,6 +160,18 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // BOOT-A (KJC-TSK-0857, cold-start ADR): the pieces existed, the ORDER did
+  // not. One command from an empty directory to a project under the method.
+  program
+    .command("bootstrap")
+    .description("Del directorio vacío al método listo: repositorio, configuración, harness, gate y RAG, en el orden que funciona")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "bootstrap", flags, async ({ config, logger }) => {
+        const res = await bootstrapCommand({ config, logger, flags });
+        if (!res.ok) process.exitCode = PENDING_EXIT_CODE;
+      });
+    });
+
   // MGL-A (KJC-TSK-0808): the muggle launcher — one command, at most one
   // question, and the person lands inside a governed conversation.
   program

package/src/cli/register-pipeline.js

@@ -239,6 +239,10 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--prune-days <n>", "TTL in days for --prune (default: 14)")
     .option("--dry-run", "With --prune: report what would be removed without deleting")
     .option("--no-sonar", "Skip the deterministic Sonar pre-gate that runs before the cross-AI verdict")
+    // BOOT-D (KJC-TSK-0863): how the walkthrough gets INTO the verdict. Without
+    // this the rule could only complain, which is the gate with no exit.
+    .option("--walked <route>", "Recorrido comprobado como lo haría una persona (repetible) — queda en el veredicto", (v, prev) => [...(prev || []), v], [])
+    .option("--walked-with <tool>", "Con qué se comprobó el recorrido (por ejemplo chrome-devtools)")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
         // ENV-B1 (KJC-TSK-0637): the gate mode records a verdict tied to

package/src/commands/bootstrap.js

@@ -0,0 +1,131 @@
+/**
+ * BOOT-A (KJC-TSK-0857, epic KJC-PCS-0088) — `kj bootstrap`: from an empty
+ * directory to a project under the method, in one command.
+ *
+ * It invents nothing. The pieces already existed; what was missing was the
+ * ORDER and somebody imposing it. The field report that opened the cold-start
+ * ADR found nine walls on that path, and several of them fired precisely
+ * because the repository had been raised by hand, in the wrong sequence.
+ *
+ * Rules this command obeys:
+ *  - Idempotent. What is already there is reported as `already`, never redone.
+ *  - Fail loud, never half. A step that needs the person's hands STOPS the
+ *    sequence and says which one; nothing downstream pretends it ran.
+ *  - No guarantees without git: the gates live in git hooks, so the repo comes
+ *    first and a git that cannot run is the end of the line, not a warning.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ensureGitRepo } from "./init.js";
+import { initCommand } from "./init.js";
+import { envInstallCommand } from "./env.js";
+import { runStartScript, START_SCRIPT_CONTRACT } from "../start/project-script.js";
+
+const STEP_LABEL = {
+  git: "repositorio",
+  config: "configuración del proyecto",
+  method: "método activo (harness, gate y RAG)",
+  contract: "commit del contrato",
+  start: "arranque del proyecto",
+};
+
+/** What kj generates and the whole team must inherit by cloning. */
+const CONTRACT_PATHS = [
+  ".gitignore",
+  ".karajan/hooks",
+  ".karajan/review-gate",
+  ".karajan/adrs",
+  ".karajan/policy.yml",
+  ".claude",
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+];
+const CONTRACT_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
+
+const hasCommits = (projectDir, git) => {
+  try { git(["rev-parse", "--verify", "HEAD"]); return true; } catch { return false; }
+};
+
+/**
+ * @returns {Promise<{ok: boolean, pending: string|null, steps: Array<{name: string, status: "done"|"already"|"pending"}>}>}
+ */
+export async function bootstrapCommand({ config = {}, logger = console, flags = {}, deps = {} } = {}) {
+  const projectDir = config.projectDir || process.cwd();
+  const steps = [];
+  const say = (name, status, detail) => {
+    steps.push({ name, status });
+    const mark = status === "already" ? "·" : "✓";
+    logger.info?.(`${mark} ${STEP_LABEL[name]}${detail ? ` — ${detail}` : ""}`);
+  };
+  const stop = (name, why) => {
+    steps.push({ name, status: "pending" });
+    logger.error?.(`✗ ${STEP_LABEL[name]} — ${why}`);
+    return { ok: false, pending: name, steps };
+  };
+
+  // 1. The repository. Without it there are no hooks, and without hooks there
+  //    are no guarantees: this is the one step that cannot be skipped.
+  const hadRepo = existsSync(join(projectDir, ".git"));
+  if (!ensureGitRepo({ projectDir, logger: { info() {}, warn() {} }, gitFn: deps.gitFn })) {
+    return stop("git", "git no está disponible y las garantías de Karajan viven en sus hooks");
+  }
+  say("git", hadRepo ? "already" : "done", hadRepo ? "ya existía" : "creado, sin commit todavía");
+
+  // 2. The project's own configuration.
+  const hasConfig = existsSync(join(projectDir, ".karajan", "kj.config.yml"));
+  if (hasConfig) say("config", "already", "ya estaba");
+  else {
+    const init = await (deps.init ?? initCommand)({ logger, flags: { ...flags, noInteractive: true } });
+    if (init?.exitCode) return stop("config", "queda algo que solo puedes hacer tú, lo tienes arriba");
+    say("config", "done");
+  }
+
+  // 3. The method itself: harness, verdict gate, playbook and RAG index. This
+  //    is the step that turns an installed kj into an enforced one.
+  const hasGate = existsSync(join(projectDir, ".karajan", "review-gate"));
+  if (hasGate) say("method", "already", "ya estaba activo");
+  else {
+    const env = await (deps.env ?? envInstallCommand)({ config, logger, flags: { yes: true } });
+    if (env?.exitCode) return stop("method", "queda algo que solo puedes hacer tú, lo tienes arriba");
+    say("method", "done");
+  }
+
+  // 4. The contract commit. project-new.md asked the USER for it, and it was
+  //    the commit their own freshly installed gates rejected: the review gate
+  //    (KJC-BUG-0165) and the branch guard (KJC-BUG-0186) both exempt it now,
+  //    so kj can make it itself instead of leaving the person to fight it.
+  //    Only what kj generated, only while the repo has no commit, never the
+  //    person's own code. This is NOT the supervisor seal, which stays a human
+  //    act with its own four layers (ADR 0009).
+  const git = deps.gitRun ?? ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
+  if (hasCommits(projectDir, git)) say("contract", "already", "el repositorio ya tiene historia");
+  else {
+    const present = CONTRACT_PATHS.filter((p) => existsSync(join(projectDir, p)));
+    if (present.length === 0) say("contract", "already", "no hay contrato que commitear");
+    else {
+      try {
+        git(["add", "--", ...present]);
+        git(["commit", "-m", CONTRACT_MESSAGE]);
+      } catch (err) {
+        // Nunca explotar aquí: lo más probable es que falte la identidad del
+        // clon, y ese cauce ya lo pide el paso anterior (KJC-BUG-0188).
+        return stop("contract", `git no pudo commitear el contrato: ${String(err.message).split("\n")[0]}`);
+      }
+      say("contract", "done", `${present.length} ruta(s) del contrato`);
+    }
+  }
+
+  // 5. Does the project actually run? kj verified the method; nobody verified
+  //    the application (BOOT-C, KJC-TSK-0862). It REPORTS, never blocks: a
+  //    start script written badly must not stop work over something unrelated,
+  //    and a tree that was already broken has to be said BEFORE implementing.
+  const start = await (deps.start ?? runStartScript)({ projectDir, config });
+  if (start.status === "absent") say("start", "already", `sin guion de arranque — ${START_SCRIPT_CONTRACT}`);
+  else if (start.status === "ok") say("start", "done", "el proyecto arranca y su humo pasa");
+  else say("start", "already", `el árbol YA venía roto (${start.status}) — no lo ha causado este trabajo`);
+
+  return { ok: true, pending: null, steps };
+}

package/src/commands/go.js

@@ -12,8 +12,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { checkBinary } from "../utils/agent-detect.js";
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
-import { envInstallCommand } from "./env.js";
-import { ensureGitRepo } from "./init.js";
+import { bootstrapCommand } from "./bootstrap.js";
 import { boardCommand } from "./board.js";
 // The interactive launchers a muggle can live inside (v1: the two the epic
 // names). Auth heuristics are the same cheap file checks reviewer-fallback
@@ -44,9 +43,6 @@ export function buildGoPrompt() {
     "Empieza presentándote en dos frases y preguntando qué quiere construir o cambiar hoy.",
   ].join("\n");
 }
-async function defaultPrepare({ config, logger }) {
-  return envInstallCommand({ config, logger, flags: { yes: true } });
-}
 export async function defaultBoard({ config, logger, runBoard = boardCommand, openPath = "/?maggle=1" }) {
   const port = config.hu_board?.port || 4000;
   await runBoard({ action: "start", port, bind: "127.0.0.1", logger });
@@ -96,14 +92,17 @@ export async function goCommand({ config = {}, logger = console, flags = {}, dep
   // 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)…");
-    // KJC-BUG-0191: empezar en una carpeta vacía es lo natural, y kj env
-    // install se niega a correr sin repositorio. Lo creamos nosotros.
-    if (!ensureGitRepo({ projectDir, logger })) {
-      logger.error?.("No he podido preparar el control de versiones de tu proyecto (git). Instálalo y vuelve a escribir: kj go");
+    // 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 = await (deps.prepare ?? defaultPrepare)({ config, logger });
+    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) {

package/src/commands/review-gate.js

@@ -15,6 +15,7 @@ import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
 import { checkSonarRequirement, SONAR_RULE_ID } from "../review/sonar-requirement.js";
 import { checkRagRequirement, checkRagVerdict, ragBlock, RAG_RULE_ID } from "../review/rag-requirement.js";
+import { checkUiEvidence, uiBlock } from "../review/ui-evidence.js";
 import { readRagLedger } from "../review/rag-ledger.js";
 import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
@@ -482,6 +483,20 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       + twins.map((t) => `- ${t}`).join("\n");
   }
 
+  // BOOT-D (KJC-TSK-0863): green is not proof for what a person SEES. kj does
+  // not drive the browser (the host has it); it demands the walkthrough and
+  // records it in the verdict, bound to the diff like sonar and rag. It WARNS:
+  // the last proof, never the only one, and a gate that fires often teaches
+  // people to skip gates.
+  const walked = Array.isArray(flags.walked) ? flags.walked : [];
+  const uiReq = checkUiEvidence({
+    stagedFiles: changedFiles,
+    evidence: walked.length > 0 ? { walked, tool: flags.walkedWith ?? null } : null,
+    standingExceptions: std.standing,
+  });
+  if (uiReq.warn) console.log(`⚠ ${uiReq.reason}`);
+  const uiRecord = uiBlock(uiReq);
+
   // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
   // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
   // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
@@ -504,7 +519,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
-  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord });
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord, ui: uiRecord });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;

package/src/review/one-shot-review.js

@@ -47,6 +47,8 @@ export async function runOneShotReview({
   sonar = null,
   // KJC-TSK-0849 (ADR 0010): what the session's RAG ledger proved, same place.
   rag = null,
+  // BOOT-D (KJC-TSK-0863): the walkthrough of what a person sees, same place.
+  ui = null,
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
@@ -129,6 +131,9 @@ export async function runOneShotReview({
     summary: parsed.summary || parsed.raw_summary || "",
     ...(sonar ? { sonar } : {}),
     ...(rag ? { rag } : {}),
+    // BOOT-D (KJC-TSK-0863): the walkthrough of what a person sees travels with
+    // the verdict, bound to this diff, like the other two proofs.
+    ...(ui ? { ui } : {}),
     confidence: parsed.confidence ?? null,
   });
 }

package/src/review/ui-evidence.js

@@ -0,0 +1,65 @@
+/**
+ * BOOT-D (KJC-TSK-0863) — the done-statement of something a person SEES is not
+ * proved by a green suite.
+ *
+ * The Anthropic write-up on long-running agents reports it as an observed
+ * failure: the agent marked features complete without checking them. This
+ * codebase has the same hole. `impeccable` gives an AI OPINION about the diff,
+ * which is precisely what KJC-TSK-0726 rejects; what is missing is the proof
+ * that the route works when a person walks it.
+ *
+ * kj does not drive the browser: the host already has Chrome DevTools, and
+ * duplicating that would tie kj to one runner. kj DEMANDS the evidence and
+ * records it in the verdict, bound to the diff, exactly as it does with sonar
+ * and rag.
+ *
+ * It WARNS, it does not block. The article itself admits the browser misses
+ * native modals, so this is the last proof, never the only one — and a gate
+ * that fails often teaches people to skip gates, which is the doctrine behind
+ * every other rule here.
+ */
+
+export const UI_RULE_ID = "method.ui.evidence";
+
+// What a person can actually see. Deliberately narrow: a false demand costs
+// more than a missed one while this only warns.
+const VISIBLE = /\.(jsx|tsx|vue|svelte|astro|css|scss|sass|less|html)$/i;
+
+const liveGrant = (standingExceptions, now) => (standingExceptions || []).find((e) => {
+  if (e?.rule_id !== UI_RULE_ID) return false;
+  const until = Date.parse(e?.expiresAt ?? "");
+  return Number.isFinite(until) && until > now.getTime();
+});
+
+/**
+ * @returns {{ok: boolean, mode: "not-visible"|"walked"|"granted"|"missing", visible: string[], warn?: boolean, reason?: string, evidence?: object, grant?: object}}
+ */
+export function checkUiEvidence({ stagedFiles = [], evidence = null, standingExceptions = [], now = new Date() } = {}) {
+  const visible = stagedFiles.filter((f) => VISIBLE.test(String(f)));
+  if (visible.length === 0) return { ok: true, mode: "not-visible", visible };
+
+  const walked = Array.isArray(evidence?.walked) ? evidence.walked.filter(Boolean) : [];
+  if (walked.length > 0) return { ok: true, mode: "walked", visible, evidence: { walked, tool: evidence.tool ?? null } };
+
+  const grant = liveGrant(standingExceptions, now);
+  if (grant) return { ok: true, mode: "granted", visible, grant };
+
+  return {
+    ok: true,
+    warn: true,
+    mode: "missing",
+    visible,
+    reason: `verde no es prueba: ${visible.length} fichero(s) que una persona VE (${visible.join(", ")}) sin recorrido comprobado — recórrelo como lo haría ella y deja constancia`,
+  };
+}
+
+/** The block that travels inside the verdict, bound to the diff like sonar's. */
+export function uiBlock(req) {
+  if (!req || req.mode === "not-visible") return null;
+  return {
+    mode: req.mode,
+    walked: req.evidence?.walked ?? [],
+    tool: req.evidence?.tool ?? null,
+    visible: req.visible ?? [],
+  };
+}

package/src/start/project-script.js

@@ -0,0 +1,84 @@
+/**
+ * BOOT-C (KJC-TSK-0862) — the project's start script.
+ *
+ * From the Anthropic write-up on harnesses for long-running agents, and from
+ * the cold-start map: a session burns tokens working out how the project is
+ * launched, and worse, starts building on a tree that was already broken
+ * without knowing it. kj verifies the method; nobody verified that the
+ * application runs.
+ *
+ * kj declares the CONTRACT and checks it. The project writes the script,
+ * because kj cannot know how a project it has never seen is launched, and
+ * generating one from stack detection would produce the decorative artefact
+ * this codebase already rejects elsewhere (a config without its tool).
+ *
+ * It reports, it does not block: a badly written script must not stop work
+ * over something unrelated to the card. It earns the right to block when it
+ * proves reliable, the same path Sonar and the RAG took.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const DEFAULT_START_SCRIPT = ".karajan/start.sh";
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const MAX_OUTPUT_BYTES = 64 * 1024;
+
+export const START_SCRIPT_CONTRACT = [
+  "El guion de arranque levanta lo que haya que levantar y corre un humo de referencia.",
+  "Sale con 0 si el proyecto arranca y el humo pasa; con otro código si no.",
+  "No modifica el árbol ni depende de credenciales: solo responde si esto funciona ahora mismo.",
+].join(" ");
+
+/** Where the start script lives: the project's config decides, with a default. */
+export function startScriptPath(projectDir, config = {}) {
+  return join(projectDir, config.start_script || DEFAULT_START_SCRIPT);
+}
+
+/**
+ * @returns {Promise<{status: "absent"|"ok"|"broken"|"timeout", exitCode?: number, output?: string, contract?: string, path: string}>}
+ */
+export function runStartScript({ projectDir, config = {}, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const script = startScriptPath(projectDir, config);
+  if (!existsSync(script)) {
+    return Promise.resolve({ status: "absent", path: script, contract: START_SCRIPT_CONTRACT });
+  }
+  return new Promise((resolve) => {
+    const ownGroup = process.platform !== "win32";
+    const child = spawn("sh", [script], { cwd: projectDir, detached: ownGroup });
+    let output = "";
+    let truncated = false;
+    let timedOut = false;
+    // Bounded on purpose (catch de codex): a verbose or runaway script would
+    // otherwise eat the CLI's memory for the whole timeout. The LAST bytes are
+    // the ones worth keeping — that is where a failure explains itself.
+    const collect = (buf) => {
+      output += String(buf);
+      if (output.length > MAX_OUTPUT_BYTES) {
+        output = output.slice(-MAX_OUTPUT_BYTES);
+        truncated = true;
+      }
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    // Kill the GROUP, not just the shell (catch de codex): this script's whole
+    // job is to START things, so the dev server it launched would keep its port
+    // long after we reported a timeout.
+    const killTree = () => {
+      try {
+        if (ownGroup && child.pid) process.kill(-child.pid, "SIGKILL");
+        else child.kill("SIGKILL");
+      } catch { /* ya no está */ }
+    };
+    // A script that hangs is not a verdict: it is a script that hangs.
+    const timer = setTimeout(() => { timedOut = true; killTree(); }, timeoutMs);
+    child.on("error", (err) => { clearTimeout(timer); resolve({ status: "broken", path: script, exitCode: null, output: `${output}${err.message}`, truncated }); });
+    // Resolve on CLOSE, never before: the answer comes once the tree is down.
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) resolve({ status: "timeout", path: script, output, truncated });
+      else resolve({ status: code === 0 ? "ok" : "broken", exitCode: code, path: script, output, truncated });
+    });
+  });
+}