@karajan-family/code 4.21.0

package/src/types/config.js

@@ -0,0 +1,114 @@
+/**
+ * Karajan configuration typedefs. Mirrors the shape produced by loadConfig()
+ * and consumed throughout the orchestrator. Optional fields are intentional
+ * — users may set them in kj.config.yml without every field being required.
+ */
+
+/**
+ * @typedef {Object} RoleConfig
+ * @property {string} [provider]    - claude | codex | gemini | opencode | aider | anthropic | openai | google
+ * @property {string} [model]       - provider-specific model identifier
+ */
+
+/**
+ * @typedef {Object} PipelineToggle
+ * @property {boolean} [enabled]
+ */
+
+/**
+ * @typedef {Object} PipelineFlags
+ * @property {boolean} [coderEnabled]
+ * @property {boolean} [reviewerEnabled]
+ * @property {boolean} [plannerEnabled]
+ * @property {boolean} [researcherEnabled]
+ * @property {boolean} [architectEnabled]
+ * @property {boolean} [refactorerEnabled]
+ * @property {boolean} [testerEnabled]
+ * @property {boolean} [securityEnabled]
+ * @property {boolean} [impeccableEnabled]
+ * @property {boolean} [triageEnabled]
+ * @property {boolean} [discoverEnabled]
+ * @property {boolean} [huReviewerEnabled]
+ * @property {boolean} [coderRequired]
+ */
+
+/**
+ * @typedef {Object} GitConfig
+ * @property {boolean} [auto_commit]
+ * @property {boolean} [auto_push]
+ * @property {boolean} [auto_pr]
+ * @property {boolean} [auto_rebase]
+ * @property {string} [branch_prefix]
+ */
+
+/**
+ * @typedef {Object} SonarConfig
+ * @property {boolean} [enabled]
+ * @property {string} [host]
+ * @property {string} [token]
+ * @property {boolean} [external]
+ * @property {string} [enforcement_profile]
+ */
+
+/**
+ * @typedef {Object} BudgetConfig
+ * @property {Object} [pricing]
+ * @property {number} [warn_threshold_pct]
+ */
+
+/**
+ * @typedef {Object} BrainDecisorConfig
+ * @property {boolean} [enabled]
+ * @property {number} [maxDecisions]
+ */
+
+/**
+ * @typedef {Object} BrainConfig
+ * @property {boolean} [enabled]
+ * @property {string} [provider]
+ * @property {boolean} [bypass_solomon_on_correctness]
+ * @property {number} [max_consecutive_verification_failures]
+ * @property {BrainDecisorConfig} [decisor]
+ */
+
+/**
+ * @typedef {Object} SkillsConfig
+ * @property {boolean} [enabled]
+ * @property {"auto"|"regex"|"semantic"|"none"} [mode]
+ */
+
+/**
+ * @typedef {Object} PreflightConfig
+ * @property {boolean} [extended]
+ */
+
+/**
+ * Full Karajan configuration shape as resolved by loadConfig() +
+ * applyRunOverrides(). Not every field is always present; consumers should
+ * defensively read via `config.x?.y`.
+ *
+ * @typedef {Object} KarajanConfig
+ * @property {string} [coder]                   - legacy agent name (claude, codex, ...)
+ * @property {string} [reviewer]                - legacy agent name
+ * @property {Object.<string, RoleConfig>} [roles]
+ * @property {Object.<string, PipelineToggle>} [pipeline]
+ * @property {string} [review_mode]             - standard | strict | paranoid | relaxed
+ * @property {string} [review_rules]            - path to review rules .md
+ * @property {number} [max_iterations]
+ * @property {number} [max_budget_usd]
+ * @property {BudgetConfig} [budget]
+ * @property {SonarConfig} [sonarqube]
+ * @property {GitConfig} [git]
+ * @property {string} [base_branch]
+ * @property {Object} [session]                 - timeouts etc
+ * @property {Object} [output]                  - log level, report dir
+ * @property {Object} [development]             - methodology, require_test_changes
+ * @property {BrainConfig} [brain]
+ * @property {SkillsConfig} [skills]
+ * @property {PreflightConfig} [preflight]
+ * @property {string} [projectDir]              - absolute path, set at runtime
+ * @property {string} [productContext]          - runtime-loaded
+ * @property {string} [domainContext]           - runtime-loaded
+ */
+
+export {};

