karajan-code 4.6.3 → 4.8.0

package/package.json

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

package/src/agents/base-agent.js

@@ -11,6 +11,7 @@
  */
 
 import { defaultEnvironment } from "../infrastructure/environment.js";
+import { buildAgentEnv } from "../utils/role-env.js";
 
 const MODEL_NOT_SUPPORTED_PATTERNS = [
   /model.{0,30}is not supported/i,
@@ -49,6 +50,25 @@ export class BaseAgent {
    * @returns {Promise<CommandRunResult>}
    */
   async runCommand(command, args = [], options = {}) {
+    // KJC-TSK-0693: the subprocess gets an env allowlist, never the user's
+    // whole environment. security.env_allowlist:false opts out.
+    if (this.config?.security?.env_allowlist !== false) {
+      // Solomon-arbitrated contract (KJC-TSK-0693): an explicit env WITH a
+      // PATH is a COMPLETE child env (agents build those from process.env and
+      // deliberately strip vars — cleanExecaOpts drops CLAUDECODE, qwen
+      // unsets gemini's trust var) and is filtered AS GIVEN. An env WITHOUT
+      // a PATH is a partial overlay and merges over the inherited env first,
+      // so an overlay caller can never cost the child PATH/HOME.
+      const complete = options.env && ("PATH" in options.env || "Path" in options.env);
+      const base = complete ? options.env : { ...process.env, ...(options.env || {}) };
+      options = {
+        ...options,
+        env: buildAgentEnv(base, {
+          agent: this.name,
+          passthrough: this.config?.security?.env_passthrough || [],
+        }),
+      };
+    }
     return this.environment.runner.run(command, args, options);
   }
 

package/src/audit/deterministic-summary.js

@@ -65,7 +65,7 @@ function formatAiSlopBlock(slop) {
 
 function formatInjectionBlock(inj) {
   if (!inj.available) return ["### Prompt-injection scan", `- Status: not available — ${inj.reason || "scan failed"}`, ""];
-  const lines = ["### Prompt-injection scan (specs / domain / onboarding)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
+  const lines = ["### Prompt-injection scan (agent-context surface: CLAUDE/AGENTS/GEMINI.md, templates, .rulesync, .karajan)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
   if ((inj.total ?? 0) > 0) {
     for (const [severity, items] of Object.entries(groupInjectionBySeverity(inj.findings || []))) {
       if (items.length === 0) continue;

package/src/audit/injection-findings.js

@@ -17,6 +17,15 @@ const SCAN_TARGETS = [
   { rel: ".karajan/specs", kind: "dir" },
   { rel: ".karajan/onboarding", kind: "dir" },
   { rel: ".karajan/domain.md", kind: "file" },
+  // KJC-TSK-0695: the agent-context surface — whatever lands in the host
+  // agent's context every session is the real injection vector.
+  { rel: "CLAUDE.md", kind: "file" },
+  { rel: "AGENTS.md", kind: "file" },
+  { rel: "GEMINI.md", kind: "file" },
+  { rel: ".cursorrules", kind: "file" },
+  { rel: path.join(".github", "copilot-instructions.md"), kind: "file" },
+  { rel: "templates", kind: "dir" },
+  { rel: ".rulesync", kind: "dir" },
 ];
 
 export async function collectInjectionFindings(rootDir, logger = null) {

package/src/checks/ai-surface.js

@@ -0,0 +1,76 @@
+/**
+ * ai-surface — MCP inventory with drift detection (KJC-TSK-0694).
+ *
+ * Every new tool an agent gains is one more access. An inventory nobody
+ * reconciles is "the feeling of control without the control", so kj check
+ * flags what APPEARED since the last run and asks the user to own it.
+ * A nudge, never a gate. ~/.claude.json is scoped to its global block plus
+ * THIS project's entry — other projects' MCPs are not reachable here.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const sources = (projectDir, home) => [
+  { file: path.join(projectDir, ".mcp.json"), format: "json" },
+  { file: path.join(home, ".claude.json"), format: "json" },
+  { file: path.join(home, ".codex", "config.toml"), format: "toml" },
+  { file: path.join(home, ".gemini", "settings.json"), format: "json" },
+];
+
+function jsonServerNames(text, projectDir) {
+  try {
+    const parsed = JSON.parse(text);
+    const names = new Set(Object.keys(parsed.mcpServers || {}));
+    for (const name of Object.keys(parsed.projects?.[projectDir]?.mcpServers || {})) names.add(name);
+    return names;
+  } catch {
+    return new Set();
+  }
+}
+
+const tomlServerNames = (text) =>
+  new Set([...text.matchAll(/^\s*\[mcp_servers\.["']?([^\]"']+)["']?\]/gm)].map((m) => m[1]));
+
+/** Sorted `name (config-file)` entries for every MCP reachable in this project. */
+export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+  const surface = new Set();
+  for (const { file, format } of sources(projectDir, home)) {
+    if (!existsSync(file)) continue;
+    let text;
+    try { text = readFileSync(file, "utf8"); } catch { continue; }
+    const names = format === "toml" ? tomlServerNames(text) : jsonServerNames(text, projectDir);
+    for (const name of names) surface.add(`${name} (${path.basename(file)})`);
+  }
+  return [...surface].sort();
+}
+
+/**
+ * Diff the current surface against the last-seen snapshot and persist the
+ * new state. First run records the baseline silently.
+ */
+export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json") } = {}) {
+  const surface = collectAiSurface({ projectDir, home });
+  let state = {};
+  try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* first run or corrupt → baseline */ }
+  const prev = Array.isArray(state[projectDir]) ? state[projectDir] : null;
+  const added = prev ? surface.filter((e) => !prev.includes(e)) : [];
+  const removed = prev ? prev.filter((e) => !surface.includes(e)) : [];
+  state[projectDir] = surface;
+  try {
+    mkdirSync(path.dirname(statePath), { recursive: true });
+    writeFileSync(statePath, JSON.stringify(state, null, 2));
+  } catch { /* read-only FS — inventory still reports, just cannot remember */ }
+  return { surface, added, removed, first: !prev };
+}
+
+/** One line for kj check output. */
+export function formatAiSurface({ surface, added, removed, first }) {
+  const head = `ai surface: ${surface.length} MCP(s)`;
+  if (first) return `${head} — baseline recorded`;
+  const parts = [head];
+  if (added.length) parts.push(`NEW since last check: ${added.join(", ")} — approved by you?`);
+  if (removed.length) parts.push(`gone: ${removed.join(", ")}`);
+  return parts.join(" · ");
+}

package/src/cli/register-meta.js

@@ -379,6 +379,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--trend", "Append a sparkline of the harness score across the last 10 runs (uses .karajan/audit-history.db). KJC-TSK-0473.")
     .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
     .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
+    .option("--security", "Focused deterministic security pass: prompt-injection scan over the agent-context surface (CLAUDE.md/AGENTS.md/templates/.rulesync/.karajan) + OSV + Semgrep + Sonar. Skips basal-cost, webperf, madge, knip, ai-slop, harness and the LLM — zero tokens. Designed for agents to self-invoke when a task touches sensitive surface (KJC-TSK-0695).")
     .option("-y, --yes", "Auto-confirm the 'Continue with LLM analysis?' prompt. Useful in scripts that want the full audit non-interactively. CI/non-TTY paths already auto-confirm without this flag.")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
@@ -402,6 +403,7 @@ export function registerMeta(program, { pkgVersion }) {
           noAiSlop: flags.aiSlop === false,
           reportFile: flags.reportFile || null,
           deterministicOnly: Boolean(flags.deterministicOnly),
+          security: Boolean(flags.security),
           yes: Boolean(flags.yes),
           trend: Boolean(flags.trend),
         });

package/src/commands/audit.js

@@ -237,7 +237,10 @@ function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHar
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, noAiSlop = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, noAiSlop = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null, security = false }) {
+  // KJC-TSK-0695: --security = the focused pass an agent self-invokes.
+  // Deterministic by definition (zero tokens) and skips non-security stages.
+  if (security) { deterministicOnly = true; noHarness = true; noAiSlop = true; }
   // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
   // dimension. It scores any third-party repo for AI-agent readability
   // (llms.txt presence, page token budgets, robots allowlist, etc.).
@@ -281,6 +284,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       noOsv,
       noSemgrep,
       noAiSlop,
+      ...(security ? { securityOnly: true } : {}),
     };
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);

package/src/commands/check.js

@@ -6,21 +6,26 @@
 
 import { checkHarden } from "../harden/check.js";
 import { collectMethodStats, formatMethodStats } from "../checks/method.js";
+import { checkAiSurface, formatAiSurface } from "../checks/ai-surface.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
   const result = await checkHarden({ projectDir, profile });
   // KJC-TSK-0689 (MG-D): method adherence is VISIBILITY, not a gate — it
   // rides along in check output but never affects the exit code.
   const method = await collectMethodStats({ projectDir }).catch(() => null);
+  // KJC-TSK-0694: same deal for the MCP inventory — a nudge, never a gate.
+  let aiSurface = null;
+  try { aiSurface = checkAiSurface({ projectDir }); } catch { /* inventory is best-effort */ }
 
   if (json) {
-    logger.info?.(JSON.stringify({ ...result, method }));
+    logger.info?.(JSON.stringify({ ...result, method, aiSurface }));
     return result.ok ? 0 : 1;
   }
 
   logger.info?.(`kj check (${profile})`);
   for (const c of result.checks) logger.info?.(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
   if (method) logger.info?.(`  method: ${formatMethodStats(method)}`);
+  if (aiSurface) logger.info?.(`  ${formatAiSurface(aiSurface)}`);
   if (!result.ok) logger.info?.("Harness drift detected — run `kj harden` to repair.");
   else logger.info?.("Harness OK.");
   return result.ok ? 0 : 1;

package/src/config/overrides.js

@@ -77,8 +77,11 @@ const UNDEF_CHECK_FLAGS = [
 ];
 
 function applyRoleOverrides(out, flags) {
+  // A provider override is always a string (`--security codex`). A bare
+  // boolean means the flag belongs to the command itself (`kj audit
+  // --security`, KJC-TSK-0695) and must not become a provider.
   for (const [flag, role] of ROLE_PROVIDER_FLAGS) {
-    if (flags[flag]) out.roles[role].provider = flags[flag];
+    if (typeof flags[flag] === "string" && flags[flag]) out.roles[role].provider = flags[flag];
   }
   // coder/reviewer also update top-level aliases
   if (flags.coder) out.coder = flags.coder;

package/src/environment/briefs.js

@@ -79,6 +79,7 @@ const B = {
       [
         "These findings are never overridable — not even by Solomon arbitration.",
         "PII is never logged; new dependencies need a reason and a pinned version.",
+        "Sensitive surface (auth, user input, secrets, network, deps)? Self-invoke `kj audit --security` — deterministic, zero tokens: prompt-injection over the agent-context files + OSV + Semgrep + Sonar — and remediate the findings before requesting review.",
       ],
       "findings with severity, category and file:line — or an explicit 'no security surface touched'."),
   },

package/src/environment/playbook.js

@@ -66,6 +66,8 @@ Invariants (the git gates enforce these — they are not suggestions):
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
 - Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
+  Task touches auth, user input, secrets, network or deps? Run
+  \`kj audit --security\` (zero tokens) and remediate BEFORE the review.
 - A design decision the card's AC don't cover belongs to the USER: record
   it as a proposed ADR (\`kj adr add\`) and ask — never bury it in a PR
   bullet. An oversized-diff warning is not an opinion either: partition,

package/src/roles/audit-role.js

@@ -48,13 +48,17 @@ export class AuditRole extends AgentRole {
    *   execute() would gather internally)
    */
   async collectDeterministic(input) {
+    // KJC-TSK-0695: securityOnly = the focused pass an agent self-invokes
+    // when a task touches sensitive surface. Only the security collectors
+    // run (sonar, osv, semgrep, injection) — zero tokens, fast.
+    const securityOnly = typeof input === "object" ? Boolean(input?.securityOnly) : false;
     const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
     const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
     const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
-    const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
-    const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
+    const noMadge = (typeof input === "object" ? Boolean(input?.noMadge) : false) || securityOnly;
+    const noKnip = (typeof input === "object" ? Boolean(input?.noKnip) : false) || securityOnly;
     const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
-    const noAiSlop = typeof input === "object" ? Boolean(input?.noAiSlop) : false;
+    const noAiSlop = (typeof input === "object" ? Boolean(input?.noAiSlop) : false) || securityOnly;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -67,11 +71,13 @@ export class AuditRole extends AgentRole {
     let deadExports = null;
     let injectionFindings = null;
     let aiSlop = null;
-    try {
-      basalCost = await measureBasalCost(projectDir);
-      const previous = await loadPreviousAudit(projectDir);
-      growthDelta = computeGrowthDelta(basalCost, previous);
-    } catch { /* basal cost is best-effort */ }
+    if (!securityOnly) {
+      try {
+        basalCost = await measureBasalCost(projectDir);
+        const previous = await loadPreviousAudit(projectDir);
+        growthDelta = computeGrowthDelta(basalCost, previous);
+      } catch { /* basal cost is best-effort */ }
+    }
     try {
       stack = await detectProjectStack(projectDir);
     } catch { /* stack detect is best-effort */ }
@@ -80,9 +86,11 @@ export class AuditRole extends AgentRole {
         sonarFindings = await collectSonarFindings(this.config, this.logger);
       } catch { /* sonar fetch is best-effort */ }
     }
-    try {
-      webperf = collectWebPerfInput(stack, this.config);
-    } catch { /* webperf input is best-effort */ }
+    if (!securityOnly) {
+      try {
+        webperf = collectWebPerfInput(stack, this.config);
+      } catch { /* webperf input is best-effort */ }
+    }
     // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
     // osv-scanner binary returns available:false and the audit
     // continues without the section.

package/src/utils/role-env.js

@@ -0,0 +1,57 @@
+/**
+ * role-env — env allowlist for agent subprocesses (KJC-TSK-0693).
+ *
+ * Agents inherit only what their function requires: system essentials, the
+ * spawned CLI's own auth/config vars, and KJ_* lane vars. Long-lived secrets
+ * that no agent needs (cloud keys, registry tokens, DB URLs) never reach the
+ * child, so a compromised agent or an injected prompt cannot exfiltrate them.
+ * Escapes: `security.env_passthrough` (exact names or trailing-* globs) and
+ * `security.env_allowlist: false` to disable filtering entirely.
+ */
+
+const EXACT = new Set([
+  "PATH", "Path", "HOME", "USER", "LOGNAME", "SHELL", "TERM", "COLORTERM", "LANG",
+  "TZ", "TMPDIR", "TMP", "TEMP", "EDITOR", "CI", "OLLAMA_HOST",
+  // Windows child-process essentials: executable resolution and profile dirs.
+  "SystemRoot", "SYSTEMROOT", "windir", "COMSPEC", "ComSpec", "PATHEXT",
+  "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA", "PROGRAMDATA",
+  // SSH agent socket: local-only handle, needed for git fetch/pull over SSH
+  // inside worktrees. Unusable off-machine, unlike a long-lived token.
+  "SSH_AUTH_SOCK", "SSH_AGENT_PID",
+  "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy",
+]);
+
+// Per-CLI auth/config families. GOOGLE_ covers GOOGLE_APPLICATION_CREDENTIALS
+// (gemini via Vertex); npm_ covers npm_config_* that Node tooling reads.
+const PREFIXES = [
+  "LC_", "XDG_", "KJ_", "NODE_", "npm_",
+  "ANTHROPIC_", "CLAUDE", "OPENAI_", "CODEX", "GEMINI", "GOOGLE_",
+  "QWEN", "DASHSCOPE_", "OPENCODE", "AIDER_", "OPENROUTER_",
+];
+
+// Vars only ONE agent authenticates with — granting them globally would
+// defeat the point (the coder does not need your GitHub token; copilot does).
+const AGENT_EXTRAS = {
+  copilot: ["GITHUB_", "GH_"],
+};
+
+const matches = (pattern, key) =>
+  pattern.endsWith("*") ? key.startsWith(pattern.slice(0, -1)) : key === pattern;
+
+/**
+ * Filter an environment down to what the given agent's subprocess needs.
+ * @param {Record<string,string|undefined>} base - env to filter
+ * @param {{agent?: string|null, passthrough?: string[]}} [opts]
+ * @returns {Record<string,string|undefined>}
+ */
+export function buildAgentEnv(base = process.env, { agent = null, passthrough = [] } = {}) {
+  const prefixes = [...PREFIXES, ...(AGENT_EXTRAS[agent] || [])];
+  const out = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (EXACT.has(key) || prefixes.some((p) => key.startsWith(p)) || passthrough.some((p) => matches(p, key))) {
+      out[key] = value;
+    }
+  }
+  return out;
+}