karajan-code 4.70.3 → 5.0.0

package/src/orchestrator/fs-leak-detector.js

@@ -1,228 +0,0 @@
-/**
- * KJC-BUG-0032: detect coder writes outside projectDir.
- *
- * The coder subprocess runs with `cwd: projectDir`, but its Bash
- * tool can `cd` anywhere. Real-world repro: a HU titled
- *   "Initialize project skeleton: create assistant/ directory…"
- * had Claude run `cd /home/manu/assistant && pnpm init …`. The
- * resulting 36 MB of code lived in $HOME/assistant — outside the
- * projectDir, outside any git repo, lost to tracking, commits and
- * review. The coder was happy, the user only noticed by accident.
- *
- * This module is a deterministic guard: snapshot $HOME's top-level
- * directory entries before the coder runs, scan again after, and
- * any new entry that isn't projectDir itself is a leak.
- *
- * Why top-level only:
- *   - Catches the realistic failure mode (coder creates a sibling
- *     `~/something` for the project skeleton).
- *   - Cheap (single readdirSync) — no `find -newer` traversal of
- *     $HOME's potentially massive tree.
- *   - Doesn't thrash on writes to existing dirs like ~/.npm or
- *     ~/.cache that legitimate node tooling touches.
- *
- * What it WON'T catch (acknowledged trade-offs):
- *   - Writes deep inside existing $HOME subdirs (e.g. modifying
- *     ~/.bashrc — would need a per-file mtime scan).
- *   - Writes to /tmp (high false-positive rate; /tmp is ephemeral
- *     by spec; less risky).
- *   - Writes to /etc, /var, etc. (would require root anyway).
- *
- * The first-pass guard is the right ROI. Subsequent iterations
- * can extend coverage if real-world cases warrant it.
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-/**
- * Snapshot the immediate children of $HOME. Returns a Set of names
- * (not full paths) so detectNewHomeEntries can do a quick set
- * difference. Empty set on any FS error — treats "can't snapshot"
- * the same as "snapshot OK with nothing".
- *
- * @returns {Set<string>}
- */
-export function snapshotHomeTopLevel() {
-  try {
-    return new Set(fs.readdirSync(os.homedir()));
-  } catch {
-    return new Set();
-  }
-}
-
-/**
- * Detect $HOME top-level entries that didn't exist when `before`
- * was snapshotted. Excludes projectDir itself in case the user
- * keeps their projects directly under $HOME (no false positive
- * if `projectDir = $HOME/some-project` already existed).
- *
- * @param {Set<string>} before — snapshot from snapshotHomeTopLevel()
- * @param {string|null} projectDir — current run's projectDir
- * @returns {string[]} absolute paths of new entries (potential leaks)
- */
-export function detectNewHomeEntries(before, projectDir) {
-  const home = os.homedir();
-  let after;
-  try {
-    after = fs.readdirSync(home);
-  } catch {
-    return [];
-  }
-  const projectDirAbs = projectDir ? path.resolve(projectDir) : null;
-  const leaks = [];
-  for (const name of after) {
-    if (before.has(name)) continue;
-    const full = path.join(home, name);
-    // Skip projectDir itself (defensive — shouldn't happen since
-    // projectDir is pre-existing, but a paranoid check costs nothing).
-    if (projectDirAbs && path.resolve(full) === projectDirAbs) continue;
-    leaks.push(full);
-  }
-  return leaks;
-}
-
-/**
- * Issue #546: filter potential leaks by attribution. Snapshot diff
- * cannot tell coder writes from concurrent writes by other processes
- * (host AI scratch files, parallel tooling, manual edits). Real-world
- * 2026-04-29 incident: a host-side write of `~/karajan-status-snapshot.md`
- * during a kj run aborted HU 003 with a false positive.
- *
- * Heuristic: if the coder genuinely created the leaked path, its
- * transcript will mention the path or its basename — the coder
- * narrates what it does (Bash commands, file operations, todos). If
- * neither the absolute path nor the basename appears anywhere in
- * the transcript, the entry was created by some other process during
- * the iteration window and should NOT abort the HU.
- *
- * False-negative trade-off: a coder that creates a file silently
- * (e.g. via a script that doesn't echo paths) escapes this filter.
- * That trade-off is acceptable: the original leak class (coder
- * skeleton-creating in $HOME) always emits the path in commands; the
- * silent-write case has never been observed.
- *
- * Back-compat: when `transcript` is empty/null/undefined, NO filtering
- * happens — every detected leak is passed through unchanged. This
- * preserves the strict behaviour for callers that don't have a
- * transcript handy.
- *
- * @param {string[]} leaks — output of detectNewHomeEntries()
- * @param {string|null|undefined} transcript — coder's full output text
- * @returns {string[]} filtered leaks (the subset attributable to coder)
- */
-/**
- * KJC-BUG-0180 — attribution is not severity. `verifyLeaksAgainstTranscript`
- * stays strict on purpose: with no transcript it returns everything. But
- * "the snapshot changed and there is NO evidence the coder did it" is a
- * different fact from "the coder wrote there", and only the second one
- * should kill the run. The flaky CI failure was exactly this: other test
- * files writing under $HOME during the iteration window, an empty
- * transcript from a mocked coder, and the whole flow failing and retrying.
- *
- * @returns {{attributed: string[], unattributed: string[]}} — `attributed`
- *   fails the run; `unattributed` is reported and the work goes on.
- */
-export function splitLeakEvidence(leaks, transcript) {
-  const hasTranscript = typeof transcript === "string" && transcript.length > 0;
-  const found = verifyLeaksAgainstTranscript(leaks, transcript);
-  return hasTranscript ? { attributed: found, unattributed: [] } : { attributed: [], unattributed: found };
-}
-
-export function verifyLeaksAgainstTranscript(leaks, transcript) {
-  if (!Array.isArray(leaks) || leaks.length === 0) return [];
-  if (!transcript || typeof transcript !== "string" || transcript.length === 0) {
-    return leaks; // no transcript ⇒ no filtering, original behaviour
-  }
-  return leaks.filter((p) => {
-    const base = path.basename(p);
-    // Skip artefacts whose basename is too short to be discriminating
-    // (e.g. ".cache") — a 3-char basename matched against a long
-    // transcript is meaningless. For such cases we prefer the strict
-    // behaviour (flag) since they're rare and the user can inspect.
-    if (base.length < 4) return true;
-    return transcript.includes(p) || transcript.includes(base);
-  });
-}
-
-/**
- * Layer 2 detection (KJC-BUG-0032): scan the coder's transcript for
- * `cd <abs-path> && <write-cmd>` patterns where <abs-path> is OUTSIDE
- * projectDir. Catches the bug class even when the target directory
- * already existed (so snapshot-diff misses it) — e.g.
- *   `cd /home/manu/assistant && pnpm init -y`
- * when `~/assistant` was pre-existing.
- *
- * Filters applied:
- *  - Only absolute paths (`/`, `~/`, `$HOME/`) — relative `cd subdir`
- *    is assumed inside projectDir.
- *  - Skips `/tmp/...` (ephemeral, legitimate scratch).
- *  - Skips targets inside projectDir.
- *  - Only flags if followed (same line, within 200 chars) by a
- *    write/creation command: mkdir / touch / cp / mv / git init /
- *    {pnpm,npm,yarn} init / {pnpm,npm,yarn,npx} create / cat > /
- *    echo > / shell redirect (>, >>).
- *  - Pure read commands (ls, which, cat <file>, grep) do NOT flag.
- *
- * @param {string|null|undefined} transcript
- * @param {string|null} projectDir
- * @returns {string[]} deduplicated absolute leak paths
- */
-export function detectTranscriptCdLeaks(transcript, projectDir) {
-  if (!transcript || typeof transcript !== "string") return [];
-  const projectDirAbs = projectDir ? path.resolve(projectDir) : null;
-  const homeDir = os.homedir();
-  // Capture cd target + the next ~200 chars of the same line for write-cmd lookup.
-  // Two-step (S5843, complexity 31): capture ANY cd target with one simple
-  // class, then filter to the absolute/home-rooted shapes the original
-  // single alternation required (~/, $HOME/, /).
-  const cdRegex = /\bcd\s+([^\s&|;`'"\n]+)([^\n]{0,200})/g;
-  const absoluteTargetRe = /^(?:~\/|\$HOME\/|\/)/;
-  const writeCmdRegex = /\b(mkdir|touch|cp|mv|git\s+init|(?:pnpm|npm|yarn)\s+(?:init|create)|npx\s+create|cat\s*>|echo\s+[^|]*>|>>?\s*\S)/i;
-  const leaks = new Set();
-  let match;
-  while ((match = cdRegex.exec(transcript)) !== null) {
-    if (!absoluteTargetRe.test(match[1])) continue;
-    const original = match[1];
-    let target = original;
-    const rest = match[2] || "";
-    if (target.startsWith("~/")) target = path.join(homeDir, target.slice(2));
-    else if (target.startsWith("$HOME/")) target = path.join(homeDir, target.slice(6));
-    const abs = path.resolve(target);
-    // /tmp guard only applies to literal /tmp/... paths (ephemeral scratch),
-    // not to ~/ expansions that happen to land in /tmp during tests.
-    if (original === "/tmp" || original.startsWith("/tmp/")) continue;
-    if (projectDirAbs && (abs === projectDirAbs || abs.startsWith(projectDirAbs + path.sep))) continue;
-    if (!writeCmdRegex.test(rest)) continue;
-    leaks.add(abs);
-  }
-  return Array.from(leaks);
-}
-
-/**
- * Format a leak list into a multiline plain-Spanish error message.
- * Includes a hint about how to recover (move-or-delete) so the user
- * isn't left guessing.
- *
- * @param {string[]} leaks — output of detectNewHomeEntries()
- * @param {string} projectDir
- * @returns {string}
- */
-export function formatLeakMessage(leaks, projectDir) {
-  const list = leaks.map((p) => `  - ${p}`).join("\n");
-  return [
-    `El coder creó archivos FUERA del proyecto (${projectDir}).`,
-    "",
-    "Rutas detectadas:",
-    list,
-    "",
-    "Esto suele pasar cuando una HU usa una ruta absoluta o relativa a $HOME y el coder la sigue literalmente. Las rutas SIEMPRE deben ser relativas a la raíz del proyecto.",
-    "",
-    "Qué hacer:",
-    "  1. Inspecciona las rutas listadas. Si tienen código útil, muévelo a tu proyecto manualmente.",
-    "  2. Borra las rutas listadas si son basura.",
-    "  3. Edita el título / scope de la HU para que no contenga rutas absolutas.",
-    "  4. Vuelve a lanzar la HU.",
-  ].join("\n");
-}

package/src/orchestrator/hu-scheduler.js

@@ -1,114 +0,0 @@
-/**
- * hu-scheduler — pure scheduling for parallel HU execution (KJC-TSK-0623,
- * épica KJC-PCS-0065). Decides WHICH HUs may run concurrently; it never
- * launches anything. Two rules, both conservative by design:
- *
- *   1. Dependencies: every blocked_by id must be in completedIds.
- *   2. Scope isolation: two HUs whose scopes touch the same path prefix are
- *      never scheduled together — predictable merge conflicts cost more than
- *      the parallelism they'd buy. An HU with NO scope has an unknown blast
- *      radius, so it runs alone (exclusive with everything).
- */
-
-/**
- * Extract path-like tokens from a free-form scope. The planner writes scope
- * as prose ("src/auth y tests/auth", "docs/*.md"); we keep anything that
- * looks like a path or glob, normalized to its base directory.
- */
-export function scopeTokens(scope) {
-  if (!scope || typeof scope !== "string") return [];
-  const matches = scope.match(/[\w.-]+(?:\/[\w*.{}-]+)+|[\w.-]+\/(?=\s|$|,)/g) || [];
-  return matches
-    .map((raw) => {
-      // Cut the token at its first glob segment: "src/**/*.js" → "src".
-      const segments = raw.replace(/\/+$/, "").split("/");
-      const firstGlob = segments.findIndex((s) => s.includes("*") || s.includes("{"));
-      return (firstGlob === -1 ? segments : segments.slice(0, firstGlob)).join("/");
-    })
-    .filter(Boolean);
-}
-
-/** True when two token lists share a path-prefix relationship. */
-function tokensOverlap(a, b) {
-  for (const ta of a) {
-    for (const tb of b) {
-      if (ta === tb || ta.startsWith(`${tb}/`) || tb.startsWith(`${ta}/`)) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * True when two HUs cannot run concurrently: either one has no parseable
- * scope (unknown blast radius ⇒ exclusive) or their scopes overlap.
- */
-export function husConflict(huA, huB) {
-  const a = scopeTokens(huA.scope);
-  const b = scopeTokens(huB.scope);
-  if (a.length === 0 || b.length === 0) return true;
-  return tokensOverlap(a, b);
-}
-
-/**
- * Split one dependency-level group into conflict-free chunks of at most
- * `maxParallel` HUs (KJC-TSK-0626). Every chunk runs concurrently; chunks
- * run one after another. maxParallel 1 ⇒ singletons (fully sequential).
- * Same conservative rules as husConflict: no parseable scope ⇒ runs alone.
- *
- * @param {Array<{id: string, scope?: string|null}>} stories - full story list
- * @param {string[]} groupIds - ids of one dependency-level group, in order
- * @param {number} maxParallel
- * @returns {string[][]} chunks of ids
- */
-export function partitionConflictFree(stories, groupIds, maxParallel = 1) {
-  if (maxParallel <= 1) return groupIds.map((id) => [id]);
-  const byId = new Map(stories.map((s) => [s.id, s]));
-  const chunks = [];
-  for (const id of groupIds) {
-    const story = byId.get(id) ?? { id };
-    const fit = chunks.find(
-      (chunk) => chunk.length < maxParallel && !chunk.some((otherId) => husConflict(story, byId.get(otherId) ?? { id: otherId })),
-    );
-    if (fit) fit.push(id);
-    else chunks.push([id]);
-  }
-  return chunks;
-}
-
-/**
- * Select the next HUs to launch, order-preserving and greedy.
- *
- * @param {object} args
- * @param {Array<{id: string, blocked_by?: string[], scope?: string|null}>} args.hus - candidates, in plan order
- * @param {string[]} [args.completedIds] - HUs already done (dependency source)
- * @param {Array<{id: string, scope?: string|null}>} [args.inFlight] - HUs currently running
- * @param {number} [args.maxParallel] - total concurrency cap (in-flight included)
- * @returns {{ selected: object[], blocked: Array<{id: string, reason: string}> }}
- */
-export function selectRunnableHus({ hus = [], completedIds = [], inFlight = [], maxParallel = 1 } = {}) {
-  const done = new Set(completedIds);
-  const flying = new Set(inFlight.map((h) => h.id));
-  const slots = Math.max(0, maxParallel - inFlight.length);
-  const selected = [];
-  const blocked = [];
-
-  for (const hu of hus) {
-    if (flying.has(hu.id) || done.has(hu.id)) continue;
-    const missing = (hu.blocked_by || []).filter((dep) => !done.has(dep));
-    if (missing.length > 0) {
-      blocked.push({ id: hu.id, reason: `waiting for ${missing.join(", ")}` });
-      continue;
-    }
-    if (selected.length >= slots) {
-      blocked.push({ id: hu.id, reason: "no free slot" });
-      continue;
-    }
-    const rival = [...inFlight, ...selected].find((other) => husConflict(hu, other));
-    if (rival) {
-      blocked.push({ id: hu.id, reason: `scope conflicts with ${rival.id}` });
-      continue;
-    }
-    selected.push(hu);
-  }
-  return { selected, blocked };
-}