package/src/types/hu.js

@@ -0,0 +1,47 @@
+/**
+ * HU (Historia de Usuario) typedefs. An HU is a user story that the
+ * pipeline can decompose into, certify via hu-reviewer, then run as a
+ * sub-pipeline.
+ */
+
+/**
+ * @typedef {"pending"|"planned"|"in_progress"|"done"|"rejected"|"blocked"|"failed"} HUStatus
+ */
+
+/**
+ * @typedef {Object} HUAcceptanceCriterion
+ * @property {string} [given]
+ * @property {string} [when]
+ * @property {string} [then]
+ * @property {string} [raw]                     - plain-text AC if not Gherkin
+ */
+
+/**
+ * @typedef {Object} HUStory
+ * @property {string} id                        - stable slug per batch
+ * @property {string} title
+ * @property {string} [role]                    - "Como ..."
+ * @property {string} [goal]                    - "Quiero ..."
+ * @property {string} [benefit]                 - "Para ..."
+ * @property {HUAcceptanceCriterion[]} [acceptanceCriteria]
+ * @property {HUStatus} [status]
+ * @property {string} [assignee]
+ * @property {string[]} [dependencies]          - ids of HUs that must be done first
+ * @property {Object} [certification]           - hu-reviewer verdict
+ * @property {Object} [session]                 - sub-pipeline session metadata when it runs
+ */
+
+/**
+ * A batch is the ordered collection of HUs produced by the auto-generator
+ * or loaded from a YAML file.
+ *
+ * @typedef {Object} HUBatch
+ * @property {string} id                        - typically the parent sessionId
+ * @property {string} [task]                    - original task text
+ * @property {HUStory[]} stories
+ * @property {string} [created_at]
+ * @property {string} [updated_at]
+ * @property {Object} [board]                   - HU Board metadata (port, URL)
+ */
+
+export {};

package/src/types/index.js

@@ -0,0 +1,38 @@
+/**
+ * Central JSDoc typedef registry. Import typedefs via:
+ *
+ *   /** @typedef {import("../types/index.js").KarajanConfig} KarajanConfig *\/
+ *
+ * This module re-exports every type so consumers have a single import path.
+ * The actual typedef bodies live in the focused files under src/types/.
+ *
+ * Intentionally a runtime-empty module: it only carries JSDoc annotations,
+ * nothing to execute.
+ */
+
+/**
+ * @typedef {import("./config.js").KarajanConfig} KarajanConfig
+ * @typedef {import("./config.js").RoleConfig} RoleConfig
+ * @typedef {import("./config.js").PipelineFlags} PipelineFlags
+ *
+ * @typedef {import("./session.js").Session} Session
+ * @typedef {import("./session.js").Checkpoint} Checkpoint
+ *
+ * @typedef {import("./stage.js").StageContext} StageContext
+ * @typedef {import("./stage.js").StageResult} StageResult
+ *
+ * @typedef {import("./agent.js").AgentResult} AgentResult
+ * @typedef {import("./agent.js").AgentResponse} AgentResponse
+ *
+ * @typedef {import("./hu.js").HUStory} HUStory
+ * @typedef {import("./hu.js").HUBatch} HUBatch
+ *
+ * @typedef {import("./policy.js").ResolvedPolicies} ResolvedPolicies
+ * @typedef {import("./policy.js").QualityGateResult} QualityGateResult
+ *
+ * @typedef {import("./solomon.js").Conflict} SolomonConflict
+ * @typedef {import("./solomon.js").ConflictHistoryEntry} SolomonConflictHistoryEntry
+ * @typedef {import("./solomon.js").SolomonResult} SolomonResult
+ */
+
+export {};

