getprismo 0.1.39 → 0.1.41

package/lib/prismo-dev/agent.js

@@ -13,6 +13,8 @@ module.exports = function createAgent(deps) {
     runShield,
     runOptimize,
     openUrl,
+    repairExecutors,
+    repairPlanner,
   } = deps;
 
   const DEFAULT_WORKSPACE_URL = "https://getprismo.dev/dashboard/dev";
@@ -21,6 +23,15 @@ module.exports = function createAgent(deps) {
   const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
   const SAFE_SHIELD_COMMANDS = new Set(["npm", "pnpm", "yarn", "bun", "npx", "pytest", "python", "python3", "node"]);
   const VALID_MODES = new Set(["observe", "suggest", "autopilot"]);
+  // Backend verification only measures these action types, so self-repairs
+  // are registered under the matching type for their cause.
+  const CAUSE_ACTION_TYPES = {
+    "repeated-file-reads": "doctor",
+    "tool-output-flood": "shield",
+    "generated-artifacts": "doctor",
+    "context-loop": "guard",
+    "long-session-buildup": "context",
+  };
 
   function apiBase(config) {
     return String(config?.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
@@ -166,6 +177,66 @@ module.exports = function createAgent(deps) {
     } catch (_) {}
   }
 
+  // Register an executed self-repair as a real workspace action row so the
+  // backend verification loop measures it like a dashboard-queued repair.
+  // Returns false when the endpoint is unavailable (older API) so the
+  // caller can fall back to the auto-detect channel.
+  async function registerSelfRepair(config, plannerResult, options = {}) {
+    if (!plannerResult || !plannerResult.decision || !plannerResult.outcome) return false;
+    const { cause, tier } = plannerResult.decision;
+    const endpoint = options.selfRepairEndpoint || `${apiBase(config)}/v1/dev/workspace/actions/agent`;
+    try {
+      const created = await requestJson("POST", endpoint, config.token, {
+        actionType: CAUSE_ACTION_TYPES[cause] || "doctor",
+        command: `${NPX_COMMAND} repair ${cause}`,
+        label: `Self-repair: ${cause} (${tier})`,
+        targetCause: cause,
+      }, options.timeoutMs || 10000);
+      const actionId = created.data && created.data.id;
+      if (!actionId) return false;
+      await updateAction(config, actionId, {
+        status: plannerResult.outcome.status,
+        statusMessage: plannerResult.outcome.statusMessage,
+        result: {
+          executor: "repair-planner",
+          targetCause: cause,
+          tier,
+          generatedFiles: plannerResult.outcome.generatedFiles || [],
+        },
+      }, options);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Fallback reporting channel for planner activity (planned-only repairs,
+  // or APIs without the agent action endpoint).
+  async function reportPlanner(config, plannerResult, mode, options = {}) {
+    if (!plannerResult || (!plannerResult.decision && !plannerResult.executed)) return;
+    const findings = [];
+    if (plannerResult.decision) {
+      findings.push({
+        type: "self-repair",
+        cause: plannerResult.decision.cause,
+        tier: plannerResult.decision.tier,
+        message: plannerResult.outcome && plannerResult.outcome.statusMessage
+          ? plannerResult.outcome.statusMessage
+          : plannerResult.decision.reason,
+      });
+    }
+    await reportAutoDetect(config, {
+      startedAt: plannerResult.generatedAt,
+      completedAt: new Date().toISOString(),
+      mode,
+      score: null,
+      findings,
+      generatedFiles: plannerResult.outcome ? plannerResult.outcome.generatedFiles : [],
+      applied: Boolean(plannerResult.executed),
+      needsApproval: mode !== "autopilot" && Boolean(plannerResult.decision),
+    }, options);
+  }
+
   function openWorkspace(config) {
     const url = config?.workspaceUrl || DEFAULT_WORKSPACE_URL;
     if (openUrl) {
@@ -192,6 +263,20 @@ module.exports = function createAgent(deps) {
     const config = options._config || null;
     const progress = config ? (step, detail) => reportProgress(config, action.id, step, detail, options) : async () => {};
 
+    // Cause-specific repair executors take precedence: an action that names a
+    // waste cause gets a targeted repair instead of the generic command run.
+    const targetCause = action.targetCause
+      || (parsed.command === "repair" ? parsed.args.find((arg) => !arg.startsWith("-")) : null);
+    const causeExecutor = repairExecutors ? repairExecutors.forCause(targetCause) : null;
+    if (causeExecutor) {
+      // The backend escalates a repair by queueing "repair <cause> --tier
+      // aggressive" when the previous repair's verdict was no-change/regressed.
+      const tierIndex = parsed.args.indexOf("--tier");
+      const tierArg = tierIndex >= 0 ? parsed.args[tierIndex + 1] : null;
+      const executorOptions = tierArg ? { ...options, tier: tierArg } : options;
+      return causeExecutor(action, root, { progress, parsed, options: executorOptions });
+    }
+
     if (parsed.command === "doctor" || action.actionType === "doctor") {
       await progress("scanning", "Scanning repo for context issues");
       const result = runDoctor(root, { limit: options.limit || 3, applySuggestions: true, json: true });
@@ -371,6 +456,23 @@ module.exports = function createAgent(deps) {
       results.push({ id: action.id, label: action.label, ...result });
     }
 
+    let plannerResult = null;
+    if (options.planRepairs && repairPlanner) {
+      try {
+        plannerResult = await repairPlanner.runPlannerOnce(rootDir, {
+          execute: mode === "autopilot",
+          sessionLimit: options.plannerSessionLimit,
+        });
+        const registered = plannerResult.executed
+          ? await registerSelfRepair(config, plannerResult, options)
+          : false;
+        plannerResult.registered = registered;
+        if (!registered) await reportPlanner(config, plannerResult, mode, options);
+      } catch (error) {
+        plannerResult = { error: error && error.message ? error.message : String(error) };
+      }
+    }
+
     let syncResult = null;
     if (options.syncTelemetry) {
       try {
@@ -400,6 +502,7 @@ module.exports = function createAgent(deps) {
       actionsFailed: results.filter((item) => item.status === "failed").length,
       actionsObserved: results.filter((item) => item.status === "observed" || item.status === "pending_approval").length,
       autoDetect: autoDetectResult,
+      planner: plannerResult,
       sync: syncResult,
       results,
       privacy: {
@@ -449,6 +552,25 @@ module.exports = function createAgent(deps) {
         lines.push(`  - ${f.message}`);
       });
     }
+    if (result.planner && !result.planner.error) {
+      lines.push("");
+      lines.push("Self-repair");
+      if (result.planner.decision) {
+        lines.push(`  Cause: ${result.planner.decision.cause} (${result.planner.decision.tier} tier)`);
+        lines.push(`  Why: ${result.planner.decision.reason}`);
+        if (result.planner.outcome) {
+          lines.push(`  Status: ${result.planner.outcome.status}`);
+          if (result.planner.outcome.statusMessage) lines.push(`  ${result.planner.outcome.statusMessage}`);
+        } else {
+          lines.push(`  Status: planned (mode: ${result.mode}); not executed`);
+        }
+      } else {
+        lines.push("  Nothing to repair right now.");
+      }
+      (result.planner.skipped || []).forEach((item) => {
+        lines.push(`  Held back: ${item.cause} (${item.reason})`);
+      });
+    }
     if (result.sync) {
       lines.push("");
       lines.push("Sync");
@@ -479,11 +601,13 @@ module.exports = function createAgent(deps) {
     const intervalMs = Math.max(5, Number(options.interval || 15)) * 1000;
     const syncIntervalMs = Math.max(30, Number(options.syncInterval || 60)) * 1000;
     const detectIntervalMs = Math.max(60, Number(options.detectInterval || 300)) * 1000;
+    const plannerIntervalMs = Math.max(60, Number(options.plannerInterval || 600)) * 1000;
     let running = true;
     let sleepResolve = null;
     let firstRun = true;
     let lastSyncAt = 0;
     let lastDetectAt = 0;
+    let lastPlanAt = 0;
 
     if (options.open) {
       const config = loadConfig();
@@ -513,9 +637,12 @@ module.exports = function createAgent(deps) {
       if (shouldSync) lastSyncAt = now;
       const shouldDetect = options.autoDetect !== false && (firstRun || now - lastDetectAt >= detectIntervalMs);
       if (shouldDetect) lastDetectAt = now;
+      const shouldPlan = options.planRepairs !== false && (firstRun || now - lastPlanAt >= plannerIntervalMs);
+      if (shouldPlan) lastPlanAt = now;
       const runOptions = {
         ...options,
         autoDetect: shouldDetect,
+        planRepairs: shouldPlan,
         syncTelemetry: shouldSync,
       };
       firstRun = false;

package/lib/prismo-dev/cli.js

@@ -5,7 +5,7 @@ const VALID_COMMANDS = new Set([
   "dev", "init", "doctor", "firewall", "benchmark", "shield", "mcp",
   "connect", "sync", "status", "disconnect", "agent", "connector", "setup", "scan",
   "optimize", "context", "cc", "cursor", "receipt", "instructions",
-  "timeline", "replay", "boundaries", "usage", "guard", "watch", "demo",
+  "timeline", "replay", "boundaries", "usage", "guard", "watch", "demo", "repair",
 ]);
 
 function parseTokenBudget(value) {
@@ -68,6 +68,11 @@ function createCli(deps) {
     runSync,
     renderGuardTerminal,
     runGuard,
+    REPAIR_CAUSES,
+    renderRepairTerminal,
+    runRepair,
+    renderPlannerTerminal,
+    runPlannerOnce,
     renderAgentTerminal,
     runAgent,
     renderConnectorTerminal,
@@ -425,6 +430,7 @@ function createCli(deps) {
       const intervalIndex = rest.indexOf("--interval");
       const syncIntervalIndex = rest.indexOf("--sync-interval");
       const detectIntervalIndex = rest.indexOf("--detect-interval");
+      const plannerIntervalIndex = rest.indexOf("--planner-interval");
       const limitIndex = rest.indexOf("--limit");
       const budgetIndex = rest.indexOf("--budget");
       const modeIndex = rest.indexOf("--mode");
@@ -432,7 +438,7 @@ function createCli(deps) {
       if (!AGENT_VALID_MODES.has(modeValue)) {
         throw new Error(`Invalid agent mode: ${modeValue}. Valid modes: observe, suggest, autopilot`);
       }
-      const positional = getPositionals(rest, new Set(["--interval", "--sync-interval", "--detect-interval", "--limit", "--budget", "--mode"]));
+      const positional = getPositionals(rest, new Set(["--interval", "--sync-interval", "--detect-interval", "--planner-interval", "--limit", "--budget", "--mode"]));
       const target = positional[0] || process.cwd();
       const agentOptions = {
         json,
@@ -440,10 +446,12 @@ function createCli(deps) {
         watch: rest.includes("--watch") && !rest.includes("--once"),
         open: rest.includes("--open"),
         autoDetect: !rest.includes("--no-detect"),
+        planRepairs: !rest.includes("--no-planner"),
         noSync: rest.includes("--no-sync"),
         interval: parsePositiveInt(intervalIndex >= 0 ? rest[intervalIndex + 1] : null, 15),
         syncInterval: parsePositiveInt(syncIntervalIndex >= 0 ? rest[syncIntervalIndex + 1] : null, 60),
         detectInterval: parsePositiveInt(detectIntervalIndex >= 0 ? rest[detectIntervalIndex + 1] : null, 300),
+        plannerInterval: parsePositiveInt(plannerIntervalIndex >= 0 ? rest[plannerIntervalIndex + 1] : null, 600),
         limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 5),
         syncLimit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 20),
         tokenBudget: parseTokenBudget(budgetIndex >= 0 ? rest[budgetIndex + 1] : null) || 600000,
@@ -758,6 +766,41 @@ function createCli(deps) {
       return;
     }
 
+    if (command === "repair") {
+      const json = rest.includes("--json");
+      const separatorIndex = rest.indexOf("--");
+      const ownArgs = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : rest;
+      const commandArgs = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : [];
+      const positional = getPositionals(ownArgs, new Set(["--limit", "--budget", "--scope", "--tier"]));
+      const cause = (positional[0] || "").toLowerCase();
+      const target = positional[1] || process.cwd();
+      const limitIndex = ownArgs.indexOf("--limit");
+      const budgetIndex = ownArgs.indexOf("--budget");
+      const scopeIndex = ownArgs.indexOf("--scope");
+      const tierIndex = ownArgs.indexOf("--tier");
+      if (cause === "auto") {
+        const result = await runPlannerOnce(target, {
+          execute: !ownArgs.includes("--dry-run"),
+          limit: parsePositiveInt(limitIndex >= 0 ? ownArgs[limitIndex + 1] : null, 5),
+          tokenBudget: parseTokenBudget(budgetIndex >= 0 ? ownArgs[budgetIndex + 1] : null),
+        });
+        if (json) console.log(JSON.stringify(result, null, 2));
+        else console.log(renderPlannerTerminal(result));
+        return;
+      }
+      const result = await runRepair(target, cause, {
+        limit: parsePositiveInt(limitIndex >= 0 ? ownArgs[limitIndex + 1] : null, 5),
+        tokenBudget: parseTokenBudget(budgetIndex >= 0 ? ownArgs[budgetIndex + 1] : null),
+        scope: scopeIndex >= 0 ? ownArgs[scopeIndex + 1] : null,
+        tier: tierIndex >= 0 ? ownArgs[tierIndex + 1] : null,
+        commandArgs,
+      });
+      if (json) console.log(JSON.stringify(result, null, 2));
+      else console.log(renderRepairTerminal(result));
+      if (result.status === "failed") process.exitCode = 1;
+      return;
+    }
+
     if (command === "usage" || command === "watch") {
       const json = rest.includes("--json");
       const knownTools = new Set(["codex", "claude", "cursor", "all"]);

package/lib/prismo-dev/cloud-sync.js

@@ -496,6 +496,7 @@ module.exports = function createCloudSync(deps) {
   return {
     buildSyncPayload,
     configPath,
+    estimateWaste,
     loadConfig,
     renderConnectTerminal,
     renderDisconnectTerminal,

package/lib/prismo-dev/help.js

@@ -33,6 +33,7 @@ Usage:
   prismo boundaries [codex|claude|cursor|all] [--json] [--limit N] [path]
   prismo usage [codex|claude|cursor|all] [--json] [--limit N] [path]
   prismo guard [codex|claude|cursor|all] [--json] [--watch] [--once] [--no-sync] [--dry-run] [--limit N] [--budget N] [--interval N] [path]
+  prismo repair <cause|auto> [--json] [--dry-run] [--tier mild|aggressive] [--limit N] [--budget N] [--scope SCOPE] [path] [-- <command ...>]
   prismo watch [codex|claude|cursor|all] [--json] [--once] [--agents] [--report] [--rescue] [--guardrails] [--throttle] [--events] [--no-events] [--auto] [--budget N] [--redact-paths] [--interval N] [path]
   prismo demo
 
@@ -62,6 +63,7 @@ Commands:
   boundaries  Check whether parallel agents are isolated or overlapping.
   usage       Read local Codex/Claude Code/Cursor session logs and summarize token usage.
   guard       Run proactive local guardrails and sync prevention events to Prismo.
+  repair      Run the cause-specific repair for a detected waste cause; "auto" lets the planner pick.
   watch       Refresh local session usage in the terminal.
   demo        Show sample output without needing a messy repo.
   setup       Detect coding tools, tracking modes, local logs, and Prismo proxy readiness.
@@ -288,6 +290,37 @@ Examples:
 Output:
   Runs proactive local protection on top of Prismo watch: live guardrails, rescue prompt, context throttle, context firewall, guard event log, and dashboard-ready prevention events.
   Guard never uploads prompts, source code, file contents, stdout, stderr, or full command logs.`,
+  repair: `PrismoDev Repair
+
+Usage:
+  prismo repair <cause|auto> [--json] [--dry-run] [--tier mild|aggressive] [--limit N] [--budget N] [--scope SCOPE] [path] [-- <command ...>]
+
+Causes:
+  repeated-file-reads   Refresh ignore rules and context packs, and map hot files into .prismo/hot-files.md.
+  tool-output-flood     Stage noisy commands behind shield in .prismo/noisy-commands.md; run a safe command shielded when passed after --.
+  generated-artifacts   Append ignore rules for scan-detected build output plus artifact paths seen in recent sessions.
+  context-loop          Run a tightened guard snapshot and write loop-breaking rules to .prismo/loop-breaker.md.
+  long-session-buildup  Generate scoped context packs and a fresh-session restart routine in .prismo/session-restart.md.
+  auto                  Let the planner score recent sessions, pick the top cause, and run its repair.
+
+Examples:
+  prismo repair auto
+  prismo repair auto --dry-run
+  prismo repair repeated-file-reads
+  prismo repair tool-output-flood -- npm test
+  prismo repair generated-artifacts --json
+  prismo repair context-loop --budget 400k
+  prismo repair long-session-buildup --scope frontend
+
+Output:
+  Runs the targeted repair for one waste cause instead of the generic doctor flow.
+  These are the same executors the workspace agent uses when a queued action carries a targetCause.
+  "auto" applies cooldowns and verdict feedback from .prismo/repair-state.json: a repair that came back
+  no-change or regressed escalates to an aggressive tier (adds a context firewall policy and tighter budgets);
+  a cause that already failed both tiers is held for review instead of being retried forever.
+  --dry-run with auto prints the planner decision without executing.
+  --tier aggressive forces the stronger repair; cloud-queued actions carry it automatically after a no-change/regressed verdict.
+  Repairs only write .prismo/ files and append ignore rules with backups; they never overwrite CLAUDE.md, AGENTS.md, .gitignore, or source code.`,
   watch: `Prismo Watch
 
 Usage:
@@ -492,7 +525,7 @@ Output:
   agent: `PrismoDev Agent
 
 Usage:
-  prismo agent [--json] [--once] [--watch] [--open] [--no-detect] [--no-sync] [--interval N] [--sync-interval N] [--limit N] [--mode MODE] [path]
+  prismo agent [--json] [--once] [--watch] [--open] [--no-detect] [--no-planner] [--no-sync] [--interval N] [--sync-interval N] [--planner-interval N] [--limit N] [--mode MODE] [path]
 
 Modes:
   observe    Watch and report actions without executing. No changes made.
@@ -511,6 +544,8 @@ Examples:
 Options:
   --open        Open the Prismo workspace in the browser on start.
   --no-detect   Skip the initial auto-detect scan on first poll.
+  --no-planner  Disable the self-repair planner (cause scoring, cooldowns, tier escalation).
+  --planner-interval N  Seconds between self-repair planner runs in watch mode (default 600).
   --no-sync     Keep watch mode from continuously syncing aggregate telemetry.
 
 Output:
@@ -520,6 +555,10 @@ Output:
   Sends heartbeat to Prismo Cloud on each poll and syncs aggregate telemetry on a controlled interval so the dashboard stays fresh.
   Handles SIGINT/SIGTERM gracefully and marks the agent offline before exiting.
   Supported actions are doctor, sync, guard, context/optimize, and shield with a conservative command allowlist.
+  Actions queued with a targetCause run cause-specific repair executors instead of the generic command; see prismo repair --help.
+  In autopilot the self-repair planner also runs on its own interval: it scores waste causes from local sessions,
+  repairs the top cause above threshold, judges the result against later sessions, and escalates or backs off accordingly.
+  In observe/suggest modes the planner only reports what it would repair.
   Agent does not upload prompts, source code, file contents, stdout, stderr, or full command logs.`,
   ci: `Prismo CI
 

package/lib/prismo-dev/repair-executors.js

@@ -0,0 +1,543 @@
+module.exports = function createRepairExecutors(deps) {
+  const {
+    fs,
+    path,
+    NPX_COMMAND,
+    runDoctor,
+    runOptimize,
+    runGuard,
+    runShield,
+    runFirewall,
+    getUsageSummary,
+    appendIgnoreSuggestions,
+  } = deps;
+
+  const REPAIR_CAUSES = [
+    "repeated-file-reads",
+    "tool-output-flood",
+    "generated-artifacts",
+    "context-loop",
+    "long-session-buildup",
+  ];
+
+  const SAFE_SHIELD_COMMANDS = new Set(["npm", "pnpm", "yarn", "bun", "npx", "pytest", "python", "python3", "node"]);
+  const EXPECTED_REPEATED_PATHS = new Set(["claude.md", "agents.md", "readme.md"]);
+
+  function nowIso() {
+    return new Date().toISOString();
+  }
+
+  function noopProgress() {
+    return Promise.resolve();
+  }
+
+  function writeRepairFile(root, name, contents) {
+    const relPath = path.join(".prismo", name);
+    const fullPath = path.join(root, relPath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, contents, "utf8");
+    return relPath;
+  }
+
+  function collectSessions(root, limit) {
+    try {
+      const summary = getUsageSummary({ tool: "all", cwd: root, limit: limit || 5 });
+      return summary.sessions || [];
+    } catch {
+      return [];
+    }
+  }
+
+  function aggregateEntries(sessions, pick) {
+    const totals = new Map();
+    for (const session of sessions) {
+      for (const entry of pick(session) || []) {
+        if (!entry || !entry.value) continue;
+        totals.set(entry.value, (totals.get(entry.value) || 0) + Number(entry.count || 0));
+      }
+    }
+    return Array.from(totals, ([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count);
+  }
+
+  function isExpectedRepeatedPath(value) {
+    const normalized = String(value || "").trim().toLowerCase();
+    return EXPECTED_REPEATED_PATHS.has(normalized) || normalized.endsWith("/readme.md");
+  }
+
+  function parseSafeCommandArgs(command) {
+    const parts = String(command || "").trim().split(/\s+/).filter(Boolean);
+    const separatorIndex = parts.indexOf("--");
+    if (separatorIndex < 0) return null;
+    const commandArgs = parts.slice(separatorIndex + 1);
+    if (!commandArgs.length) return null;
+    if (!SAFE_SHIELD_COMMANDS.has(commandArgs[0])) return null;
+    if (commandArgs.some((arg) => /[;&|`$<>]/.test(arg))) return null;
+    return commandArgs;
+  }
+
+  function repairTier(helpers) {
+    return helpers.options && helpers.options.tier === "aggressive" ? "aggressive" : "mild";
+  }
+
+  // Aggressive tier adds a context firewall policy on top of the mild repair,
+  // so the cause is fenced off by an allow/block file instead of guidance only.
+  function applyAggressiveFirewall(root, cause) {
+    if (!runFirewall) return [];
+    try {
+      const firewall = runFirewall(root, { task: cause, dryRun: false });
+      return firewall.generatedFiles || [];
+    } catch {
+      return [];
+    }
+  }
+
+  function parseScope(action, helpers) {
+    if (helpers.options && helpers.options.scope) return helpers.options.scope;
+    const args = helpers.parsed ? helpers.parsed.args : String(action.command || "").trim().split(/\s+/).slice(1);
+    const scope = (args || []).find((arg) => arg && !arg.startsWith("-"));
+    return ["frontend", "backend"].includes(String(scope || "").toLowerCase()) ? String(scope).toLowerCase() : null;
+  }
+
+  function looksLikeIgnoreRule(value) {
+    const rule = String(value || "").trim();
+    if (!rule || rule.length > 200) return false;
+    if (rule.startsWith("/") || rule.startsWith("-") || rule.includes("..")) return false;
+    return /^[A-Za-z0-9_.*/@-]+$/.test(rule);
+  }
+
+  function renderHotFilesGuide(hotPaths, contextFile) {
+    return [
+      "# Prismo Repair: Repeated File Reads",
+      "",
+      "These files were read repeatedly across recent coding-agent sessions.",
+      "Read each one once, then rely on the compact context packs below instead of re-opening the file.",
+      "",
+      "## Hot Files",
+      "",
+      ...(hotPaths.length
+        ? hotPaths.map((entry) => `- ${entry.value} (${entry.count} reads)`)
+        : ["- No repeated reads detected in recent sessions."]),
+      "",
+      "## Session Rules",
+      "",
+      `- Start sessions from ${contextFile || ".prismo/architecture-summary.md"} instead of broad exploration.`,
+      "- Quote the relevant section from a context pack instead of re-reading a hot file.",
+      "- If a hot file changed during the session, re-read only the changed region.",
+      "",
+    ].join("\n");
+  }
+
+  function renderNoisyCommandsGuide(noisyCommands, shieldedRun) {
+    return [
+      "# Prismo Repair: Tool-Output Flood",
+      "",
+      "These commands repeatedly flooded agent context with raw output.",
+      `Run them through \`${NPX_COMMAND} shield -- <command>\` so the full output stays on disk and only a compact summary enters context.`,
+      "",
+      "## Noisy Commands",
+      "",
+      ...(noisyCommands.length
+        ? noisyCommands.map((entry) => `- \`${entry.value}\` (${entry.count} runs) -> \`${NPX_COMMAND} shield -- ${entry.value}\``)
+        : ["- No repeated noisy commands detected in recent sessions."]),
+      "",
+      ...(shieldedRun
+        ? [
+            "## Last Shielded Run",
+            "",
+            `- Command: \`${shieldedRun.command}\``,
+            `- Exit code: ${shieldedRun.exitCode}`,
+            shieldedRun.runDir ? `- Full output stored in: ${shieldedRun.runDir}` : null,
+            "",
+          ].filter((line) => line !== null)
+        : []),
+      "## Session Rules",
+      "",
+      "- Never paste full test, build, or install output into the conversation.",
+      "- Use shield summaries; search stored runs with `shield search` when details are needed.",
+      "",
+    ].join("\n");
+  }
+
+  function renderLoopBreakerGuide(repeatedCommands, loopSessionCount) {
+    return [
+      "# Prismo Repair: Context Loop",
+      "",
+      loopSessionCount > 0
+        ? `${loopSessionCount} recent session(s) showed loop behavior: the same command retried with growing context.`
+        : "No active loop detected, but guardrails below prevent retry loops from building context waste.",
+      "",
+      "## Repeated Commands",
+      "",
+      ...(repeatedCommands.length
+        ? repeatedCommands.map((entry) => `- \`${entry.value}\` (${entry.count} runs)`)
+        : ["- No repeated commands detected in recent sessions."]),
+      "",
+      "## Loop-Breaking Rules",
+      "",
+      "- After 2 failed attempts of the same command, stop and change the approach instead of retrying.",
+      `- Route retry-heavy commands through \`${NPX_COMMAND} shield -- <command>\` so each retry costs a summary, not full output.`,
+      "- If the session keeps circling, start a fresh session from the .prismo context packs and state what already failed.",
+      "- Follow .prismo/live-guardrails.md while the session is active.",
+      "",
+    ].join("\n");
+  }
+
+  function renderSessionRestartGuide(scope, starterPrompt, heavySessionCount) {
+    return [
+      "# Prismo Repair: Long-Session Buildup",
+      "",
+      heavySessionCount > 0
+        ? `${heavySessionCount} recent session(s) carried High/Medium context risk from accumulated history.`
+        : "Recent sessions look healthy; the restart routine below keeps them that way.",
+      "",
+      "## Restart Routine",
+      "",
+      "- Split work at task boundaries: one task, one session.",
+      `- Start each new session from the scoped context pack${scope ? ` for ${scope}` : ""} instead of carrying the old conversation forward.`,
+      "- When a session crosses ~60% of its budget, finish the current task and restart.",
+      "",
+      ...(starterPrompt
+        ? ["## Paste-Ready Starter Prompt", "", "```", starterPrompt, "```", ""]
+        : []),
+    ].join("\n");
+  }
+
+  // Repeated file reads: refresh ignore rules and context packs via doctor,
+  // then map the hot files into a guide agents can read instead of the files.
+  async function repairRepeatedFileReads(action, root, helpers = {}) {
+    const progress = helpers.progress || noopProgress;
+    const options = helpers.options || {};
+    const startedAt = nowIso();
+
+    await progress("analyzing", "Measuring repeated file reads in recent sessions");
+    const sessions = collectSessions(root, options.limit || 5);
+    const hotPaths = aggregateEntries(sessions, (session) => session.repeatedPathMentions)
+      .filter((entry) => !isExpectedRepeatedPath(entry.value))
+      .slice(0, 10);
+
+    await progress("fixing", hotPaths.length
+      ? `Found ${hotPaths.length} hot file(s); refreshing ignore rules and context packs`
+      : "No hot files found; refreshing ignore rules and context packs as prevention");
+    const doctor = runDoctor(root, { limit: options.limit || 3, applySuggestions: true, json: true });
+    const generatedFiles = doctor.generatedFiles || [];
+    const guidePath = writeRepairFile(root, "hot-files.md", renderHotFilesGuide(hotPaths, doctor.contextFile));
+    const tier = repairTier(helpers);
+    const firewallFiles = tier === "aggressive" ? applyAggressiveFirewall(root, "repeated-file-reads") : [];
+
+    await progress("done", `Mapped ${hotPaths.length} hot file(s) into ${guidePath}`);
+    return {
+      status: "completed",
+      statusMessage: (hotPaths.length
+        ? `Repaired repeated file reads: ${hotPaths.length} hot file(s) mapped into ${guidePath}; context packs refreshed so agents read summaries once.`
+        : `No repeated-read hot files detected; refreshed ignore rules and context packs, and wrote ${guidePath} as prevention.`)
+        + (firewallFiles.length ? " Aggressive tier: context firewall policy added." : ""),
+      result: {
+        command: "repair",
+        targetCause: "repeated-file-reads",
+        tier,
+        startedAt,
+        completedAt: nowIso(),
+        hotPaths,
+        fixActions: doctor.fixActions || [],
+        generatedFiles: [...generatedFiles, guidePath, ...firewallFiles],
+        score: doctor.after && typeof doctor.after.score === "number" ? doctor.after.score : null,
+      },
+    };
+  }
+
+  // Tool-output flood: stage the noisy commands behind shield and, when the
+  // action carries a safe command, run it shielded so output stays on disk.
+  async function repairToolOutputFlood(action, root, helpers = {}) {
+    const progress = helpers.progress || noopProgress;
+    const options = helpers.options || {};
+    const startedAt = nowIso();
+
+    await progress("analyzing", "Finding commands that flood agent context");
+    const sessions = collectSessions(root, options.limit || 5);
+    const noisyCommands = aggregateEntries(sessions, (session) => session.repeatedCommands).slice(0, 8);
+
+    const commandArgs = Array.isArray(options.commandArgs) && options.commandArgs.length
+      ? (SAFE_SHIELD_COMMANDS.has(options.commandArgs[0]) && !options.commandArgs.some((arg) => /[;&|`$<>]/.test(arg)) ? options.commandArgs : null)
+      : parseSafeCommandArgs(action.command);
+
+    let shieldedRun = null;
+    if (commandArgs) {
+      await progress("shielding", `Running shielded command: ${commandArgs.join(" ")}`);
+      const shield = runShield(root, commandArgs);
+      shieldedRun = {
+        command: commandArgs.join(" "),
+        exitCode: shield.exitCode,
+        summary: shield.summary || null,
+        runDir: shield.runDir || null,
+      };
+    }
+
+    const guidePath = writeRepairFile(root, "noisy-commands.md", renderNoisyCommandsGuide(noisyCommands, shieldedRun));
+    const tier = repairTier(helpers);
+    const firewallFiles = tier === "aggressive" ? applyAggressiveFirewall(root, "tool-output-flood") : [];
+    await progress("done", shieldedRun
+      ? `Shielded run stored; ${noisyCommands.length} noisy command(s) staged in ${guidePath}`
+      : `${noisyCommands.length} noisy command(s) staged in ${guidePath}`);
+
+    const statusMessage = (shieldedRun
+      ? `Repaired tool-output flood: ran \`${shieldedRun.command}\` shielded (exit ${shieldedRun.exitCode}); full output stays on disk and ${guidePath} routes noisy commands through shield.`
+      : `Repaired tool-output flood: staged ${noisyCommands.length} noisy command(s) behind shield in ${guidePath}. Queue a \`shield -- <command>\` action to capture a run.`)
+      + (firewallFiles.length ? " Aggressive tier: context firewall policy added." : "");
+
+    return {
+      status: "completed",
+      statusMessage,
+      result: {
+        command: "repair",
+        targetCause: "tool-output-flood",
+        tier,
+        startedAt,
+        completedAt: nowIso(),
+        noisyCommands,
+        shieldedRun,
+        generatedFiles: [guidePath, ...firewallFiles],
+      },
+    };
+  }
+
+  // Generated artifacts: append ignore rules for scan-detected risks plus the
+  // specific artifact paths observed entering recent sessions.
+  async function repairGeneratedArtifacts(action, root, helpers = {}) {
+    const progress = helpers.progress || noopProgress;
+    const options = helpers.options || {};
+    const startedAt = nowIso();
+
+    await progress("analyzing", "Finding generated artifacts leaking into context");
+    const sessions = collectSessions(root, options.limit || 5);
+    const artifacts = aggregateEntries(sessions, (session) => session.generatedArtifacts).slice(0, 10);
+
+    await progress("fixing", "Appending ignore rules for generated artifacts");
+    const doctor = runDoctor(root, { limit: options.limit || 3, applySuggestions: true, noContextPacks: true, json: true });
+    const fixActions = [...(doctor.fixActions || [])];
+
+    const sessionRules = Array.from(new Set(artifacts.map((entry) => entry.value).filter(looksLikeIgnoreRule)));
+    if (sessionRules.length) {
+      const hasClaudeIgnore = fs.existsSync(path.join(root, ".claudeignore"));
+      const hasCursorIgnore = fs.existsSync(path.join(root, ".cursorignore"));
+      fixActions.push(...appendIgnoreSuggestions({
+        root,
+        hasClaudeIgnore,
+        recommendedClaudeIgnore: sessionRules,
+        missingClaudeIgnoreSuggestions: sessionRules,
+        hasCursorIgnore,
+        recommendedCursorIgnore: sessionRules,
+        missingCursorIgnoreSuggestions: sessionRules,
+      }));
+    }
+
+    const tier = repairTier(helpers);
+    const firewallFiles = tier === "aggressive" ? applyAggressiveFirewall(root, "generated-artifacts") : [];
+
+    await progress("done", `Ignore rules updated; ${artifacts.length} session-observed artifact(s) covered`);
+    return {
+      status: "completed",
+      statusMessage: (artifacts.length
+        ? `Repaired generated artifacts: ignore rules now cover ${artifacts.length} artifact path(s) seen in recent sessions plus scan-detected build output.`
+        : "No artifact mentions found in recent sessions; refreshed scan-detected ignore rules as prevention.")
+        + (firewallFiles.length ? " Aggressive tier: context firewall policy added." : ""),
+      result: {
+        command: "repair",
+        targetCause: "generated-artifacts",
+        tier,
+        startedAt,
+        completedAt: nowIso(),
+        artifacts,
+        fixActions,
+        generatedFiles: firewallFiles,
+        score: doctor.after && typeof doctor.after.score === "number" ? doctor.after.score : null,
+      },
+    };
+  }
+
+  // Context loop: run a guard snapshot with a tighter budget and write a
+  // loop-breaker guide built from the actual repeated commands.
+  async function repairContextLoop(action, root, helpers = {}) {
+    const progress = helpers.progress || noopProgress;
+    const options = helpers.options || {};
+    const startedAt = nowIso();
+
+    await progress("analyzing", "Looking for retry loops in recent sessions");
+    const sessions = collectSessions(root, options.limit || 5);
+    const loopSessionCount = sessions.filter((session) => session.loopSuspicion).length;
+    const repeatedCommands = aggregateEntries(sessions, (session) => session.repeatedCommands).slice(0, 8);
+
+    const tier = repairTier(helpers);
+    await progress("guarding", "Running guard snapshot with a tightened token budget");
+    const guard = await runGuard(root, {
+      tool: "all",
+      limit: options.limit || 5,
+      tokenBudget: options.tokenBudget || (tier === "aggressive" ? 250000 : 400000),
+      noSync: false,
+      watch: false,
+    });
+
+    const guidePath = writeRepairFile(root, "loop-breaker.md", renderLoopBreakerGuide(repeatedCommands, loopSessionCount));
+    const firewallFiles = tier === "aggressive" ? applyAggressiveFirewall(root, "context-loop") : [];
+    const eventCount = guard.events ? guard.events.length : 0;
+    await progress("done", `Guard recorded ${eventCount} event(s); loop-breaker rules written to ${guidePath}`);
+
+    return {
+      status: "completed",
+      statusMessage: (loopSessionCount > 0
+        ? `Repaired context loop: ${loopSessionCount} looping session(s) found; guard tightened and loop-breaker rules written to ${guidePath}.`
+        : `No active loop found; guard tightened and loop-breaker rules written to ${guidePath} as prevention.`)
+        + (firewallFiles.length ? " Aggressive tier: context firewall policy added and budget tightened." : ""),
+      result: {
+        command: "repair",
+        targetCause: "context-loop",
+        tier,
+        startedAt,
+        completedAt: nowIso(),
+        loopSessions: loopSessionCount,
+        repeatedCommands,
+        guardEvents: eventCount,
+        generatedFiles: [guidePath, ...firewallFiles],
+      },
+    };
+  }
+
+  // Long-session buildup: generate scoped context packs and a restart routine
+  // so new sessions start small instead of inheriting stale history.
+  async function repairLongSessionBuildup(action, root, helpers = {}) {
+    const progress = helpers.progress || noopProgress;
+    const options = helpers.options || {};
+    const startedAt = nowIso();
+
+    await progress("analyzing", "Checking recent sessions for context buildup");
+    const sessions = collectSessions(root, options.limit || 5);
+    const heavySessionCount = sessions.filter((session) => session.contextRisk === "High" || session.contextRisk === "Medium").length;
+
+    const scope = parseScope(action, helpers);
+    await progress("generating", `Generating ${scope ? `${scope} ` : ""}context packs for fresh-session starts`);
+    const optimize = runOptimize(root, { scope });
+    const generatedFiles = optimize.generatedFiles || [];
+    const guidePath = writeRepairFile(root, "session-restart.md", renderSessionRestartGuide(optimize.scope || scope, optimize.starterPrompt, heavySessionCount));
+    const tier = repairTier(helpers);
+    const firewallFiles = tier === "aggressive" ? applyAggressiveFirewall(root, "long-session-buildup") : [];
+
+    await progress("done", `Generated ${generatedFiles.length} context file(s); restart routine in ${guidePath}`);
+    return {
+      status: "completed",
+      statusMessage: (heavySessionCount > 0
+        ? `Repaired long-session buildup: ${heavySessionCount} heavy session(s) found; scoped context packs and a restart routine are in place so new sessions start small.`
+        : `Recent sessions look healthy; generated scoped context packs and a restart routine in ${guidePath} to keep buildup down.`)
+        + (firewallFiles.length ? " Aggressive tier: context firewall policy added." : ""),
+      result: {
+        command: "repair",
+        targetCause: "long-session-buildup",
+        tier,
+        startedAt,
+        completedAt: nowIso(),
+        heavySessions: heavySessionCount,
+        scope: optimize.scope || scope,
+        starterPrompt: optimize.starterPrompt || null,
+        generatedFiles: [...generatedFiles, guidePath, ...firewallFiles],
+      },
+    };
+  }
+
+  const executors = {
+    "repeated-file-reads": repairRepeatedFileReads,
+    "tool-output-flood": repairToolOutputFlood,
+    "generated-artifacts": repairGeneratedArtifacts,
+    "context-loop": repairContextLoop,
+    "long-session-buildup": repairLongSessionBuildup,
+  };
+
+  function forCause(cause) {
+    return executors[String(cause || "").trim().toLowerCase()] || null;
+  }
+
+  async function runRepair(rootDir = process.cwd(), cause, options = {}) {
+    const root = path.resolve(rootDir);
+    const executor = forCause(cause);
+    if (!executor) {
+      return {
+        schemaVersion: 1,
+        command: "repair",
+        cause: cause || null,
+        status: "failed",
+        statusMessage: `Unknown repair cause: ${cause || "(none)"}. Valid causes: ${REPAIR_CAUSES.join(", ")}.`,
+        result: null,
+        generatedAt: nowIso(),
+      };
+    }
+    const normalizedCause = String(cause).trim().toLowerCase();
+    const action = {
+      id: null,
+      actionType: "repair",
+      command: `${NPX_COMMAND} repair ${normalizedCause}${options.commandArgs && options.commandArgs.length ? ` -- ${options.commandArgs.join(" ")}` : ""}`,
+      label: `Repair ${normalizedCause}`,
+      targetCause: normalizedCause,
+    };
+    const outcome = await executor(action, root, { options });
+    return {
+      schemaVersion: 1,
+      command: "repair",
+      cause: normalizedCause,
+      status: outcome.status,
+      statusMessage: outcome.statusMessage,
+      result: outcome.result,
+      generatedAt: nowIso(),
+    };
+  }
+
+  function renderRepairTerminal(report) {
+    const lines = [];
+    lines.push("");
+    lines.push("PrismoDev Repair");
+    lines.push("");
+    lines.push(`Cause: ${report.cause || "unknown"}`);
+    lines.push(`Status: ${report.status}`);
+    if (report.statusMessage) lines.push(report.statusMessage);
+    const result = report.result || {};
+    if (result.hotPaths && result.hotPaths.length) {
+      lines.push("");
+      lines.push("Hot files:");
+      result.hotPaths.forEach((entry) => lines.push(`- ${entry.value} (${entry.count} reads)`));
+    }
+    if (result.noisyCommands && result.noisyCommands.length) {
+      lines.push("");
+      lines.push("Noisy commands:");
+      result.noisyCommands.forEach((entry) => lines.push(`- ${entry.value} (${entry.count} runs)`));
+    }
+    if (result.artifacts && result.artifacts.length) {
+      lines.push("");
+      lines.push("Artifacts seen in sessions:");
+      result.artifacts.forEach((entry) => lines.push(`- ${entry.value} (${entry.count} mentions)`));
+    }
+    if (result.repeatedCommands && result.repeatedCommands.length) {
+      lines.push("");
+      lines.push("Repeated commands:");
+      result.repeatedCommands.forEach((entry) => lines.push(`- ${entry.value} (${entry.count} runs)`));
+    }
+    if (result.fixActions && result.fixActions.length) {
+      lines.push("");
+      lines.push("Fixes:");
+      result.fixActions.forEach((item) => lines.push(`- ${item}`));
+    }
+    if (result.generatedFiles && result.generatedFiles.length) {
+      lines.push("");
+      lines.push("Generated:");
+      result.generatedFiles.forEach((file) => lines.push(`- ${file}`));
+    }
+    if (report.status === "failed" && !result.generatedFiles) {
+      lines.push("");
+      lines.push("Valid causes:");
+      REPAIR_CAUSES.forEach((item) => lines.push(`- ${item}`));
+    }
+    return lines.join("\n");
+  }
+
+  return {
+    REPAIR_CAUSES,
+    forCause,
+    renderRepairTerminal,
+    runRepair,
+  };
+};

package/lib/prismo-dev/repair-planner.js

@@ -0,0 +1,307 @@
+module.exports = function createRepairPlanner(deps) {
+  const {
+    fs,
+    path,
+    NPX_COMMAND,
+    getUsageSummary,
+    estimateWaste,
+    repairExecutors,
+  } = deps;
+
+  // Decision thresholds. Verdict math mirrors the backend's
+  // _measure_repair_impact (14-day baseline, >=2 post-repair sessions,
+  // 0.01 waste-rate epsilon) so local and cloud verdicts agree.
+  const DEFAULTS = {
+    sessionLimit: 10,
+    minWastedTokens: 15000,
+    minWasteRate: 0.05,
+    cooldownMs: 6 * 60 * 60 * 1000,
+    minSessionsToJudge: 2,
+    baselineDays: 14,
+    rateEpsilon: 0.01,
+    historyLimit: 20,
+  };
+
+  function nowIso() {
+    return new Date().toISOString();
+  }
+
+  function statePath(root) {
+    return path.join(root, ".prismo", "repair-state.json");
+  }
+
+  function readState(root) {
+    try {
+      const raw = fs.readFileSync(statePath(root), "utf8");
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === "object" ? { causes: {}, history: [], ...parsed } : { causes: {}, history: [] };
+    } catch {
+      return { causes: {}, history: [] };
+    }
+  }
+
+  function writeState(root, state) {
+    const filePath = statePath(root);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  }
+
+  function sessionStamp(session) {
+    const value = session.updatedAt || session.startedAt || null;
+    const parsed = value ? Date.parse(value) : NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  function analyzeSessions(root, options = {}) {
+    let sessions = [];
+    try {
+      const summary = getUsageSummary({ tool: "all", cwd: root, limit: options.sessionLimit || DEFAULTS.sessionLimit });
+      sessions = summary.sessions || [];
+    } catch {
+      sessions = [];
+    }
+    return sessions
+      .map((session) => {
+        const stamp = sessionStamp(session);
+        if (stamp === null) return null;
+        const waste = estimateWaste(session);
+        return {
+          stamp,
+          tokens: Number(waste.tokens || 0),
+          wastedTokens: Number(waste.wastedTokens || 0),
+          topCause: waste.topCause,
+        };
+      })
+      .filter(Boolean);
+  }
+
+  function scoreCauses(analyzed) {
+    const totals = new Map();
+    let observedTokens = 0;
+    for (const session of analyzed) {
+      observedTokens += session.tokens;
+      if (!session.topCause || session.topCause === "low-signal") continue;
+      const entry = totals.get(session.topCause) || { cause: session.topCause, wastedTokens: 0, sessions: 0 };
+      entry.wastedTokens += session.wastedTokens;
+      entry.sessions += 1;
+      totals.set(session.topCause, entry);
+    }
+    return Array.from(totals.values())
+      .map((entry) => ({
+        ...entry,
+        wasteRate: observedTokens > 0 ? Math.round((entry.wastedTokens / observedTokens) * 10000) / 10000 : 0,
+      }))
+      .sort((a, b) => b.wastedTokens - a.wastedTokens);
+  }
+
+  // Local mirror of the backend's repair verification: compare the cause's
+  // waste rate in sessions before vs. after the last repair.
+  function judgeRepair(cause, repairedAtMs, analyzed, config) {
+    const baselineStart = repairedAtMs - config.baselineDays * 24 * 60 * 60 * 1000;
+    const before = analyzed.filter((s) => s.stamp <= repairedAtMs && s.stamp >= baselineStart);
+    const after = analyzed.filter((s) => s.stamp > repairedAtMs);
+
+    const causeWasted = (group) => group.reduce((sum, s) => sum + (s.topCause === cause ? s.wastedTokens : 0), 0);
+    const observed = (group) => group.reduce((sum, s) => sum + s.tokens, 0);
+
+    const observedAfter = observed(after);
+    const observedBefore = observed(before);
+    const verdict = {
+      cause,
+      sessionsBefore: before.length,
+      sessionsAfter: after.length,
+      wasteRateBefore: observedBefore > 0 ? Math.round((causeWasted(before) / observedBefore) * 10000) / 10000 : null,
+      wasteRateAfter: observedAfter > 0 ? Math.round((causeWasted(after) / observedAfter) * 10000) / 10000 : null,
+      status: "measuring",
+      judgedAt: nowIso(),
+    };
+    if (after.length < config.minSessionsToJudge || observedAfter <= 0) return verdict;
+    if (!before.length || observedBefore <= 0) {
+      verdict.status = "no-baseline";
+      return verdict;
+    }
+    const delta = verdict.wasteRateBefore - verdict.wasteRateAfter;
+    if (delta > config.rateEpsilon) verdict.status = "improved";
+    else if (delta < -config.rateEpsilon) verdict.status = "regressed";
+    else verdict.status = "no-change";
+    return verdict;
+  }
+
+  // Decide what (if anything) to repair next. Pure read: does not execute
+  // or modify state, so observe/suggest modes can call it safely.
+  function plan(root, options = {}) {
+    const config = { ...DEFAULTS, ...options };
+    const analyzed = analyzeSessions(root, config);
+    const causes = scoreCauses(analyzed);
+    const state = readState(root);
+    const now = Date.now();
+    const skipped = [];
+    let decision = null;
+
+    for (const scored of causes) {
+      if (scored.wastedTokens < config.minWastedTokens || scored.wasteRate < config.minWasteRate) {
+        skipped.push({ cause: scored.cause, reason: "below-threshold" });
+        continue;
+      }
+      if (!repairExecutors.forCause(scored.cause)) {
+        skipped.push({ cause: scored.cause, reason: "no-executor" });
+        continue;
+      }
+      const entry = state.causes[scored.cause] || null;
+      let verdict = null;
+      let tier = "mild";
+      if (entry && entry.lastRepairAt) {
+        const repairedAtMs = Date.parse(entry.lastRepairAt);
+        if (Number.isFinite(repairedAtMs)) {
+          if (now - repairedAtMs < config.cooldownMs) {
+            skipped.push({ cause: scored.cause, reason: "cooldown" });
+            continue;
+          }
+          verdict = judgeRepair(scored.cause, repairedAtMs, analyzed, config);
+          if (verdict.status === "measuring") {
+            skipped.push({ cause: scored.cause, reason: "measuring", verdict });
+            continue;
+          }
+          if (verdict.status === "no-change" || verdict.status === "regressed") {
+            if (entry.lastTier === "aggressive") {
+              // Both tiers tried without improvement; stop auto-repairing
+              // this cause until a human looks at it or sessions change.
+              skipped.push({ cause: scored.cause, reason: "needs-review", verdict });
+              continue;
+            }
+            tier = "aggressive";
+          }
+        }
+      }
+      if (!decision) {
+        decision = {
+          cause: scored.cause,
+          tier,
+          wastedTokens: scored.wastedTokens,
+          wasteRate: scored.wasteRate,
+          previousVerdict: verdict ? verdict.status : null,
+          reason: verdict && tier === "aggressive"
+            ? `Last ${entry.lastTier} repair came back ${verdict.status}; escalating to aggressive.`
+            : `${scored.cause} is the top waste cause (${scored.wastedTokens.toLocaleString()} tokens, ${(scored.wasteRate * 100).toFixed(1)}% of observed).`,
+        };
+      } else {
+        skipped.push({ cause: scored.cause, reason: "lower-priority" });
+      }
+    }
+
+    return {
+      generatedAt: nowIso(),
+      sessionsAnalyzed: analyzed.length,
+      causes,
+      decision,
+      skipped,
+    };
+  }
+
+  async function runPlannerOnce(rootDir = process.cwd(), options = {}) {
+    const root = path.resolve(rootDir);
+    const config = { ...DEFAULTS, ...options };
+    const planResult = plan(root, config);
+    const report = {
+      schemaVersion: 1,
+      command: "repair-planner",
+      ...planResult,
+      executed: false,
+      outcome: null,
+    };
+    if (!planResult.decision || options.execute === false) return report;
+
+    const { cause, tier } = planResult.decision;
+    const executor = repairExecutors.forCause(cause);
+    const action = {
+      id: null,
+      actionType: "repair",
+      command: `${NPX_COMMAND} repair ${cause}`,
+      label: `Auto-repair ${cause} (${tier})`,
+      targetCause: cause,
+    };
+    let outcome;
+    try {
+      outcome = await executor(action, root, { options: { ...options, tier } });
+    } catch (error) {
+      outcome = {
+        status: "failed",
+        statusMessage: `Repair executor failed: ${error && error.message ? error.message : String(error)}`,
+        result: null,
+      };
+    }
+
+    const state = readState(root);
+    const previous = state.causes[cause] || { attempts: 0 };
+    state.causes[cause] = {
+      ...previous,
+      lastRepairAt: nowIso(),
+      lastTier: tier,
+      lastStatus: outcome.status,
+      attempts: Number(previous.attempts || 0) + 1,
+      lastVerdict: planResult.decision.previousVerdict || previous.lastVerdict || null,
+    };
+    state.history = [
+      { at: nowIso(), cause, tier, status: outcome.status, wastedTokens: planResult.decision.wastedTokens },
+      ...(state.history || []),
+    ].slice(0, config.historyLimit);
+    writeState(root, state);
+
+    report.executed = outcome.status === "completed";
+    report.outcome = {
+      status: outcome.status,
+      statusMessage: outcome.statusMessage,
+      tier,
+      generatedFiles: (outcome.result && outcome.result.generatedFiles) || [],
+    };
+    return report;
+  }
+
+  function renderPlannerTerminal(report) {
+    const lines = [];
+    lines.push("");
+    lines.push("PrismoDev Repair Planner");
+    lines.push("");
+    lines.push(`Sessions analyzed: ${report.sessionsAnalyzed}`);
+    if (report.causes.length) {
+      lines.push("");
+      lines.push("Waste causes:");
+      report.causes.forEach((entry) => {
+        lines.push(`- ${entry.cause}: ${entry.wastedTokens.toLocaleString()} tokens (${(entry.wasteRate * 100).toFixed(1)}% of observed, ${entry.sessions} session(s))`);
+      });
+    } else {
+      lines.push("No attributable waste causes in recent sessions.");
+    }
+    if (report.decision) {
+      lines.push("");
+      lines.push(`Decision: repair ${report.decision.cause} (${report.decision.tier} tier)`);
+      lines.push(`Why: ${report.decision.reason}`);
+    } else {
+      lines.push("");
+      lines.push("Decision: nothing to repair right now.");
+    }
+    if (report.skipped.length) {
+      lines.push("");
+      lines.push("Held back:");
+      report.skipped.forEach((item) => lines.push(`- ${item.cause}: ${item.reason}`));
+    }
+    if (report.outcome) {
+      lines.push("");
+      lines.push(`Repair: ${report.outcome.status}`);
+      if (report.outcome.statusMessage) lines.push(report.outcome.statusMessage);
+    } else if (report.decision && !report.executed) {
+      lines.push("");
+      lines.push(`Not executed (planning only). Run: ${NPX_COMMAND} repair ${report.decision.cause}`);
+    }
+    return lines.join("\n");
+  }
+
+  return {
+    DEFAULTS,
+    judgeRepair,
+    plan,
+    readState,
+    renderPlannerTerminal,
+    runPlannerOnce,
+  };
+};

package/lib/prismo-dev-scan.js

@@ -272,6 +272,7 @@ const {
 
 const {
   buildSyncPayload,
+  estimateWaste,
   loadConfig,
   renderConnectTerminal,
   renderDisconnectTerminal,
@@ -313,6 +314,37 @@ const {
   loadConfig,
 });
 
+const repairExecutors = require("./prismo-dev/repair-executors")({
+  fs,
+  path,
+  NPX_COMMAND,
+  runDoctor,
+  runOptimize,
+  runGuard,
+  runShield,
+  runFirewall,
+  getUsageSummary,
+  appendIgnoreSuggestions,
+});
+const {
+  REPAIR_CAUSES,
+  renderRepairTerminal,
+  runRepair,
+} = repairExecutors;
+
+const repairPlanner = require("./prismo-dev/repair-planner")({
+  fs,
+  path,
+  NPX_COMMAND,
+  getUsageSummary,
+  estimateWaste,
+  repairExecutors,
+});
+const {
+  renderPlannerTerminal,
+  runPlannerOnce,
+} = repairPlanner;
+
 const {
   renderAgentTerminal,
   runAgent,
@@ -331,6 +363,8 @@ const {
   runShield,
   runOptimize,
   openUrl,
+  repairExecutors,
+  repairPlanner,
 });
 
 const {
@@ -452,6 +486,11 @@ const { runCli } = require("./prismo-dev/cli")({
   runSync,
   renderGuardTerminal,
   runGuard,
+  REPAIR_CAUSES,
+  renderRepairTerminal,
+  runRepair,
+  renderPlannerTerminal,
+  runPlannerOnce,
   renderAgentTerminal,
   runAgent,
   renderConnectorTerminal,
@@ -552,6 +591,11 @@ module.exports = {
   runConnect,
   runDisconnect,
   runGuard,
+  runRepair,
+  renderRepairTerminal,
+  REPAIR_CAUSES,
+  runPlannerOnce,
+  renderPlannerTerminal,
   runConnectorInstall,
   runConnectorStart,
   runConnectorStatus,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",