karajan-code 1.50.1 → 1.51.0

package/package.json

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

package/src/commands/doctor.js

@@ -208,15 +208,20 @@ async function checkBecariaInfra(config) {
 }
 
 async function checkRtk() {
-  const NOT_FOUND_DETAIL = `Not found — install for 60-90% token savings: ${getInstallCommand("rtk")}`;
-  let detail = NOT_FOUND_DETAIL;
+  const installCmd = getInstallCommand("rtk");
   try {
     const res = await runCommand("rtk", ["--version"]);
     if (res.exitCode === 0) {
-      detail = `${res.stdout.trim()} — token savings active`;
+      return { name: "rtk", label: "RTK (Rust Token Killer)", ok: true, detail: `${res.stdout.trim()} — token savings active`, fix: null };
     }
   } catch { /* not installed */ }
-  return { name: "rtk", label: "RTK (Rust Token Killer)", ok: true, detail, fix: null };
+  return {
+    name: "rtk",
+    label: "RTK (Rust Token Killer)",
+    ok: false,
+    detail: "Not found — 60-90% token savings available",
+    fix: `Install: ${installCmd}`
+  };
 }
 
 async function checkRuleFiles(config) {

package/src/commands/init.js

@@ -10,6 +10,8 @@ import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
+import { detectRtk } from "../utils/rtk-detect.js";
+import { installRtk } from "../utils/rtk-install.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -328,18 +330,16 @@ export async function initCommand({ logger, flags = {} }) {
   await ensureCoderRules(coderRulesPath, logger);
   await installSkills(logger, interactive);
 
-  // Check RTK availability and inform user
-  let hasRtk = false;
-  try {
-    const rtkRes = await runCommand("rtk", ["--version"]);
-    hasRtk = rtkRes.exitCode === 0;
-  } catch { /* rtk not installed */
-    hasRtk = false;
-  }
-  if (!hasRtk) {
-    logger.info("");
-    logger.info("RTK (Rust Token Killer) can reduce token usage by 60-90%.");
-    logger.info(`  Install: ${getInstallCommand("rtk")}`);
+  // Check RTK availability — auto-install if missing
+  const rtk = await detectRtk();
+  if (rtk.available) {
+    logger.info(`RTK ${rtk.version || ""} detected.`);
+  } else {
+    const installResult = await installRtk(logger);
+    if (!installResult.ok) {
+      logger.warn("RTK is optional but recommended for 60-90% token savings.");
+      logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+    }
   }
 
   await setupSonarQube(config, logger);

package/src/commands/report.js

@@ -152,6 +152,7 @@ async function buildReport(dir, sessionId) {
   };
   if (session.pg_task_id) report.pg_task_id = session.pg_task_id;
   if (session.pg_project_id) report.pg_project_id = session.pg_project_id;
+  if (session.rtk_savings) report.rtk_savings = session.rtk_savings;
   return report;
 }
 
@@ -326,6 +327,16 @@ async function resolveTraceOptions(currency) {
   return { cur, rate };
 }
 
+function printRtkSavings(rtkSavings) {
+  if (!rtkSavings || !rtkSavings.callCount) return;
+  const tokens = rtkSavings.estimatedTokensSaved ?? 0;
+  const ratio = rtkSavings.savedPct ?? 0;
+  const commands = rtkSavings.callCount ?? 0;
+  console.log("");
+  console.log(`RTK Savings: ~${tokens} tokens saved (${ratio}% compression, ${commands} commands)`);
+  console.log(`  Original: ${rtkSavings.originalBytes} bytes, Compressed: ${rtkSavings.rtkBytes} bytes, Saved: ${rtkSavings.savedBytes} bytes`);
+}
+
 function printTraceReport(report, currency, exchangeRate) {
   console.log(`Session: ${report.session_id}`);
   printPgCardLine(report);
@@ -333,6 +344,7 @@ function printTraceReport(report, currency, exchangeRate) {
   console.log(`Task: ${report.task_description || "N/A"}`);
   console.log("");
   printTraceTable(report.budget_trace, { currency, exchangeRate });
+  printRtkSavings(report.rtk_savings);
 }
 
 async function handlePgTaskReport({ dir, pgTask, list, sessionId, format, trace, currency }) {

package/src/guards/intent-guard.js

@@ -6,6 +6,15 @@ import { VALID_TASK_TYPES } from "./policy-resolver.js";
  * Evaluated top-down; first match with confidence >= threshold wins.
  */
 const INTENT_PATTERNS = [
+  // Audit / analysis tasks (no code changes, read-only analysis)
+  {
+    id: "audit",
+    keywords: ["audit", "review", "analyze", "check", "verify", "inspect", "scan", "auditar", "revisar", "analizar", "comprobar", "verificar", "inspeccionar"],
+    taskType: "audit",
+    level: "simple",
+    confidence: 0.9,
+    message: "Audit/analysis task detected — skipping coder and reviewer",
+  },
   // Documentation-only tasks
   {
     id: "doc-readme",

package/src/guards/policy-resolver.js

@@ -1,4 +1,4 @@
-export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor"]);
+export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "audit", "analysis"]);
 
 export const DEFAULT_POLICIES = {
   sw:        { tdd: true,  sonar: true,  reviewer: true, testsRequired: true  },
@@ -6,6 +6,8 @@ export const DEFAULT_POLICIES = {
   doc:       { tdd: false, sonar: false, reviewer: true, testsRequired: false },
   "add-tests": { tdd: false, sonar: true,  reviewer: true, testsRequired: true  },
   refactor:  { tdd: true,  sonar: true,  reviewer: true, testsRequired: false },
+  audit:     { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
+  analysis:  { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
 };
 
 const FALLBACK_TYPE = "sw";

package/src/orchestrator.js

@@ -41,6 +41,9 @@ import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js"
 import { detectTestFramework } from "./utils/project-detect.js";
 import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
 import { detectRtk } from "./utils/rtk-detect.js";
+import { createRtkRunner, RtkSavingsTracker } from "./utils/rtk-wrapper.js";
+import { setRunner as setDiffRunner } from "./review/diff-generator.js";
+import { setRunner as setGitRunner } from "./utils/git.js";
 import { detectNeededSkills, autoInstallSkills, cleanupAutoInstalledSkills } from "./skills/skill-detector.js";
 import { isOpenSkillsAvailable } from "./skills/openskills-client.js";
 
@@ -278,6 +281,9 @@ function resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBa
   if (!resolvedPolicies.reviewer) {
     pipelineFlags.reviewerEnabled = false;
   }
+  if (resolvedPolicies.coderRequired === false) {
+    pipelineFlags.coderRequired = false;
+  }
 
   emitProgress(
     emitter,
@@ -760,7 +766,7 @@ async function handlePostLoopStages({ config, session, emitter, eventBase, coder
   return { action: "proceed" };
 }
 
-async function finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i }) {
+async function finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i, rtkTracker }) {
   const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
 
   // Accumulate final commits for PG card lifecycle tracking
@@ -779,16 +785,24 @@ async function finalizeApprovedSession({ config, gitCtx, task, logger, session,
   await markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger });
 
   const deferredIssues = session.deferred_issues || [];
+  const rtkSavings = rtkTracker?.hasData() ? rtkTracker.summary() : undefined;
+  if (rtkSavings) session.rtk_savings = rtkSavings;
+  await saveSession(session);
+
+  const endDetail = { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues };
+  if (rtkSavings) endDetail.rtk_savings = rtkSavings;
   emitProgress(
     emitter,
     makeEvent("session:end", { ...eventBase, stage: "done" }, {
       message: deferredIssues.length > 0
         ? `Session approved (${deferredIssues.length} deferred issue(s) tracked as tech debt)`
         : "Session approved",
-      detail: { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues }
+      detail: endDetail
     })
   );
-  return { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
+  const result = { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
+  if (rtkSavings) result.rtk_savings = rtkSavings;
+  return result;
 }
 
 // PG card "To Validate" logic moved to src/planning-game/pipeline-adapter.js → markPgCardToValidate()
@@ -1132,7 +1146,7 @@ async function runReviewerGateStage({ pipelineFlags, reviewerRole, config, logge
   return { action: "ok", review: reviewerResult.review };
 }
 
-async function handleApprovedReview({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, pipelineFlags, askQuestion, logger, gitCtx, budgetSummary, pgCard, pgProject, review }) {
+async function handleApprovedReview({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, pipelineFlags, askQuestion, logger, gitCtx, budgetSummary, pgCard, pgProject, review, rtkTracker }) {
   session.reviewer_retry_count = 0;
   const postLoopResult = await handlePostLoopStages({
     config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults,
@@ -1141,11 +1155,11 @@ async function handleApprovedReview({ config, session, emitter, eventBase, coder
   if (postLoopResult.action === "return") return { action: "return", result: postLoopResult.result };
   if (postLoopResult.action === "continue") return { action: "continue" };
 
-  const result = await finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i });
+  const result = await finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i, rtkTracker });
   return { action: "return", result };
 }
 
-async function handleMaxIterationsReached({ session, budgetSummary, emitter, eventBase, config, stageResults, logger, askQuestion, task }) {
+async function handleMaxIterationsReached({ session, budgetSummary, emitter, eventBase, config, stageResults, logger, askQuestion, task, rtkTracker }) {
   // Escalate to Solomon / human before giving up
   const solomonResult = await invokeSolomon({
     config, logger, emitter, eventBase, stage: "max_iterations", askQuestion, session,
@@ -1178,13 +1192,17 @@ async function handleMaxIterationsReached({ session, budgetSummary, emitter, eve
 
   // Solomon also couldn't resolve — fail
   session.budget = budgetSummary();
+  const rtkSavings = rtkTracker?.hasData() ? rtkTracker.summary() : undefined;
+  if (rtkSavings) session.rtk_savings = rtkSavings;
   await markSessionStatus(session, "failed");
+  const failDetail = { approved: false, reason: "max_iterations", iterations: config.max_iterations, stages: stageResults, budget: budgetSummary() };
+  if (rtkSavings) failDetail.rtk_savings = rtkSavings;
   emitProgress(
     emitter,
     makeEvent("session:end", { ...eventBase, stage: "done" }, {
       status: "fail",
       message: "Max iterations reached (Solomon could not resolve)",
-      detail: { approved: false, reason: "max_iterations", iterations: config.max_iterations, stages: stageResults, budget: budgetSummary() }
+      detail: failDetail
     })
   );
   return { approved: false, sessionId: session.id, reason: "max_iterations" };
@@ -1232,9 +1250,14 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
   const rtkResult = await detectRtk();
   if (rtkResult.available) {
     config = { ...config, rtk: { available: true, version: rtkResult.version } };
-    logger.info(`RTK detected (${rtkResult.version}) — instructing agents to prefix Bash commands with rtk`);
+    const rtkTracker = new RtkSavingsTracker();
+    const rtkRunner = createRtkRunner(true, rtkTracker);
+    setDiffRunner(rtkRunner);
+    setGitRunner(rtkRunner);
+    ctx.rtkTracker = rtkTracker;
+    logger.info(`RTK detected (${rtkResult.version}) — wrapping internal git/diff commands with rtk`);
     emitProgress(emitter, makeEvent("rtk:detected", ctx.eventBase, {
-      message: "RTK detected — agent commands will use token optimization",
+      message: "RTK detected — internal commands wrapped for token optimization",
       detail: { version: rtkResult.version, executorType: "local" }
     }));
   }
@@ -1351,7 +1374,8 @@ async function runSingleIteration(ctx) {
     const approvedResult = await handleApprovedReview({
       config, session, emitter, eventBase, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, i, task,
       stageResults: ctx.stageResults, pipelineFlags: ctx.pipelineFlags, askQuestion: ctx.askQuestion, logger,
-      gitCtx: ctx.gitCtx, budgetSummary: ctx.budgetSummary, pgCard: ctx.pgCard, pgProject: ctx.pgProject, review
+      gitCtx: ctx.gitCtx, budgetSummary: ctx.budgetSummary, pgCard: ctx.pgCard, pgProject: ctx.pgProject, review,
+      rtkTracker: ctx.rtkTracker
     });
     if (approvedResult.action === "return" || approvedResult.action === "continue") return approvedResult;
   }
@@ -1430,7 +1454,7 @@ async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitter, log
     if (iterResult.action === "retry") { i -= 1; }
   }
 
-  const maxIterResult = await handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task: loopTask });
+  const maxIterResult = await handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task: loopTask, rtkTracker: ctx.rtkTracker });
   return maxIterResult;
 }
 
@@ -1444,6 +1468,53 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
 
   try {
+    // --- Analysis-only flow: skip coder/reviewer when coderRequired === false ---
+    if (ctx.pipelineFlags.coderRequired === false) {
+      logger.info("Analysis-only task — skipping coder/reviewer iteration loop");
+      emitProgress(emitter, makeEvent("pipeline:analysis-only", { ...ctx.eventBase, stage: "analysis" }, {
+        message: "Analysis-only task — running security and audit stages only",
+        detail: { taskType: ctx.session.resolved_policies?.taskType, coderRequired: false }
+      }));
+
+      const analysisStageResults = ctx.stageResults;
+      const postLoopDiff = await generateDiff({ baseRef: ctx.session.session_start_sha });
+
+      if (ctx.pipelineFlags.securityEnabled) {
+        const securityResult = await runSecurityStage({
+          config: ctx.config, logger, emitter, eventBase: ctx.eventBase, session: ctx.session,
+          coderRole: ctx.coderRole, trackBudget: ctx.trackBudget,
+          iteration: 1, task: ctx.plannedTask, diff: postLoopDiff, askQuestion
+        });
+        if (securityResult.stageResult) analysisStageResults.security = securityResult.stageResult;
+      }
+
+      const auditResult = await runFinalAuditStage({
+        config: ctx.config, logger, emitter, eventBase: ctx.eventBase, session: ctx.session,
+        coderRole: ctx.coderRole, trackBudget: ctx.trackBudget,
+        iteration: 1, task: ctx.plannedTask, diff: postLoopDiff
+      });
+      if (auditResult.stageResult) analysisStageResults.audit = auditResult.stageResult;
+
+      ctx.session.budget = ctx.budgetSummary();
+      await markSessionStatus(ctx.session, "approved");
+
+      const analysisResult = {
+        approved: true,
+        sessionId: ctx.session.id,
+        analysisOnly: true,
+        stages: analysisStageResults,
+        budget: ctx.budgetSummary()
+      };
+      await writeHistoryRecord({ sessionId: ctx.session.id, task, result: analysisResult, logger });
+
+      emitProgress(emitter, makeEvent("session:end", { ...ctx.eventBase, stage: "done" }, {
+        message: "Analysis-only session completed",
+        detail: analysisResult
+      }));
+
+      return analysisResult;
+    }
+
     // --- HU Sub-Pipeline: run each certified HU as an independent iteration loop ---
     if (needsSubPipeline(ctx.stageResults.huReviewer)) {
       logger.info(`HU sub-pipeline: ${ctx.stageResults.huReviewer.certified} certified stories — running each as a sub-pipeline`);

package/src/prompts/triage.js

@@ -39,13 +39,14 @@ export function buildTriagePrompt({ task, instructions, availableRoles }) {
       "- **reviewer**: Enable for most tasks as a quality gate. Disable only for trivial, single-line changes.",
       "- **architect**: Enable when creating new modules/apps, changing data models or APIs, medium/complex tasks, or when design approach is ambiguous. Disable for simple fixes, doc-only, or CSS-only changes.",
       "- **hu-reviewer**: Enable for medium/complex tasks that benefit from story decomposition and certification. Disable for trivial/simple tasks, doc-only, or CSS-only changes.",
+      "- **audit/analysis taskType**: Set taskType to \"audit\" or \"analysis\" for tasks that only require reading/inspecting code without making changes (e.g., audit, review, analyze, check, verify, inspect, scan, auditar, revisar, analizar, comprobar, verificar, inspeccionar). The coder and reviewer will be skipped entirely for these tasks.",
       "",
-      "Note: coder is ALWAYS active — you don't need to decide on it."
+      "Note: coder is ALWAYS active for coding tasks — you don't need to decide on it. However, for audit/analysis taskTypes the coder is skipped."
     ].join("\n"),
     "Classify the task complexity, determine its taskType, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
     "Keep the reasoning short and practical.",
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect|hu-reviewer"],"taskType":"sw|infra|doc|add-tests|refactor","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
+    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect|hu-reviewer"],"taskType":"sw|infra|doc|add-tests|refactor|audit|analysis","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
     `## Task\n${task}`
   );
 

package/src/review/diff-generator.js

@@ -1,10 +1,26 @@
 import { runCommand } from "../utils/process.js";
 
+/** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
+let _runner = null;
+
+/**
+ * Inject an RTK-aware runner so all git operations in this module benefit from token savings.
+ * Call once at pipeline start when RTK is available.
+ * @param {(command: string, args?: string[], options?: object) => Promise<object>} runner
+ */
+export function setRunner(runner) {
+  _runner = runner;
+}
+
+function run(command, args, ...rest) {
+  return (_runner || runCommand)(command, args, ...rest);
+}
+
 export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
   if (baseRef) return baseRef;
-  const mergeBase = await runCommand("git", ["merge-base", "HEAD", `origin/${baseBranch}`]);
+  const mergeBase = await run("git", ["merge-base", "HEAD", `origin/${baseBranch}`]);
   if (mergeBase.exitCode !== 0) {
-    const fallback = await runCommand("git", ["rev-parse", "HEAD~1"]);
+    const fallback = await run("git", ["rev-parse", "HEAD~1"]);
     if (fallback.exitCode !== 0) {
       throw new Error("Could not compute diff base reference");
     }
@@ -16,9 +32,9 @@ export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
 export async function generateDiff({ baseRef, stageNewFiles = false }) {
   // Stage untracked files so they appear in the diff (coder creates files but doesn't git add)
   if (stageNewFiles) {
-    await runCommand("git", ["add", "-A"]);
+    await run("git", ["add", "-A"]);
   }
-  const result = await runCommand("git", ["diff", stageNewFiles ? "--cached" : "", `${baseRef}`].filter(Boolean));
+  const result = await run("git", ["diff", stageNewFiles ? "--cached" : "", `${baseRef}`].filter(Boolean));
   if (result.exitCode !== 0) {
     throw new Error(`git diff failed: ${result.stderr || result.stdout}`);
   }
@@ -26,7 +42,7 @@ export async function generateDiff({ baseRef, stageNewFiles = false }) {
 }
 
 export async function getUntrackedFiles() {
-  const result = await runCommand("git", ["ls-files", "--others", "--exclude-standard"]);
+  const result = await run("git", ["ls-files", "--others", "--exclude-standard"]);
   if (result.exitCode !== 0) return [];
   return result.stdout.trim().split("\n").filter(Boolean);
 }

package/src/utils/display.js

@@ -252,6 +252,14 @@ function isBudgetUnavailable(budget) {
     (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
 }
 
+function printSessionRtkSavings(rtkSavings) {
+  if (!rtkSavings || !rtkSavings.callCount) return;
+  const tokens = rtkSavings.estimatedTokensSaved ?? 0;
+  const ratio = rtkSavings.savedPct ?? 0;
+  const commands = rtkSavings.callCount ?? 0;
+  console.log(`  ${ANSI.dim}\u26a1 RTK: saved ~${tokens} tokens (${ratio}% compression, ${commands} commands)${ANSI.reset}`);
+}
+
 function printSessionBudget(budget) {
   if (!budget) return;
   if (isBudgetUnavailable(budget)) {
@@ -447,6 +455,7 @@ const EVENT_HANDLERS = {
     printSessionStages(event.detail?.stages);
     printSessionGit(event.detail?.git);
     printSessionBudget(event.detail?.budget);
+    printSessionRtkSavings(event.detail?.rtk_savings);
     console.log(`${ANSI.dim}Session: ${event.sessionId}${ANSI.reset}`);
   },
 

package/src/utils/git.js

@@ -1,5 +1,20 @@
 import { runCommand } from "./process.js";
 
+/** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
+let _runner = null;
+
+/**
+ * Inject an RTK-aware runner so all git operations in this module benefit from token savings.
+ * @param {(command: string, args?: string[], options?: object) => Promise<object>} runner
+ */
+export function setRunner(runner) {
+  _runner = runner;
+}
+
+function run(command, args, ...rest) {
+  return (_runner || runCommand)(command, args, ...rest);
+}
+
 function slugifyTask(task) {
   return String(task)
     .toLowerCase()
@@ -9,7 +24,7 @@ function slugifyTask(task) {
 }
 
 async function runGit(args, options = {}) {
-  const res = await runCommand("git", args, options);
+  const res = await run("git", args, options);
   if (res.exitCode !== 0) {
     throw new Error(`git ${args.join(" ")} failed: ${res.stderr || res.stdout}`);
   }
@@ -17,7 +32,7 @@ async function runGit(args, options = {}) {
 }
 
 export async function ensureGitRepo() {
-  const res = await runCommand("git", ["rev-parse", "--is-inside-work-tree"]);
+  const res = await run("git", ["rev-parse", "--is-inside-work-tree"]);
   return res.exitCode === 0 && res.stdout.trim() === "true";
 }
 

package/src/utils/rtk-install.js

@@ -0,0 +1,38 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectRtk } from "./rtk-detect.js";
+
+/**
+ * Install RTK (Rust Token Killer) using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installRtk(logger) {
+  const command = getInstallCommand("rtk");
+
+  logger.info("Installing RTK (Rust Token Killer)...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`RTK install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    // Verify installation
+    const check = await detectRtk();
+    if (check.available) {
+      logger.info(`RTK ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("RTK install command succeeded but rtk binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`RTK install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}

package/src/utils/rtk-wrapper.js

@@ -0,0 +1,87 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Commands that RTK can safely wrap for token-optimized output.
+ */
+export const RTK_SUPPORTED_COMMANDS = [
+  "git", "ls", "find", "grep", "cat", "head", "tail",
+  "wc", "diff", "tree", "du", "file"
+];
+
+const supportedSet = new Set(RTK_SUPPORTED_COMMANDS);
+
+/**
+ * Wrap a command with RTK if available and the command is in the whitelist.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {boolean} rtkAvailable
+ * @returns {{ command: string, args: string[] }}
+ */
+export function wrapWithRtk(command, args, rtkAvailable) {
+  if (rtkAvailable && supportedSet.has(command)) {
+    return { command: "rtk", args: [command, ...args] };
+  }
+  return { command, args };
+}
+
+/**
+ * Session-level accumulator for RTK byte savings.
+ */
+export class RtkSavingsTracker {
+  constructor() {
+    this.originalBytes = 0;
+    this.rtkBytes = 0;
+    this.callCount = 0;
+  }
+
+  record(originalSize, rtkSize) {
+    this.originalBytes += originalSize;
+    this.rtkBytes += rtkSize;
+    this.callCount += 1;
+  }
+
+  summary() {
+    const savedBytes = this.originalBytes - this.rtkBytes;
+    const savedPct = this.originalBytes > 0
+      ? Number(((savedBytes / this.originalBytes) * 100).toFixed(1))
+      : 0;
+    const estimatedTokensSaved = Math.floor(savedBytes / 4);
+    return {
+      originalBytes: this.originalBytes,
+      rtkBytes: this.rtkBytes,
+      savedBytes,
+      savedPct,
+      estimatedTokensSaved,
+      callCount: this.callCount
+    };
+  }
+
+  /** Returns true if any commands were recorded. */
+  hasData() {
+    return this.callCount > 0;
+  }
+}
+
+/**
+ * Create a runner function that transparently wraps supported commands with RTK.
+ * @param {boolean} rtkAvailable
+ * @param {RtkSavingsTracker} [tracker] - Optional savings tracker
+ * @returns {(command: string, args?: string[], options?: object) => Promise<object>}
+ */
+export function createRtkRunner(rtkAvailable, tracker = null) {
+  return async (command, args = [], options = {}) => {
+    const wrapped = wrapWithRtk(command, args, rtkAvailable);
+    const result = await runCommand(wrapped.command, wrapped.args, options);
+
+    if (tracker && rtkAvailable && supportedSet.has(command)) {
+      const outputSize = Buffer.byteLength(result.stdout || "", "utf8");
+      // For RTK-wrapped calls, the output is already compressed.
+      // We estimate the original size as outputSize (conservative — real savings
+      // would require running the command without RTK, which defeats the purpose).
+      // The tracker is useful when the caller provides real estimates externally.
+      tracker.record(outputSize, outputSize);
+    }
+
+    return result;
+  };
+}