package/src/types/policy.js

@@ -0,0 +1,43 @@
+/**
+ * Policy + quality-gate typedefs. Policies are resolved once per session
+ * from config + task type; quality gates are the outputs of each gate
+ * (sonar, perf, tests, review).
+ */
+
+/**
+ * @typedef {Object} ResolvedPolicies
+ * @property {boolean} [tdd]                    - whether TDD is enforced
+ * @property {boolean} [sonar]                  - Sonar gate enabled
+ * @property {boolean} [tests]                  - tester gate enabled
+ * @property {boolean} [security]               - security audit enabled
+ * @property {boolean} [reviewer]               - reviewer gate enabled
+ * @property {boolean} [planner]                - planner enabled
+ * @property {boolean} [researcher]             - researcher enabled
+ * @property {boolean} [architect]              - architect enabled
+ * @property {boolean} [refactorer]             - refactorer enabled
+ * @property {boolean} [impeccable]             - impeccable audit enabled
+ * @property {boolean} [triage]                 - triage enabled
+ * @property {boolean} [discover]               - discover phase enabled
+ * @property {boolean} [hu_reviewer]            - HU certification enabled
+ * @property {number} [reviewer_retries]
+ * @property {number} [tester_retries]
+ * @property {string} [reason]                  - why these policies (task type + config chain)
+ */
+
+/**
+ * Result of a quality gate evaluation — Sonar, perf, tester, reviewer, etc.
+ *
+ * @typedef {Object} QualityGateResult
+ * @property {boolean} ok                       - did the gate pass
+ * @property {"OK"|"FAIL"|"WARN"|"ERROR"} gateStatus
+ * @property {string} [summary]
+ * @property {Object[]} [blocking_issues]       - for reviewer/security gates
+ * @property {number} [openIssues]              - sonar
+ * @property {number} [issuesInitial]
+ * @property {number} [issuesFinal]
+ * @property {number} [issuesResolved]
+ * @property {string} [provider]                - which agent produced the verdict (when relevant)
+ * @property {Object} [details]                 - gate-specific payload
+ */
+
+export {};

package/src/types/session.js

