karajan-code 2.7.4 → 2.9.0

package/src/hu/acceptance-runner.js

@@ -37,35 +37,77 @@ async function runSingleTest(cmd, cwd, timeoutMs = 30000) {
 
 /**
  * Run all acceptance tests for an HU.
- * @param {string[]} tests - Array of shell commands
+ *
+ * Accepts two shapes:
+ *   - Legacy: plain string shell command.
+ *   - v2.7.5: { type: "shell" | "gherkin", content, file? }
+ *
+ * Shell entries execute immediately (exit code 0 = pass). Gherkin entries
+ * cannot be executed directly — that's Phase 3 of tests-first where the
+ * tester role translates them into real code tests. Until then, we report
+ * them as "pending" and skip rather than failing the whole gate.
+ *
+ * @param {Array<string|object>} tests - Array of shell commands OR structured entries
  * @param {string} cwd - Working directory
- * @returns {Promise<{allPassed: boolean, results: object[], summary: string, diagnostics: string|null}>}
+ * @returns {Promise<{allPassed: boolean, results: object[], summary: string, diagnostics: string|null, pending: number}>}
  */
 export async function runAcceptanceTests(tests, cwd) {
   if (!tests || tests.length === 0) {
-    return { allPassed: false, results: [], summary: "No acceptance tests defined", diagnostics: null };
+    return { allPassed: false, results: [], summary: "No acceptance tests defined", diagnostics: null, pending: 0 };
   }
 
   const results = [];
-  for (const cmd of tests) {
+  let pending = 0;
+  for (const entry of tests) {
+    let type = "shell";
+    let cmd;
+    if (typeof entry === "string") {
+      cmd = entry;
+    } else if (entry && typeof entry === "object" && typeof entry.content === "string") {
+      type = entry.type === "gherkin" ? "gherkin" : "shell";
+      cmd = entry.content;
+    } else {
+      results.push({ cmd: JSON.stringify(entry), passed: false, output: "Malformed acceptance_test entry", exitCode: -2, type: "invalid" });
+      continue;
+    }
+    if (type === "gherkin") {
+      // Gherkin entries need a translator (Phase 3). Mark them pending
+      // so the coder/tester sees they haven't been validated yet —
+      // better than silently passing (would lie) or hard-failing
+      // (would block the whole pipeline).
+      pending += 1;
+      results.push({
+        cmd,
+        passed: false,
+        output: "Gherkin test not yet executable (awaits tester translation — Phase 3)",
+        exitCode: 0,
+        type: "gherkin",
+        pending: true,
+      });
+      continue;
+    }
     const result = await runSingleTest(cmd, cwd);
-    results.push(result);
+    results.push({ ...result, type: "shell" });
   }
 
-  const passed = results.filter(r => r.passed);
-  const failed = results.filter(r => !r.passed);
+  const executedResults = results.filter((r) => !r.pending);
+  const passed = executedResults.filter((r) => r.passed);
+  const failed = executedResults.filter((r) => !r.passed);
   const allPassed = failed.length === 0;
 
-  const summary = `${passed.length}/${results.length} acceptance tests passed`;
+  const shellSummary = `${passed.length}/${executedResults.length} shell tests passed`;
+  const summary = pending > 0
+    ? `${shellSummary}, ${pending} gherkin test(s) pending translation`
+    : shellSummary;
 
   let diagnostics = null;
   if (!allPassed) {
-    diagnostics = failed.map(f =>
+    diagnostics = failed.map((f) =>
       `FAIL: ${f.cmd}\n  exit=${f.exitCode}\n  output: ${f.output.trim().split("\n").slice(-5).join("\n  ")}`
     ).join("\n\n");
   }
 
-  return { allPassed, results, summary, diagnostics };
+  return { allPassed, results, summary, diagnostics, pending };
 }
 
 /**

package/src/hu/store.js

@@ -80,12 +80,23 @@ export async function loadHuBatch(sessionId) {
 
 /**
  * Save a batch back to disk.
+ *
+ * Ensures the target directory exists before writing — the previous
+ * implementation assumed createHuBatch had already done the mkdir,
+ * which holds for the auto-HU path but NOT for plan-driven runs:
+ * `kj run --plan <id>` derives a batchSessionId from the plan id,
+ * loads the (non-existent) batch.json, falls back to in-memory, then
+ * crashes here with ENOENT on the first save attempt because no one
+ * created `~/.karajan/hu-stories/<sessionId>/`. The fix is one
+ * mkdir -p; cheap and idempotent.
+ *
  * @param {string} sessionId - The session identifier.
  * @param {object} batch - The batch object to persist.
  * @returns {Promise<void>}
  */
 export async function saveHuBatch(sessionId, batch) {
   const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
   batch.updated_at = new Date().toISOString();
   await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
 }

package/src/mcp/handlers/direct-handlers.js

@@ -3,7 +3,6 @@
  * Extracted from server-handlers.js for maintainability.
  */
 
-import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
 import { resolveRole } from "../../config.js";
 import { createLogger } from "../../utils/logger.js";
@@ -28,6 +27,7 @@ import {
   assertNotOnBaseBranch,
   buildConfig,
   buildDirectEmitter,
+  ensureTaskFromFile,
 } from "../shared-helpers.js";
 
 /**
@@ -56,7 +56,6 @@ export async function handlePlanDirect(a, server, extra) {
   await assertAgentsAvailable([plannerRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
-  const { ensureTaskFromFile } = await import("../shared-helpers.js");
   await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
@@ -154,7 +153,7 @@ export async function handlePlanDirect(a, server, extra) {
   sendTrackerLog(server, "planner", "running", plannerRole.provider);
   runLog.logText(`[planner] agent launched, waiting for response...`);
   let result;
-  let plannerStats = null;
+  let plannerStats;
   try {
     result = await planner.runTask({
       prompt,
@@ -212,7 +211,6 @@ export async function handleCodeDirect(a, server, extra) {
   await assertAgentsAvailable([coderRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
-  const { ensureTaskFromFile } = await import("../shared-helpers.js");
   await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
@@ -265,7 +263,6 @@ export async function handleReviewDirect(a, server, extra) {
   await assertAgentsAvailable([reviewerRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
-  const { ensureTaskFromFile } = await import("../shared-helpers.js");
   await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);

package/src/mcp/handlers/management-handlers.js

@@ -6,7 +6,7 @@
 import { runKjCommand } from "../run-kj.js";
 import { loadConfig } from "../../config.js";
 import { readRunLog } from "../../utils/run-log.js";
-import { isPreflightAcked, ackPreflight, getSessionOverrides } from "../preflight.js";
+import { ackPreflight, getSessionOverrides } from "../preflight.js";
 import { ensureBootstrap } from "../../bootstrap.js";
 import {
   resolveProjectDir,
@@ -15,7 +15,7 @@ import {
   buildConfig,
 } from "../shared-helpers.js";
 import { buildDashboardJson } from "../../utils/status-dashboard.js";
-import { loadMostRecentSession } from "../../session-store.js";
+import { loadMostRecentSession } from "../../session/store.js";
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
 
@@ -177,8 +177,8 @@ export async function handleScan(a, server) {
 
 export async function handleBoard(a) {
   const action = a.action || "status";
-  const { loadConfig: lc } = await import("../../config.js");
-  const { config } = await lc();
+  // TSK-0340: loadConfig is already statically imported at the top.
+  const { config } = await loadConfig();
   const port = a.port || config.hu_board?.port || 4000;
   const { startBoard, stopBoard, boardStatus } = await import("../../commands/board.js");
   switch (action) {
@@ -201,6 +201,50 @@ export async function handleUndo(a, server) {
   }
 }
 
+/**
+ * Garbage-collect stale Karajan state. Routed here (not through the
+ * generic `runKjCommand`) because the user needs a structured result
+ * payload: MCP clients (Claude Desktop, Cursor, …) render lists, not
+ * ANSI-styled stdout. Shared implementation lives in
+ * `src/utils/garbage-collector.js` so CLI and MCP stay in sync.
+ */
+export async function handleClean(a) {
+  const { runManualGC, nukeBoardDb, summarizeGC } = await import("../../utils/garbage-collector.js");
+
+  const dryRun = !a?.yes;
+  const retention = a?.nuke
+    ? { planRetentionDays: 0, draftRetentionDays: 0, sessionRetentionDays: 0, huRetentionDays: 0 }
+    : {
+      planRetentionDays: a?.planDays,
+      draftRetentionDays: a?.draftDays,
+      sessionRetentionDays: a?.sessionDays,
+      huRetentionDays: a?.huDays,
+    };
+
+  const result = await runManualGC({ ...retention, dryRun });
+  if (a?.nuke) {
+    const boardResult = await nukeBoardDb({ dryRun });
+    result.removed.push(...boardResult.removed);
+    result.bytesFreed += boardResult.bytesFreed;
+    result.errors.push(...boardResult.errors);
+  }
+
+  const byKind = {};
+  for (const r of result.removed) byKind[r.kind] = (byKind[r.kind] || 0) + 1;
+
+  return {
+    ok: true,
+    dryRun,
+    nuke: Boolean(a?.nuke),
+    removed: result.removed.length,
+    bytesFreed: result.bytesFreed,
+    breakdown: byKind,
+    items: result.removed.map((r) => ({ path: r.path, kind: r.kind, reason: r.reason })),
+    errors: result.errors,
+    summary: summarizeGC(result) || "[clean] nothing to clean — ~/.kj/ and ~/.karajan/ are tidy.",
+  };
+}
+
 export async function buildPreflightRequiredResponse(toolName) {
   const { config } = await loadConfig();
   const { listAgents } = await import("../../commands/agents.js");

package/src/mcp/handlers/run-handler.js

@@ -5,7 +5,7 @@
 
 import { EventEmitter } from "node:events";
 import { runFlow, resumeFlow } from "../../orchestrator.js";
-import { loadConfig, applyRunOverrides, validateConfig, resolveRole } from "../../config.js";
+import { loadConfig, resolveRole } from "../../config.js";
 import { createLogger } from "../../utils/logger.js";
 import { assertAgentsAvailable } from "../../agents/availability.js";
 import { validatePolicyCompliance } from "../../guards/policy-guard.js";
@@ -21,7 +21,7 @@ import {
   assertNotOnBaseBranch,
   buildConfig,
   buildAskQuestion,
-  enrichedFailPayload,
+  ensureTaskFromFile,
 } from "../shared-helpers.js";
 
 const MAX_AUTO_RESUMES = 2;
@@ -34,7 +34,7 @@ async function attemptAutoResume({ err, config, logger, emitter, askQuestion, ru
   if (NON_RECOVERABLE_CATEGORIES.has(category)) return null;
 
   // Find session ID from most recent session file
-  const { loadMostRecentSession } = await import("../../session-store.js");
+  const { loadMostRecentSession } = await import("../../session/store.js");
   let session;
   try {
     session = await loadMostRecentSession();
@@ -60,8 +60,9 @@ async function attemptAutoResume({ err, config, logger, emitter, askQuestion, ru
   });
 
   // Increment counter and save before resuming
-  const { saveSession } = await import("../../session-store.js");
-  session.auto_resume_count = autoResumeCount + 1;
+  const { saveSession } = await import("../../session/store.js");
+  const { setRetryCount } = await import("../../session/mutators.js");
+  setRetryCount(session, "auto_resume", autoResumeCount + 1);
   await saveSession(session);
 
   try {
@@ -251,7 +252,7 @@ export async function handleResume(a, server, extra) {
     // Load session to get pause context for policy-aware validation
     let pauseContext;
     try {
-      const { loadSession } = await import("../../session-store.js");
+      const { loadSession } = await import("../../session/store.js");
       const session = await loadSession(a.sessionId);
       const ctx = session?.paused_state?.context;
       pauseContext = typeof ctx === "string" ? ctx : ctx?.reason;
@@ -267,9 +268,9 @@ export async function handleResume(a, server, extra) {
 }
 
 export async function handleRun(a, server, extra) {
-  const { ensureTaskFromFile, resolveProjectDir: _rpd } = await import("../shared-helpers.js");
+  // TSK-0340: was `await import(...)` — both helpers now come from the static import block.
   try {
-    await ensureTaskFromFile(a, a.projectDir || (await _rpd(server, a.projectDir).catch(() => null)));
+    await ensureTaskFromFile(a, a.projectDir || (await resolveProjectDir(server, a.projectDir).catch(() => null)));
   } catch (err) {
     return failPayload(`taskFile read failed: ${err.message}`);
   }

package/src/mcp/preflight.js

@@ -1,9 +1,28 @@
 /**
- * Session-scoped preflight state.
- * Lives in memory — dies when the MCP server restarts.
+ * MCP-scoped preflight state (handshake flag + session overrides facade).
+ *
+ * Two pieces of state:
+ *   - `preflightAcked`: whether the user/host has completed the
+ *     `kj_preflight` handshake in the current MCP session. Stays local
+ *     because it is strictly MCP-protocol state (no CLI equivalent).
+ *   - Session overrides: since v2.7.5 these live in
+ *     `src/session/runtime-overrides.js` — a neutral module that both
+ *     CLI commands and MCP handlers can depend on without creating a
+ *     layer violation. This file re-exports the same functions under
+ *     their historical names for back-compat with existing MCP handlers.
+ *
+ * CLI code must NOT import from this file — it should go straight to
+ * `src/session/runtime-overrides.js`. Enforced by
+ * `tests/architecture/layer-boundaries.test.js`.
  */
+
+import {
+  getRuntimeOverrides,
+  setRuntimeOverride,
+  clearRuntimeOverrides,
+} from "../session/runtime-overrides.js";
+
 let preflightAcked = false;
-let sessionOverrides = {};
 
 export function isPreflightAcked() {
   return preflightAcked;
@@ -11,18 +30,18 @@ export function isPreflightAcked() {
 
 export function ackPreflight(overrides = {}) {
   preflightAcked = true;
-  sessionOverrides = { ...overrides };
-}
-
-export function getSessionOverrides() {
-  return { ...sessionOverrides };
-}
-
-export function setSessionOverride(key, value) {
-  sessionOverrides[key] = value;
+  clearRuntimeOverrides();
+  for (const [k, v] of Object.entries(overrides || {})) {
+    setRuntimeOverride(k, v);
+  }
 }
 
 export function resetPreflight() {
   preflightAcked = false;
-  sessionOverrides = {};
+  clearRuntimeOverrides();
 }
+
+// Back-compat aliases for MCP handlers that still import these names.
+// New code should import from `src/session/runtime-overrides.js` directly.
+export const getSessionOverrides = getRuntimeOverrides;
+export const setSessionOverride = setRuntimeOverride;

package/src/mcp/server-handlers.js

@@ -22,7 +22,7 @@ export {
 // ── Sub-module re-exports ────────────────────────────────────────────
 export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
 export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
-export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, handleClean, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
 export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
 // ── Handler dispatch ─────────────────────────────────────────────────
@@ -36,7 +36,7 @@ import {
 import {
   handleStatus, handleAgents, handlePreflight, handleRoles,
   handleReport, handleInit, handleDoctor, handleConfig,
-  handleScan, handleBoard, handleUndo
+  handleScan, handleBoard, handleUndo, handleClean
 } from "./handlers/management-handlers.js";
 import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
@@ -66,7 +66,8 @@ export async function handleToolCall(name, args, server, extra) {
     kj_hu:          (a, server) => handleHu(a, server),
     kj_suggest:     (a) => handleSuggest(a),
     kj_skills:      (a) => handleSkills(a),
-    kj_undo:        (a, server) => handleUndo(a, server)
+    kj_undo:        (a, server) => handleUndo(a, server),
+    kj_clean:       (a) => handleClean(a),
   }[name];
   if (handler) {
     return handler(a, server, extra);

package/src/mcp/suggest-handler.js

@@ -6,6 +6,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getSessionRoot } from "../utils/paths.js";
+import { setSuggestions, touch } from "../session/mutators.js";
 
 /**
  * Find the most recent running session for a given projectDir.
@@ -65,7 +66,7 @@ export async function handleSuggestion({ suggestion, context, projectDir }) {
 
   // Initialize suggestions array if not present
   if (!Array.isArray(session.suggestions)) {
-    session.suggestions = [];
+    setSuggestions(session, []);
   }
 
   const entry = {
@@ -79,7 +80,7 @@ export async function handleSuggestion({ suggestion, context, projectDir }) {
   // Persist the updated session
   const sessionRoot = getSessionRoot();
   const sessionFile = path.join(sessionRoot, session.id, "session.json");
-  session.updated_at = new Date().toISOString();
+  touch(session);
   await fs.writeFile(sessionFile, JSON.stringify(session, null, 2), "utf8");
 
   return {

package/src/mcp/tools.js

@@ -385,5 +385,20 @@ export const tools = [
         projectDir: { type: "string", description: "Absolute path to the project directory" }
       }
     }
+  },
+  {
+    name: "kj_clean",
+    description: "Garbage-collect stale Karajan state: orphan plans (project dir no longer exists), finalised plans/sessions past their retention window, and HU story batches. Dry-run by default; pass yes=true to actually delete. Use nuke=true to wipe everything (retention=0 on every bucket + drop the HU board SQLite DB).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        yes: { type: "boolean", description: "If true, actually delete. Default false (dry-run: returns the list of items that would be removed without touching disk)." },
+        nuke: { type: "boolean", description: "If true, retention=0 on every bucket + wipe the HU board DB (stops the board first if running). The \"I want it all gone right now\" button." },
+        planDays: { type: "number", description: "Keep finalised plans (approved/rejected/executed) for this many days. Default: 30." },
+        draftDays: { type: "number", description: "Keep draft plans for this many days. Default: 60." },
+        sessionDays: { type: "number", description: "Keep finalised sessions for this many days. Default: 7." },
+        huDays: { type: "number", description: "Keep HU story batches for this many days. Default: 14." }
+      }
+    }
   }
 ];

package/src/orchestrator/agent-fallback.js

@@ -1,5 +1,5 @@
 import { createAgent } from "../agents/index.js";
-import { addCheckpoint } from "../session-store.js";
+import { addCheckpoint } from "../session/store.js";
 import { detectRateLimit } from "../utils/rate-limit-detector.js";
 
 /**

package/src/orchestrator/ci-integration.js

@@ -2,11 +2,13 @@
  * CI/CD integration — early PR creation, incremental push, review dispatch.
  * Extracted from orchestrator.js — self-contained feature, only active when ci.enabled.
  */
-import { saveSession } from "../session-store.js";
+import { saveSession } from "../session/store.js";
+import { setCiEarlyPr, appendCiCommits } from "../session/mutators.js";
 import { earlyPrCreation, incrementalPush } from "../git/automation.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
+import { getIntegration } from "./integrations.js";
 
-export async function tryCiComment({ config, session, logger, agent, body }) {
+export async function tryCiComment({ config, session, logger: _logger, agent, body }) {
   if (!config.ci?.enabled || !session.ci_pr_number) return;
   try {
     const { dispatchComment } = await import("../ci/dispatch.js");
@@ -29,10 +31,10 @@ async function ciIncrementalPush({ config, session, gitCtx, task, logger, repo,
   const pushResult = await incrementalPush({ gitCtx, task, logger, session });
   if (!pushResult) return;
 
-  const { accumulateCommit } = await import("../planning-game/pipeline-adapter.js");
-  for (const c of pushResult.commits) accumulateCommit(session, c);
+  const tracker = getIntegration("tracker");
+  for (const c of pushResult.commits) tracker?.onCommit?.(session, c);
 
-  session.ci_commits = [...(session.ci_commits ?? []), ...pushResult.commits];
+  appendCiCommits(session, pushResult.commits);
   await saveSession(session);
 
   if (!repo) return;
@@ -48,12 +50,10 @@ async function ciCreateEarlyPr({ config, session, emitter, eventBase, gitCtx, ta
   const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
   if (!earlyPr) return;
 
-  const { accumulateCommit } = await import("../planning-game/pipeline-adapter.js");
-  for (const c of earlyPr.commits) accumulateCommit(session, c);
+  const tracker = getIntegration("tracker");
+  for (const c of earlyPr.commits) tracker?.onCommit?.(session, c);
 
-  session.ci_pr_number = earlyPr.prNumber;
-  session.ci_pr_url = earlyPr.prUrl;
-  session.ci_commits = earlyPr.commits;
+  setCiEarlyPr(session, { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl, commits: earlyPr.commits });
   await saveSession(session);
   emitProgress(emitter, makeEvent("ci:pr-created", { ...eventBase, stage: "ci" }, {
     message: `Early PR created: #${earlyPr.prNumber}`,
@@ -86,7 +86,7 @@ export async function handleCiEarlyPrOrPush({ ciEnabled, config, session, emitte
   }
 }
 
-export function formatBlockingIssues(issues) {
+function formatBlockingIssues(issues) {
   return issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
 }
 

package/src/orchestrator/config-init.js

@@ -4,7 +4,7 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
-import { computeBaseRef } from "../review/diff-generator.js";
+import { computeBaseRef, setSnapshot } from "../review/diff-generator.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
@@ -12,9 +12,11 @@ import { emitProgress, makeEvent } from "../utils/events.js";
 import { BudgetTracker, extractUsageMetrics } from "../utils/budget.js";
 import { computeKjComparison } from "../budget/comparison.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
+import { projectSlug } from "../plan/plan-store.js";
 import { applyPolicies } from "../guards/policy-resolver.js";
 import { resolveReviewProfile } from "../review/profiles.js";
-import { createSession } from "../session-store.js";
+import { createSession } from "../session/store.js";
+import { setResolvedPolicies } from "../session/mutators.js";
 import { exists, ensureDir } from "../utils/fs.js";
 
 /**
@@ -26,10 +28,13 @@ export async function autoInit(projectDir, logger) {
   // Ensure git repo exists — without git, diff/reviewer/commit won't work
   const gitDir = path.join(projectDir, ".git");
   if (!(await exists(gitDir))) {
-    const { execSync } = await import("node:child_process");
+    // Audit follow-up: was execSync with constant strings. Inputs are
+    // hardcoded, so injection isn't possible, but the project standard
+    // since #555 is execFileSync everywhere. Migrated for consistency.
+    const { execFileSync } = await import("node:child_process");
     try {
-      execSync("git init", { cwd: projectDir, stdio: "pipe" });
-      execSync("git commit --allow-empty -m 'initial commit'", { cwd: projectDir, stdio: "pipe" });
+      execFileSync("git", ["init"], { cwd: projectDir, stdio: "pipe" });
+      execFileSync("git", ["commit", "--allow-empty", "-m", "initial commit"], { cwd: projectDir, stdio: "pipe" });
       logger.info("Initialized git repository with empty initial commit");
     } catch (err) {
       logger.warn(`Failed to init git repo: ${err.message}`);
@@ -342,14 +347,27 @@ export async function initializeSession({ task, config, flags, pgTaskId, pgProje
   const baseRef = await computeBaseRef({ baseBranch: config.base_branch, baseRef: flags.baseRef || null });
 
   if (baseRef === "__snapshot__") {
+    // TSK-0340: `setSnapshot` now static; `takeSnapshot` kept dynamic because
+    // snapshot-diff is ~600 LOC of dependency-free fs walking that most
+    // runs don't need (only the greenfield/no-git path reaches here).
     const { takeSnapshot } = await import("../review/snapshot-diff.js");
-    const { setSnapshot } = await import("../review/diff-generator.js");
     const snapshot = await takeSnapshot(config.projectDir || process.cwd());
     setSnapshot(snapshot);
   }
 
+  // PR-F: stamp project_id on every session derived from the project
+  // directory (slug = same algorithm the board uses to bucket plans).
+  // Without this, sessions created by `kj run` from a terminal land
+  // on disk with `project_id: null`. The board sync sees an orphan
+  // and (used to) promote it to a phantom "Orphan sessions" project.
+  // Now that PR-B blocks orphans on the board side, we must also fix
+  // the source so the session can attach to a real project.
+  const projectDir = config.projectDir || process.cwd();
+  const project_id = projectSlug(projectDir);
+
   const sessionInit = {
     task,
+    project_id,
     config_snapshot: config,
     base_ref: baseRef,
     session_start_sha: baseRef,
@@ -422,7 +440,7 @@ export function resolvePipelinePolicies({ flags, config, stageResults, emitter,
     taskType: flags.taskType || config.taskType || stageResults.triage?.taskType || stageResults.intent?.taskType || null,
     policies: config.policies,
   });
-  session.resolved_policies = resolvedPolicies;
+  setResolvedPolicies(session, resolvedPolicies);
 
   let updatedConfig = config;
   if (!resolvedPolicies.tdd) {

package/src/orchestrator/direct-actions.js

@@ -1,7 +1,7 @@
 // Direct actions: commands Karajan Brain can execute without invoking a full role.
 // Keeps the action catalog small, auditable, and safe.
 
-import { execSync, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -48,7 +48,11 @@ async function runCommand({ cmd, cwd }) {
   }
 
   try {
-    const output = execSync(cmd, {
+    // Audit follow-up: was using execSync, which routes through /bin/sh.
+    // Even though `cmd` is allow-listed, defense-in-depth: switched to
+    // execFileSync with a tokenised arg array so no shell expansion at all.
+    const [program, ...args] = cmd.trim().split(/\s+/);
+    const output = execFileSync(program, args, {
       cwd: cwd || process.cwd(),
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -186,4 +190,4 @@ export function getAllowedActionTypes() {
   return Object.keys(ACTION_HANDLERS);
 }
 
-export { ALLOWED_COMMANDS, isCommandAllowed };
+export { isCommandAllowed };