getprismo 0.1.38 → 0.1.40

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) {
@@ -174,13 +245,41 @@ module.exports = function createAgent(deps) {
     return url;
   }
 
+  async function reportProgress(config, actionId, step, detail, options = {}) {
+    const endpoint = options.progressEndpoint || `${apiBase(config)}/v1/dev/workspace/actions/${actionId}/progress`;
+    try {
+      await requestJson("POST", endpoint, config.token, {
+        step,
+        detail: detail || null,
+        timestamp: new Date().toISOString(),
+      }, options.timeoutMs || 5000);
+    } catch (_) {}
+  }
+
   async function executeAction(action, rootDir, options = {}) {
     const root = repoRoot(path.resolve(rootDir || process.cwd()), action);
     const parsed = parseCommand(action.command);
     const startedAt = new Date().toISOString();
+    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) {
+      return causeExecutor(action, root, { progress, parsed, options });
+    }
 
     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 });
+      const score = result.after?.score ?? result.scan?.score ?? null;
+      const issueCount = result.scan?.issues?.length || 0;
+      const generatedFiles = result.generatedFiles || result.optimize?.generatedFiles || [];
+      if (issueCount > 0) await progress("fixing", `Found ${issueCount} issue${issueCount === 1 ? "" : "s"}, applying fixes`);
+      await progress("done", `Score: ${score}/100, generated ${generatedFiles.length} file${generatedFiles.length === 1 ? "" : "s"}`);
       return {
         status: "completed",
         statusMessage: "Doctor completed and applied safe ignore/context fixes.",
@@ -188,14 +287,16 @@ module.exports = function createAgent(deps) {
           command: "doctor",
           startedAt,
           completedAt: new Date().toISOString(),
-          score: result.after?.score ?? result.scan?.score ?? null,
-          generatedFiles: result.generatedFiles || result.optimize?.generatedFiles || [],
+          score,
+          generatedFiles,
         },
       };
     }
 
     if (parsed.command === "sync" || action.actionType === "sync") {
+      await progress("syncing", "Syncing local telemetry to workspace");
       const result = await runSync(root, { limit: options.limit || 20 });
+      await progress("done", result.synced ? "Sync completed" : "Sync failed");
       return {
         status: result.synced ? "completed" : "failed",
         statusMessage: result.synced ? "Sync completed." : "Sync could not run because this machine is not connected.",
@@ -211,6 +312,7 @@ module.exports = function createAgent(deps) {
     }
 
     if (parsed.command === "guard" || action.actionType === "guard") {
+      await progress("guarding", "Running guardrail snapshot across sessions");
       const result = await runGuard(root, {
         tool: "all",
         limit: options.limit || 5,
@@ -218,6 +320,8 @@ module.exports = function createAgent(deps) {
         noSync: false,
         watch: false,
       });
+      const eventCount = result.events?.length || 0;
+      await progress("done", `Guard complete, ${eventCount} event${eventCount === 1 ? "" : "s"} recorded`);
       return {
         status: "completed",
         statusMessage: "Guard snapshot completed. Start agent watch mode for continuous protection.",
@@ -226,14 +330,17 @@ module.exports = function createAgent(deps) {
           startedAt,
           completedAt: new Date().toISOString(),
           guardRunning: Boolean(result.guardRunning),
-          events: result.events?.length || 0,
+          events: eventCount,
         },
       };
     }
 
     if (parsed.command === "context" || parsed.command === "optimize" || action.actionType === "context") {
       const scope = parsed.args.find((arg) => !arg.startsWith("-")) || null;
+      await progress("generating", `Generating context pack${scope ? ` for ${scope}` : ""}`);
       const result = runOptimize(root, { scope });
+      const generatedFiles = result.generatedFiles || [];
+      await progress("done", `Generated ${generatedFiles.length} file${generatedFiles.length === 1 ? "" : "s"}`);
       return {
         status: "completed",
         statusMessage: "Context pack generated.",
@@ -242,7 +349,7 @@ module.exports = function createAgent(deps) {
           startedAt,
           completedAt: new Date().toISOString(),
           scope,
-          generatedFiles: result.generatedFiles || [],
+          generatedFiles,
         },
       };
     }
@@ -250,13 +357,16 @@ module.exports = function createAgent(deps) {
     if (parsed.command === "shield" || action.actionType === "shield") {
       const commandArgs = parseShieldArgs(parsed.args);
       if (!commandArgs) {
+        await progress("rejected", "Command not on safe allowlist");
         return {
           status: "failed",
           statusMessage: "Shield action was rejected because the command is not on the safe allowlist.",
           result: { command: "shield", rejected: true, reason: "unsafe-shield-command" },
         };
       }
+      await progress("shielding", `Running shielded command: ${commandArgs.join(" ")}`);
       const result = runShield(root, commandArgs);
+      await progress("done", result.exitCode === 0 ? "Command completed" : "Command failed");
       return {
         status: result.exitCode === 0 ? "completed" : "failed",
         statusMessage: result.exitCode === 0 ? "Shielded command completed." : "Shielded command exited with an error.",
@@ -336,11 +446,28 @@ module.exports = function createAgent(deps) {
         status: "running",
         statusMessage: "Running locally through PrismoDev agent.",
       }, options);
-      const result = await executeAction(action, rootDir, options);
+      const result = await executeAction(action, rootDir, { ...options, _config: config });
       await updateAction(config, action.id, result, options);
       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 {
@@ -370,6 +497,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: {
@@ -419,6 +547,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");
@@ -448,10 +595,14 @@ 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();
@@ -479,9 +630,14 @@ module.exports = function createAgent(deps) {
       const now = Date.now();
       const shouldSync = options.noSync !== true && (lastSyncAt === 0 || now - lastSyncAt >= syncIntervalMs);
       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: firstRun && options.autoDetect !== false,
+        autoDetect: shouldDetect,
+        planRepairs: shouldPlan,
         syncTelemetry: shouldSync,
       };
       firstRun = false;
@@ -506,6 +662,7 @@ module.exports = function createAgent(deps) {
     parseCommand,
     renderAgentTerminal,
     reportAutoDetect,
+    reportProgress,
     runAgent,
     runAgentOnce,
     runAutoDetect,

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,
@@ -345,7 +350,7 @@ function createCli(deps) {
           dryRun: rest.includes("--dry-run"),
         });
         result.next = result.connector?.started
-          ? [`${NPX_COMMAND} status`, "Refresh Prismo Workspace"]
+          ? [`${NPX_COMMAND} status`]
           : [`${NPX_COMMAND} connector install`, `${NPX_COMMAND} status`];
       }
       if (result.connected && (rest.includes("--open") || !rest.includes("--no-open"))) {
@@ -424,6 +429,8 @@ function createCli(deps) {
       const json = rest.includes("--json");
       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");
@@ -431,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", "--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,
@@ -439,9 +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,
@@ -756,6 +766,39 @@ 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"]));
+      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");
+      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,
+        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

@@ -405,20 +405,32 @@ module.exports = function createCloudSync(deps) {
   function renderConnectTerminal(result) {
     const lines = [];
     lines.push("");
-    lines.push("PrismoDev Connect");
-    lines.push("");
-    lines.push(`Status: ${result.connected ? "connected" : "token needed"}`);
-    lines.push(`Config: ${result.configPath}`);
-    lines.push(`API: ${result.apiUrl}`);
-    lines.push(`Device: ${result.device.name}`);
-    if (result.connector) {
-      lines.push(`Connector: ${result.connector.started ? "started" : result.connector.installed ? "installed" : "not started"}`);
-      if (result.connector.reason) lines.push(`Connector note: ${result.connector.reason}`);
-      if (result.connector.error) lines.push(`Connector error: ${result.connector.error}`);
+    if (result.connected && result.connector?.started) {
+      lines.push("Prismo agent is running.");
+      lines.push("");
+      lines.push(`Device: ${result.device.name}`);
+      lines.push(`Mode: ${result.connector.mode || "autopilot"}`);
+      lines.push(`Poll: every ${result.connector.interval || 15}s`);
+      lines.push(`Sync: every ${result.connector.syncInterval || 60}s`);
+      lines.push("");
+      lines.push("Your agent will continuously scan, repair, and guard this repo.");
+      lines.push("Open the dashboard to see what it's doing.");
+    } else {
+      lines.push("PrismoDev Connect");
+      lines.push("");
+      lines.push(`Status: ${result.connected ? "connected" : "token needed"}`);
+      lines.push(`Config: ${result.configPath}`);
+      lines.push(`API: ${result.apiUrl}`);
+      lines.push(`Device: ${result.device.name}`);
+      if (result.connector) {
+        lines.push(`Connector: ${result.connector.started ? "started" : result.connector.installed ? "installed" : "not started"}`);
+        if (result.connector.reason) lines.push(`Note: ${result.connector.reason}`);
+        if (result.connector.error) lines.push(`Error: ${result.connector.error}`);
+      }
+      lines.push("");
+      lines.push("Next");
+      result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
     }
-    lines.push("");
-    lines.push("Next");
-    result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
     return lines.join("\n");
   }
 
@@ -484,6 +496,7 @@ module.exports = function createCloudSync(deps) {
   return {
     buildSyncPayload,
     configPath,
+    estimateWaste,
     loadConfig,
     renderConnectTerminal,
     renderDisconnectTerminal,

package/lib/prismo-dev/connector.js

@@ -80,9 +80,10 @@ module.exports = function createConnector(deps) {
     const root = path.resolve(rootDir || process.cwd());
     const interval = Math.max(5, Number(options.interval || 15));
     const syncInterval = Math.max(30, Number(options.syncInterval || 60));
+    const detectInterval = Math.max(60, Number(options.detectInterval || 300));
     const mode = options.mode || "autopilot";
     fs.mkdirSync(connectorDir(), { recursive: true });
-    const command = `${BACKGROUND_COMMAND} agent --watch --interval ${interval} --sync-interval ${syncInterval} --mode ${shellEscape(mode)} ${shellEscape(root)}`;
+    const command = `${BACKGROUND_COMMAND} agent --watch --interval ${interval} --sync-interval ${syncInterval} --detect-interval ${detectInterval} --mode ${shellEscape(mode)} ${shellEscape(root)}`;
     const contents = [
       "#!/bin/sh",
       "set -eu",
@@ -97,6 +98,7 @@ module.exports = function createConnector(deps) {
       root,
       interval,
       syncInterval,
+      detectInterval,
       mode,
       command,
       platform: process.platform,
@@ -104,7 +106,7 @@ module.exports = function createConnector(deps) {
       logPath: logPath(),
       errorLogPath: errorLogPath(),
     });
-    return { root, interval, syncInterval, mode, command };
+    return { root, interval, syncInterval, detectInterval, mode, command };
   }
 
   function writePlist() {

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] [--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,36 @@ 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] [--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.
+  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 +524,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 +543,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 +554,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