@@ -0,0 +1,75 @@
+/**
+ * Session state typedefs. The session is a mutable object that accumulates
+ * state throughout a kj run and is persisted to ~/.karajan/sessions/<id>/.
+ */
+
+/**
+ * @typedef {Object} Checkpoint
+ * @property {string} [at]                   - ISO timestamp
+ * @property {string} [stage]
+ * @property {number} [iteration]
+ * @property {string} [conflictStage]
+ * @property {string} [ruling]
+ * @property {string} [alternativeAgent]
+ * @property {string} [waitUntil]
+ * @property {string[]} [conditions]
+ * @property {boolean} [escalate]
+ * @property {string} [error]
+ * @property {string|null} [subtask]
+ */
+
+/**
+ * @typedef {Object} SolomonRulingRecord
+ * @property {string} at                     - ISO timestamp
+ * @property {string} stage
+ * @property {string} trigger
+ * @property {Object} conflict
+ * @property {string} ruling                 - approve | approve_with_conditions | escalate_human | create_subtask | ...
+ * @property {string} [reasoning]
+ * @property {string[]} [conditions]
+ * @property {string|null} [alternativeAgent]
+ * @property {string} [result]
+ */
+
+/**
+ * @typedef {Object} BrainDecisionRecord
+ * @property {number} seq
+ * @property {string} at
+ * @property {string} intent                 - "<taskType>:<level>"
+ * @property {string[]} rolesOn
+ * @property {string} confidence             - low | medium | high
+ * @property {string} rationale
+ * @property {string[]} appliedOverrides
+ */
+
+/**
+ * @typedef {Object} RtkSavings
+ * @property {number} [callCount]
+ * @property {number} [estimatedTokensSaved]
+ * @property {number} [savedPct]
+ * @property {number} [originalBytes]
+ * @property {number} [rtkBytes]
+ */
+
+/**
+ * @typedef {Object} Session
+ * @property {string} id                     - session id
+ * @property {string} task                   - user's task text
+ * @property {"running"|"paused"|"approved"|"rejected"|"failed"} status
+ * @property {string} created_at             - ISO timestamp
+ * @property {string} updated_at
+ * @property {Checkpoint[]} [checkpoints]
+ * @property {SolomonRulingRecord[]} [solomonRulings]     - KJC-TSK-0287
+ * @property {BrainDecisionRecord[]} [brainDecisions]     - KJC-TSK-0322
+ * @property {string[]} [skillsRecommended]               - wouldHaveUsed when openskills missing
+ * @property {string[]} [autoInstalledSkills]
+ * @property {RtkSavings} [rtk_savings]
+ * @property {string} [session_start_sha]                 - baseline for `git diff`; may be the empty-tree SHA when no prior commits exist
+ * @property {string} [head_at_start]                     - actual HEAD when the run started; used by the post-loop journal to enumerate commits produced BY the run. Falls back to session_start_sha in zero-commits repos. (2026-05-07 dogfooding fix.)
+ * @property {string} [_journalDir]                       - runtime journal path
+ * @property {string[]} [_journalIterations]              - rendered iteration markdown
+ * @property {string[]} [_journalFiles]
+ * @property {Object} [budget]                            - final budget summary snapshot
+ */
+
+export {};

package/src/types/solomon.js

@@ -0,0 +1,87 @@
+/**
+ * Typedefs for Solomon — the AI judge consulted by Brain on genuine dilemmas.
+ *
+ * Architectural invariant (enforced by convention, see docs/ARCHITECTURE.md):
+ *   Solomon is **NEVER** invoked directly from stages, rules or roles.
+ *   The only legitimate entry points are:
+ *     - `src/brain/solomon-consult.js#consultSolomonForRouting`
+ *     - `src/orchestrator/solomon-escalation.js#invokeSolomon`
+ *   Both are called by Brain (or by the orchestrator on Brain's behalf).
+ *   The v2.3.0 audit fixed 21 violations where stages bypassed Brain and
+ *   called Solomon directly. Don't reintroduce that pattern.
+ *
+ * This module is runtime-empty — it only carries JSDoc annotations.
+ *
+ * @module types/solomon
+ */
+
+/**
+ * A single turn of feedback attributed to a pipeline agent. Used to build
+ * `Conflict.history` when Brain escalates a decision to Solomon.
+ *
+ * @typedef {Object} ConflictHistoryEntry
+ * @property {string} agent     - slug of the agent that produced the feedback
+ *                                (e.g. "reviewer", "sonar", "tester",
+ *                                "coder_rate_limit").
+ * @property {string} feedback  - raw textual feedback to be weighted by Solomon.
+ */
+
+/**
+ * The bundle of context Brain hands to Solomon when it cannot decide on its
+ * own. Solomon reads only this object + the stage + task; it never sees
+ * session internals beyond what is packed here.
+ *
+ * Historical shape: this matches the argument already used by
+ * `invokeSolomon({ ..., conflict })` — the typedef formalizes the contract
+ * so future drift is caught by `npm run typecheck`.
+ *
+ * @typedef {Object} Conflict
+ * @property {string} stage
+ *           Pipeline stage that triggered escalation (e.g. "reviewer",
+ *           "sonar", "tester", "init_error", "coder_rate_limit").
+ * @property {string} task
+ *           Original user task (denormalized so Solomon sees what the user
+ *           actually asked for, not just the stage context).
+ * @property {number} iterationCount
+ *           Current iteration number inside the escalating sub-loop.
+ * @property {number} maxIterations
+ *           Configured cap for that sub-loop (reviewer retries, tester
+ *           retries, full pipeline iterations, etc.). Hitting this cap is
+ *           the canonical trigger for Solomon consultation.
+ * @property {string|null} [cooldownUntil]
+ *           ISO timestamp for rate-limit / standby escalations. Null when
+ *           the conflict is not a rate-limit.
+ * @property {number|null} [cooldownMs]
+ *           Remaining cooldown in milliseconds. Null outside rate-limit
+ *           escalations.
+ * @property {ConflictHistoryEntry[]} history
+ *           Ordered list of agent feedback Solomon should weigh. Most
+ *           recent last. Must be non-empty — Solomon should always see at
+ *           least one piece of evidence.
+ */
+
+/**
+ * Solomon's ruling on a `Conflict`. Returned by `invokeSolomon()` and
+ * consumed by the orchestrator to decide what happens next.
+ *
+ * @typedef {Object} SolomonResult
+ * @property {"continue"|"pause"|"subtask"} action
+ *           - `continue`: retry the sub-loop with optional `humanGuidance`
+ *             appended to the next feedback round.
+ *           - `pause`: stop the pipeline and surface a question to the
+ *             human operator (`SolomonResult.question`).
+ *           - `subtask`: bifurcate into a named sub-task defined in
+ *             `SolomonResult.subtask`.
+ * @property {string} [rationale]         - human-readable reasoning for the
+ *                                          chosen action. Logged to the
+ *                                          decisions journal.
+ * @property {string} [humanGuidance]     - text to merge into the next
+ *                                          coder/reviewer prompt when
+ *                                          action === "continue".
+ * @property {string} [question]          - prompt shown to the human when
+ *                                          action === "pause".
+ * @property {Object} [subtask]           - sub-task descriptor when
+ *                                          action === "subtask".
+ */
+
+export {};

package/src/types/stage.js

@@ -0,0 +1,68 @@
+/**
+ * Stage context + stage result typedefs. A StageContext is the bundle of
+ * orchestration state every stage function receives; a StageResult is what
+ * they return for downstream stages to consume.
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(msg: string, ...rest: any[]) => void} info
+ * @property {(msg: string, ...rest: any[]) => void} warn
+ * @property {(msg: string, ...rest: any[]) => void} error
+ * @property {(msg: string, ...rest: any[]) => void} [debug]
+ */
+
+/**
+ * @typedef {Object} Emitter
+ * @property {(event: string, data?: any) => void} emit
+ */
+
+/**
+ * Shape of `eventBase` propagated to every emitted event for correlation.
+ *
+ * @typedef {Object} EventBase
+ * @property {string} sessionId
+ * @property {number} iteration
+ * @property {string|null} stage
+ * @property {number} startedAt                  - epoch ms
+ */
+
+/**
+ * The context every pipeline stage consumes. Most stages pick a subset with
+ * destructuring. Listed here so consumers can import a single type instead
+ * of re-declaring ad-hoc objects.
+ *
+ * @typedef {Object} StageContext
+ * @property {import("./config.js").KarajanConfig} config
+ * @property {import("./session.js").Session} session
+ * @property {Logger} logger
+ * @property {Emitter|null} emitter
+ * @property {EventBase} eventBase
+ * @property {Function} [trackBudget]
+ * @property {Function} [budgetSummary]
+ * @property {import("./config.js").PipelineFlags} [pipelineFlags]
+ * @property {Object} [coderRole]                - CoderRole instance
+ * @property {Object} [reviewerRole]
+ * @property {Object} [brainCtx]
+ * @property {Function} [askQuestion]
+ * @property {Object} [stageResults]             - accumulated results from prior stages
+ * @property {string} [task]
+ * @property {string|null} [pgTaskId]
+ * @property {string|null} [pgProject]
+ * @property {Object} [flags]                    - CLI/call-time flags
+ */
+
+/**
+ * The structured return of most stage helpers. Stages are allowed to return
+ * shape-specific additions on top of these common fields.
+ *
+ * @typedef {Object} StageResult
+ * @property {boolean} ok
+ * @property {string} [summary]
+ * @property {Object} [result]                   - stage-specific payload
+ * @property {string} [action]                   - "return" | "retry" | "continue" | "skip" | ...
+ * @property {Object} [stageResult]              - alternate nested result shape used by some stages
+ * @property {string} [provider]
+ */
+
+export {};

package/src/utils/agent-detect.js

@@ -0,0 +1,93 @@
+import { runCommand } from "./process.js";
+import { resolveBin } from "../agents/resolve-bin.js";
+import { getInstallCommand } from "./os-detect.js";
+
+const KNOWN_AGENTS = [
+  { name: "claude", install: getInstallCommand("claude") },
+  { name: "codex", install: getInstallCommand("codex") },
+  { name: "gemini", install: getInstallCommand("gemini") },
+  { name: "aider", install: getInstallCommand("aider") },
+  { name: "opencode", install: getInstallCommand("opencode") },
+  { name: "qwen", install: getInstallCommand("qwen") },
+  { name: "copilot", install: getInstallCommand("copilot") },
+  // KJC-TSK-0729: promoted from the observation census once its adapter
+  // landed — detecting is not supporting; supporting is.
+  { name: "kimi", install: getInstallCommand("kimi") },
+  { name: "agy", install: getInstallCommand("agy") }
+];
+
+/**
+ * KJC-TSK-0728 — observation census (from the Orca landscape): agent CLIs kj
+ * can SEE but does not drive. Detecting is not supporting — these never feed
+ * pipeline pickers; they feed the AI-surface inventory and one doctor line.
+ * `bin` differs from `name` when the vendor ships an umbrella binary.
+ */
+const OBSERVED_AGENTS = [
+  { name: "grok", bin: "grok" },
+  { name: "cursor-agent", bin: "cursor-agent" },
+  { name: "pi", bin: "pi" },
+  { name: "kilocode", bin: "kilocode" },
+  { name: "vibe", bin: "vibe" },
+  { name: "rovodev", bin: "acli" },
+];
+
+/** Probe the observation census in parallel; callers filter on `available`. */
+export async function detectObservedAgents() {
+  return Promise.all(
+    OBSERVED_AGENTS.map(async (agent) => {
+      const check = await checkBinary(agent.bin);
+      return { name: agent.name, bin: agent.bin, available: check.ok, version: check.ok ? check.version : null };
+    })
+  );
+}
+
+export async function checkBinary(name, versionArg = "--version") {
+  const resolved = resolveBin(name);
+  // KJC-BUG-0113: a zombie CLI that hangs on --version (seen with the
+  // retired Gemini Code Assist binary) must not hang init/preflight —
+  // 5s is generous for a version print.
+  const res = await runCommand(resolved, [versionArg], { timeout: 5000 });
+  const version = (res.stdout || res.stderr || "").split("\n")[0].trim();
+  return { ok: res.exitCode === 0, version, path: resolved };
+}
+
+export async function detectAvailableAgents() {
+  // PR-J (audit quick win): probe the 5 agent binaries in parallel
+  // via Promise.all instead of awaiting in a for-of. checkBinary is
+  // a pure shell-out (no shared state), so serialising them was
+  // wasted latency. With 5 agents at ~80ms each: O(n) → O(1).
+  return Promise.all(
+    KNOWN_AGENTS.map(async (agent) => {
+      const check = await checkBinary(agent.name);
+      return {
+        name: agent.name,
+        available: check.ok,
+        version: check.ok ? check.version : null,
+        install: agent.install
+      };
+    })
+  );
+}
+
+/**
+ * Detect which AI agent is the current MCP host (if any).
+ * Returns the agent name ("claude", "codex", etc.) or null if not inside an agent.
+ */
+export function detectHostAgent() {
+  if (process.env.CLAUDECODE === "1" || process.env.CLAUDE_CODE === "1") return "claude";
+  if (process.env.CODEX_CLI === "1" || process.env.CODEX === "1") return "codex";
+  if (process.env.GEMINI_CLI === "1") return "gemini";
+  if (process.env.OPENCODE === "1") return "opencode";
+  return null;
+}
+
+/**
+ * Check if a given provider matches the current host agent.
+ * When true, we can skip subprocess spawning and delegate to the host.
+ */
+export function isHostAgent(provider) {
+  const host = detectHostAgent();
+  return host !== null && host === provider;
+}
+
+export { KNOWN_AGENTS, OBSERVED_AGENTS };

package/src/utils/ai-trash.js

@@ -0,0 +1,48 @@
+// ai-trash detection + Claude Code hook install (KJC-TSK-0391).
+// `kj-trash` is the binary shipped by the @karajan/ai-trash workspace.
+// detectAiTrash() probes the binary; installAiTrashHook() invokes
+// `kj-trash install --claude-code`, which idempotently patches
+// ~/.claude/settings.json to register the PreToolUse hook.
+
+import { runCommand } from "./process.js";
+
+/**
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectAiTrash() {
+  try {
+    const res = await runCommand("kj-trash", ["--help"]);
+    if (res.exitCode === 0 || res.exitCode === 2) {
+      return { available: true, version: "0.0.0" };
+    }
+    return { available: false, version: null };
+  } catch {
+    return { available: false, version: null };
+  }
+}
+
+/**
+ * Register the kj-trash PreToolUse hook in ~/.claude/settings.json.
+ * Idempotent: second run reports "already installed" without rewriting.
+ *
+ * @param {object} logger - logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, mutated: boolean, error: string|null }>}
+ */
+export async function installAiTrashHook(logger) {
+  logger.info("Registering ai-trash Claude Code hook...");
+  try {
+    const res = await runCommand("kj-trash", ["install", "--claude-code"], { timeout: 30_000 });
+    if (res.exitCode !== 0) {
+      const error = (res.stderr || "").trim() || `exit code ${res.exitCode}`;
+      logger.warn(`ai-trash hook install failed: ${error}`);
+      return { ok: false, mutated: false, error };
+    }
+    const mutated = !(res.stdout || "").includes("already installed");
+    logger.info(mutated ? "ai-trash hook installed." : "ai-trash hook already installed.");
+    return { ok: true, mutated, error: null };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`ai-trash hook install failed: ${error}`);
+    return { ok: false, mutated: false, error };
+  }
+}

package/src/utils/async-lock.js

@@ -0,0 +1,31 @@
+/**
+ * async-lock — named in-process mutex (KJC-TSK-0625, épica KJC-PCS-0065).
+ * Parallel HU lanes run inside ONE kj process; shared single-instance
+ * resources (the SonarQube server scans one project key at a time) must
+ * serialize across lanes. `withLock` chains callers per name in FIFO
+ * order; sequential runs pay nothing (the chain is always settled).
+ */
+
+const locks = new Map(); // name -> { tail: Promise, holders: number }
+
+/** Run `fn` exclusively among every caller sharing `name`. */
+export async function withLock(name, fn) {
+  const entry = locks.get(name) ?? { tail: Promise.resolve(), holders: 0 };
+  entry.holders += 1;
+  locks.set(name, entry);
+
+  const previous = entry.tail;
+  let release;
+  entry.tail = new Promise((resolve) => {
+    release = resolve;
+  });
+
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    entry.holders -= 1;
+    if (entry.holders === 0) locks.delete(name);
+  }
+}

package/src/utils/atomic-write.js

@@ -0,0 +1,6 @@
+// Shim — the real implementation now lives in karajan-core/atomic-write.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "#utils/atomic-write.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the karajan-core import.
+export { writeJsonAtomic, writeJsonAtomicSync } from "karajan-core/atomic-write";