runtrim 0.1.18 → 0.1.20

package/dist-cli/runtrim.js

@@ -97,8 +97,45 @@ function getConfigPath(cwd = process.cwd()) {
   return path.join(getConfigDir(cwd), "config.json");
 }
 function getRunsDir(cwd = process.cwd()) {
+  return path.join(getInternalDir(cwd), "runs");
+}
+function getLegacyRunsDir(cwd = process.cwd()) {
   return path.join(getConfigDir(cwd), "runs");
 }
+function getInternalDir(cwd = process.cwd()) {
+  return path.join(getConfigDir(cwd), "internal");
+}
+function getPreviewsDir(cwd = process.cwd()) {
+  return path.join(getInternalDir(cwd), "previews");
+}
+function getLegacyPreviewsDir(cwd = process.cwd()) {
+  return path.join(getConfigDir(cwd), "previews");
+}
+function getRestoresDir(cwd = process.cwd()) {
+  return path.join(getInternalDir(cwd), "restores");
+}
+function getLegacyRestoresDir(cwd = process.cwd()) {
+  return path.join(getConfigDir(cwd), "restores");
+}
+function getContractsArchiveDir(cwd = process.cwd()) {
+  return path.join(getInternalDir(cwd), "contracts-archive");
+}
+function getAgentArchiveDir(cwd = process.cwd()) {
+  return path.join(getInternalDir(cwd), "agent-archive");
+}
+function ensureInternalArtifactDirs(cwd = process.cwd()) {
+  const dirs = [
+    getInternalDir(cwd),
+    getRunsDir(cwd),
+    getPreviewsDir(cwd),
+    getRestoresDir(cwd),
+    getContractsArchiveDir(cwd),
+    getAgentArchiveDir(cwd)
+  ];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+}
 function configExists(cwd = process.cwd()) {
   return fs.existsSync(getConfigPath(cwd));
 }
@@ -1552,35 +1589,38 @@ function saveRun(task, audit, contract, cwd = process.cwd()) {
   return record;
 }
 function loadLatestRun(cwd = process.cwd()) {
-  const runsDir = getRunsDir(cwd);
-  if (!fs3.existsSync(runsDir)) return null;
-  const files = fs3.readdirSync(runsDir).filter((f) => f.endsWith(".json")).map((f) => ({
-    name: f,
-    time: fs3.statSync(path3.join(runsDir, f)).mtime.getTime()
-  })).sort((a, b) => b.time - a.time);
+  const candidateDirs = [getRunsDir(cwd), getLegacyRunsDir(cwd)].filter((dir, idx, arr) => arr.indexOf(dir) === idx);
+  const files = candidateDirs.filter((dir) => fs3.existsSync(dir)).flatMap(
+    (dir) => fs3.readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => ({
+      dir,
+      name: f,
+      time: fs3.statSync(path3.join(dir, f)).mtime.getTime()
+    }))
+  ).sort((a, b) => b.time - a.time);
   if (files.length === 0) return null;
   try {
     return JSON.parse(
-      fs3.readFileSync(path3.join(runsDir, files[0].name), "utf-8")
+      fs3.readFileSync(path3.join(files[0].dir, files[0].name), "utf-8")
     );
   } catch (e) {
     return null;
   }
 }
 function updateRun(runId, updates, cwd = process.cwd()) {
-  const filePath = path3.join(getRunsDir(cwd), `${runId}.json`);
+  const preferredPath = path3.join(getRunsDir(cwd), `${runId}.json`);
+  const legacyPath = path3.join(getLegacyRunsDir(cwd), `${runId}.json`);
+  const filePath = fs3.existsSync(preferredPath) ? preferredPath : legacyPath;
   if (!fs3.existsSync(filePath)) return;
   const existing = JSON.parse(fs3.readFileSync(filePath, "utf-8"));
   fs3.writeFileSync(filePath, JSON.stringify(__spreadValues(__spreadValues({}, existing), updates), null, 2));
 }
 function loadAllRuns(cwd = process.cwd()) {
-  const runsDir = getRunsDir(cwd);
-  if (!fs3.existsSync(runsDir)) return [];
-  return fs3.readdirSync(runsDir).filter((f) => f.endsWith(".json")).map((f) => {
+  const candidateDirs = [getRunsDir(cwd), getLegacyRunsDir(cwd)].filter((dir, idx, arr) => arr.indexOf(dir) === idx);
+  const files = candidateDirs.filter((dir) => fs3.existsSync(dir)).flatMap((dir) => fs3.readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => path3.join(dir, f)));
+  const deduped = [...new Set(files)];
+  return deduped.map((filePath) => {
     try {
-      return JSON.parse(
-        fs3.readFileSync(path3.join(runsDir, f), "utf-8")
-      );
+      return JSON.parse(fs3.readFileSync(filePath, "utf-8"));
     } catch (e) {
       return null;
     }
@@ -2773,7 +2813,7 @@ function writeCanonicalRuntrimMd(cwd = process.cwd(), projectName) {
     "6. After editing, tell the user to run: `runtrim finish`",
     "",
     "---",
-    `Protocol: runtrim init. Updated: ${(/* @__PURE__ */ new Date()).toISOString()}`
+    `Protocol: runtrim start. Updated: ${(/* @__PURE__ */ new Date()).toISOString()}`
   ];
   fs7.writeFileSync(path7.join(cwd, "RUNTRIM.md"), lines.join("\n"), "utf-8");
 }
@@ -2829,7 +2869,7 @@ function archiveContract(cwd, runId) {
   if (!fs7.existsSync(latestPath)) return;
   const content = fs7.readFileSync(latestPath, "utf-8");
   if (content.includes("Status: none")) return;
-  const archiveDir = path7.join(contractsDir, "archive");
+  const archiveDir = getContractsArchiveDir(cwd);
   if (!fs7.existsSync(archiveDir)) fs7.mkdirSync(archiveDir, { recursive: true });
   fs7.writeFileSync(path7.join(archiveDir, `${runId}.md`), content, "utf-8");
 }
@@ -4159,9 +4199,15 @@ async function getPanelState(cwd, monitorMode) {
   let runs = [];
   let latest = null;
   let registry = {
-    version: 1,
+    version: 2,
+    stateVersion: 2,
     plan: "free",
+    machineInstallId: "",
+    createdAt: "",
+    updatedAt: "",
     trackedRepos: [],
+    lastKnownRepo: null,
+    integrity: { algorithm: "sha256-local-seal-v1", seal: "" },
     telemetry: {
       enabled: false,
       anonymousId: ""
@@ -4203,9 +4249,15 @@ async function getPanelState(cwd, monitorMode) {
   } catch (e) {
     warnings.push("global_registry_failed");
     registry = {
-      version: 1,
+      version: 2,
+      stateVersion: 2,
       plan: "free",
+      machineInstallId: "",
+      createdAt: "",
+      updatedAt: "",
       trackedRepos: [],
+      lastKnownRepo: null,
+      integrity: { algorithm: "sha256-local-seal-v1", seal: "" },
       telemetry: {
         enabled: false,
         anonymousId: ""
@@ -4673,7 +4725,7 @@ Before editing code:
 If no active RunTrim contract exists:
 - Do not edit code without one.
 - Ask the user to start a guarded run:
-  runtrim go "<task>"
+  runtrim agent "<task>" --copy
 
 If the task requires leaving the current scope:
 - Stop.
@@ -4769,7 +4821,7 @@ ${BASE_PROTOCOL}
 Before using any tool or executing any command:
 1. Confirm a RunTrim contract is active at .runtrim/contracts/latest.md.
 2. If no active contract exists, do not proceed. Ask for:
-   runtrim go "<task>"
+   runtrim agent "<task>" --copy
 3. Do not call shell commands, write files, or read env vars outside the contract.
 `.trim(),
   custom: `
@@ -4822,7 +4874,7 @@ function getCursorMdcContent() {
     "## If no active contract",
     "",
     "Ask the user to start a guarded run:",
-    '`runtrim go "<task>"`',
+    '`runtrim agent "<task>" --copy`',
     "",
     "Any agent. One run boundary."
   ].join("\n");
@@ -5084,7 +5136,7 @@ Before editing code:
 - If the task touches auth, billing, payments, webhooks, database, middleware,
   env vars, secrets, or subscriptions, stop and require an active RunTrim contract.
   Ask the user to run:
-  runtrim go "<task>"
+  runtrim agent "<task>" --copy
 - For low-risk work (UI polish, copy, docs, isolated component styling):
   Fast Path is allowed if no unfinished changes exist.
   Keep the change minimal.
@@ -5107,7 +5159,7 @@ No active RunTrim contract means no code edits.
 If no active contract exists at .runtrim/contracts/latest.md:
 - Do not edit any file.
 - Ask the user to start a guarded run:
-  runtrim go "<task>"
+  runtrim agent "<task>" --copy
 
 After every editing session:
 - Ask the user to run:
@@ -5121,7 +5173,7 @@ Fast Path is allowed for low and medium risk work.
 
 Critical systems (auth, billing, payments, webhooks, database, middleware,
 env vars, secrets, subscriptions) still require a RunTrim contract:
-  runtrim go "<task>"
+  runtrim agent "<task>" --copy
 
 After any edits:
 - runtrim finish is required before continuing to another task.
@@ -5132,7 +5184,7 @@ RunTrim Auto-guard: Off
 
 Auto-guard is disabled for this project.
 RunTrim can still be used manually:
-  runtrim go "<task>"
+  runtrim agent "<task>" --copy
   runtrim finish
 `.trim();
   }
@@ -5158,7 +5210,7 @@ function saveFastRunRecord(cwd, changedFiles, risk) {
     reportParts.push(`${sensitive.length} sensitive path${sensitive.length === 1 ? "" : "s"} touched.`);
   }
   reportParts.push("No pre-run contract was captured for this run.");
-  const nextSafeAction = changedFiles.length > 0 ? 'Create a contract before the next change: runtrim go "<task>"' : 'Start a guarded run: runtrim go "<task>"';
+  const nextSafeAction = changedFiles.length > 0 ? 'Create a contract before the next change: runtrim agent "<task>" --copy' : 'Start a guarded run: runtrim agent "<task>" --copy';
   const summary = {
     id,
     task,
@@ -5678,7 +5730,7 @@ function recommendProviderRouting(ctx) {
   } else if (route === "split-required") {
     routingReason = "This spans multiple critical systems, so RunTrim should split into audit, implementation, and verification.";
   }
-  let nextCommand = `runtrim go "${ctx.task}"`;
+  let nextCommand = `runtrim agent "${ctx.task}" --copy`;
   if (route === "split-required") {
     nextCommand = "split into:\n1. audit only\n2. implementation only\n3. verification only";
   } else if (route === "preview-only") {
@@ -5700,6 +5752,7 @@ var _a;
 var oraFactory = typeof ora === "function" ? ora : (_a = ora.default) != null ? _a : ora;
 var ACCENT = chalk.hex("#C8901A");
 var GO_ACCENT = chalk.hex("#8B7CFF");
+var RUNTRIM_AGENT_INSTRUCTIONS_VERSION = "2";
 var DIM = chalk.gray;
 var BOLD = chalk.white.bold;
 var program = new Command();
@@ -5835,6 +5888,98 @@ async function copyToClipboardSafe(value) {
 function dedupeFiles(files) {
   return [...new Set(files.filter(Boolean).map((f) => f.replace(/\\/g, "/")))];
 }
+var RUNTRIM_GITIGNORE_BLOCK_START = "# BEGIN RUNTRIM_ARTIFACTS";
+var RUNTRIM_GITIGNORE_BLOCK_END = "# END RUNTRIM_ARTIFACTS";
+function ensureRuntrimReadme(cwd) {
+  const readmePath = path13.join(getConfigDir(cwd), "README.md");
+  const content = [
+    "# RunTrim Local Files",
+    "",
+    "RunTrim stores local metadata in this folder.",
+    "",
+    "Human-facing files:",
+    "- `agent/instructions.md` and `agent/latest.md`",
+    "- `contracts/latest.md`",
+    "- `memory/current.md` and `memory/baseline.md`",
+    "- `mcp/*.json`",
+    "- `config.json`",
+    "",
+    "Internal artifacts:",
+    "- `.runtrim/internal/runs/`",
+    "- `.runtrim/internal/previews/`",
+    "- `.runtrim/internal/restores/`",
+    "- `.runtrim/internal/contracts-archive/`",
+    "- `.runtrim/internal/agent-archive/`",
+    "",
+    "Notes:",
+    "- Artifacts are local-first.",
+    "- Source code is not uploaded by local storage.",
+    "- Restore metadata is path-only and does not store secret contents."
+  ].join("\n");
+  fs13.writeFileSync(readmePath, content + "\n", "utf-8");
+}
+function ensureRuntrimGitignoreGuidance(cwd) {
+  const gitignorePath = path13.join(cwd, ".gitignore");
+  if (!fs13.existsSync(gitignorePath)) return;
+  const desired = [
+    RUNTRIM_GITIGNORE_BLOCK_START,
+    "# RunTrim local artifacts",
+    ".runtrim/internal/",
+    ".runtrim/runs/",
+    ".runtrim/previews/",
+    ".runtrim/restores/",
+    ".runtrim/contracts/archive/",
+    ".runtrim/agent/*.json",
+    RUNTRIM_GITIGNORE_BLOCK_END
+  ].join("\n");
+  const current = fs13.readFileSync(gitignorePath, "utf-8");
+  const start = current.indexOf(RUNTRIM_GITIGNORE_BLOCK_START);
+  const end = current.indexOf(RUNTRIM_GITIGNORE_BLOCK_END);
+  if (start !== -1 && end !== -1 && end > start) {
+    const next = current.slice(0, start).trimEnd() + "\n\n" + desired + "\n" + current.slice(end + RUNTRIM_GITIGNORE_BLOCK_END.length).replace(/^\n+/, "\n");
+    if (next !== current) fs13.writeFileSync(gitignorePath, next, "utf-8");
+    return;
+  }
+  if (!current.includes(".runtrim/internal/")) {
+    fs13.writeFileSync(gitignorePath, current.trimEnd() + "\n\n" + desired + "\n", "utf-8");
+  }
+}
+function listFilesIfExists(dir) {
+  if (!fs13.existsSync(dir)) return [];
+  return fs13.readdirSync(dir).map((name) => path13.join(dir, name)).filter((p) => fs13.existsSync(p) && fs13.statSync(p).isFile());
+}
+function listArtifactFiles(cwd) {
+  const dirs = [
+    getRunsDir(cwd),
+    getPreviewsDir(cwd),
+    getRestoresDir(cwd),
+    getContractsArchiveDir(cwd),
+    path13.join(getConfigDir(cwd), "internal", "agent-archive"),
+    getLegacyRunsDir(cwd),
+    getLegacyPreviewsDir(cwd),
+    getLegacyRestoresDir(cwd),
+    path13.join(getConfigDir(cwd), "contracts", "archive"),
+    path13.join(getConfigDir(cwd), "agent")
+  ];
+  const files = dirs.flatMap((dir) => listFilesIfExists(dir));
+  return files.filter((filePath) => {
+    const base = path13.basename(filePath).toLowerCase();
+    const rel = path13.relative(cwd, filePath).replace(/\\/g, "/");
+    if (rel === ".runtrim/previews/latest.md") return false;
+    if (base === "latest.md" || base === "instructions.md" || base === "current.md" || base === "baseline.md") return false;
+    return true;
+  });
+}
+function parseRunIdFromArtifact(filePath) {
+  const base = path13.basename(filePath);
+  const direct = base.match(/^([a-zA-Z0-9_-]{6,})\.json$/);
+  if (direct) return direct[1];
+  const report = base.match(/^([a-zA-Z0-9_-]{6,})\.report\.\d+\.json$/);
+  if (report) return report[1];
+  const out = base.match(/^([a-zA-Z0-9_-]{6,})\.output\.txt$/);
+  if (out) return out[1];
+  return null;
+}
 function normalizeContractPathPattern(pattern) {
   let p = pattern.trim().replace(/\\/g, "/");
   if (!p || p === "-" || p.toLowerCase() === "none") return "";
@@ -6004,10 +6149,11 @@ function buildRecommendedNextCommand(task, approval, filesToInspect) {
   return `runtrim go "${task}"`;
 }
 function writePreviewArtifacts(cwd, preview) {
-  const previewsDir = path13.join(cwd, ".runtrim", "previews");
+  const previewsDir = getPreviewsDir(cwd);
   if (!fs13.existsSync(previewsDir)) fs13.mkdirSync(previewsDir, { recursive: true });
   const jsonPath = path13.join(previewsDir, `${preview.id}.json`);
-  const markdownPath = path13.join(previewsDir, "latest.md");
+  const markdownPath = path13.join(getLegacyPreviewsDir(cwd), "latest.md");
+  if (!fs13.existsSync(path13.dirname(markdownPath))) fs13.mkdirSync(path13.dirname(markdownPath), { recursive: true });
   fs13.writeFileSync(jsonPath, JSON.stringify(preview, null, 2), "utf-8");
   const lines = [
     "RunTrim Agent Preview",
@@ -6046,7 +6192,7 @@ function writePreviewArtifacts(cwd, preview) {
     "Next:",
     preview.recommendedNextCommand,
     "",
-    `Preview JSON: .runtrim/previews/${preview.id}.json`
+    `Preview JSON: .runtrim/internal/previews/${preview.id}.json`
   ];
   fs13.writeFileSync(markdownPath, lines.join("\n"), "utf-8");
   return { jsonPath, markdownPath };
@@ -6428,6 +6574,7 @@ async function runAgentApply(task, mode) {
   const copied = mode.copy ? await copyToClipboardSafe(fs13.readFileSync(handoff.markdownPath, "utf-8")) : false;
   const run = saveRun(task, previewResult.audit, previewResult.contract, cwd);
   updateRun(run.id, { status: "guarded" }, cwd);
+  await captureRestorePoint(cwd, run.id, task);
   const riskColor = (_a2 = { low: chalk.green, medium: chalk.yellow, high: chalk.hex("#FF8C00"), critical: chalk.red }[risk]) != null ? _a2 : chalk.white;
   if (mode.primary) {
     console.log("");
@@ -6614,6 +6761,7 @@ async function runControlledExecution(task, mode) {
       controlledExecutionId: id,
       controlledExecutionStatus: status
     }, cwd);
+    await captureRestorePoint(cwd, run.id, task);
   }
   if (status === "blocked") {
     console.log("");
@@ -6904,14 +7052,18 @@ ${block}
 function buildRuntrimAgentBlockContent() {
   return [
     "RunTrim project instructions",
+    `RUNTRIM_AGENT_INSTRUCTIONS_VERSION: ${RUNTRIM_AGENT_INSTRUCTIONS_VERSION}`,
     "- Before editing, read RunTrim project memory and profile context.",
-    "- Verify active contract first. If MCP is available and no contract is active, call runtrim_create_contract with the user's task.",
+    "- Before editing, create or verify an active RunTrim contract for the current user task.",
+    "- If MCP is available and no active contract exists, call runtrim_create_contract with the user's task.",
     '- If MCP is unavailable, ask the user to run: runtrim agent "task" --copy',
-    "- Stay inside active contract scope.",
-    "- Before high-risk edits (auth, billing, middleware/proxy, migrations, sensitive files, broad app-wide changes), check scope first. If MCP is available, call runtrim_check_path.",
+    "- Before touching risky paths (auth, billing, middleware/proxy, migrations, env/sensitive files, broad app-wide refactors), call runtrim_check_path when available.",
+    "- Use RunTrim project memory and stay inside active contract scope.",
+    "- Do not silently expand scope. Preserve existing project style and logic.",
     "- Never read or print env file contents.",
-    '- Do not continue outside scope silently. Request: runtrim approve "Allow <path/scope> for this run only"',
-    "- At the end, run or ask for runtrim finish. Do not claim completion before finish verification.",
+    '- If scope must expand, stop and request approval: runtrim approve "Allow <path/scope> for this run only"',
+    "- At the end, run runtrim finish if terminal execution is available, otherwise ask the user to run runtrim finish.",
+    "- Do not claim completion before finish verification when RunTrim is active.",
     "",
     "RunTrim MCP:",
     "- runtrim mcp instructions",
@@ -7071,12 +7223,16 @@ function updateStartAgentInstructions(cwd) {
   const existing = fs13.existsSync(instructionsPath) ? fs13.readFileSync(instructionsPath, "utf-8") : "";
   const body = [
     "RunTrim agent instructions:",
+    `RUNTRIM_AGENT_INSTRUCTIONS_VERSION: ${RUNTRIM_AGENT_INSTRUCTIONS_VERSION}`,
     "- Use RunTrim project memory and profile before editing.",
-    "- Verify active contract before edits. If MCP is available and contract is missing, call runtrim_create_contract with the user's task.",
+    "- Create or verify an active RunTrim contract before edits.",
+    "- If MCP is available and contract is missing, call runtrim_create_contract with the user's task.",
     '- If MCP is unavailable, ask user to run: runtrim agent "task" --copy',
-    "- For high-risk paths (auth, billing, middleware/proxy, migrations, sensitive files, broad app-wide changes), check scope first. If MCP is available, call runtrim_check_path.",
+    "- For high-risk paths (auth, billing, middleware/proxy, migrations, env/sensitive files, broad app-wide changes), check scope first. If MCP is available, call runtrim_check_path.",
+    "- Stay inside active contract scope and preserve existing project style and logic.",
     '- If scope must expand, request: runtrim approve "Allow <path/scope> for this run only"',
-    "- Run finish verification at the end. Do not claim completion before runtrim finish.",
+    "- Run runtrim finish when terminal execution is available, otherwise ask the user to run runtrim finish.",
+    "- Do not claim completion before runtrim finish verification when RunTrim is active.",
     "- Never read or print env file contents.",
     "",
     "RunTrim MCP:",
@@ -7149,6 +7305,202 @@ function detectKnownMcpConfigPresence() {
     cursorConfigFound: Boolean(cursorMatch)
   };
 }
+function getRestorePointPath(cwd, runId) {
+  return path13.join(getRestoresDir(cwd), `${runId}.json`);
+}
+function getLegacyRestorePointPath(cwd, runId) {
+  return path13.join(getLegacyRestoresDir(cwd), `${runId}.json`);
+}
+async function isGitRepo(cwd) {
+  try {
+    await execa3("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+async function captureRestorePoint(cwd, runId, task) {
+  const dir = getRestoresDir(cwd);
+  if (!fs13.existsSync(dir)) fs13.mkdirSync(dir, { recursive: true });
+  const existingPath = getRestorePointPath(cwd, runId);
+  if (fs13.existsSync(existingPath) || fs13.existsSync(getLegacyRestorePointPath(cwd, runId))) return;
+  let commit = null;
+  let changedBeforeRun = [];
+  if (await isGitRepo(cwd)) {
+    try {
+      const { stdout } = await execa3("git", ["rev-parse", "HEAD"], { cwd });
+      commit = stdout.trim() || null;
+    } catch (e) {
+      commit = null;
+    }
+    try {
+      const changed = await getGitChangedFiles(cwd);
+      changedBeforeRun = dedupeFiles(changed.map((c) => c.path));
+    } catch (e) {
+      changedBeforeRun = [];
+    }
+  }
+  const record = {
+    runId,
+    task,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    preRun: {
+      commit,
+      dirty: changedBeforeRun.length > 0,
+      changedBeforeRun
+    }
+  };
+  fs13.writeFileSync(existingPath, JSON.stringify(record, null, 2), "utf-8");
+}
+function loadRestorePoint(cwd, runId) {
+  const preferred = getRestorePointPath(cwd, runId);
+  const legacy = getLegacyRestorePointPath(cwd, runId);
+  const p = fs13.existsSync(preferred) ? preferred : legacy;
+  if (!fs13.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs13.readFileSync(p, "utf-8"));
+  } catch (e) {
+    return null;
+  }
+}
+function saveRestorePoint(cwd, record) {
+  const dir = getRestoresDir(cwd);
+  if (!fs13.existsSync(dir)) fs13.mkdirSync(dir, { recursive: true });
+  fs13.writeFileSync(getRestorePointPath(cwd, record.runId), JSON.stringify(record, null, 2), "utf-8");
+}
+function isSecretLikePath(file) {
+  const n = file.replace(/\\/g, "/").toLowerCase();
+  return n.includes(".env") || n.endsWith(".env") || n.endsWith(".pem") || n.endsWith(".key") || n.includes("id_rsa") || n.includes("id_ed25519") || n.includes("private-key");
+}
+function isDocsLikePath(file) {
+  const n = file.replace(/\\/g, "/").toLowerCase();
+  return n === "readme.md" || n.startsWith("docs/") || n.endsWith(".md") || n.endsWith(".mdx") || n.includes("changelog");
+}
+function isUiCheckoutPath(file) {
+  const n = file.replace(/\\/g, "/").toLowerCase();
+  return n.includes("/checkout/") && !n.includes("/api/") && !n.includes("webhook") && !n.includes("stripe") && !n.includes("dodo") && !n.includes("provider") && !n.includes("session");
+}
+function isHighRiskLogicPath(file) {
+  const n = file.replace(/\\/g, "/").toLowerCase();
+  if (isSecretLikePath(n)) return true;
+  if (n.endsWith("middleware.ts") || n.endsWith("middleware.js") || n.endsWith("proxy.ts") || n.endsWith("proxy.js")) return true;
+  if (n.includes("supabase/migrations") || n.includes("prisma/migrations") || n.includes("/migrations/")) return true;
+  if (n.includes("/auth/") || n.includes("session") || n.includes("jwt")) return true;
+  if (n.includes("webhook")) return true;
+  if ((n.includes("billing") || n.includes("payment") || n.includes("stripe") || n.includes("dodo")) && (n.includes("/api/") || n.includes("/lib/") || n.includes("route.ts") || n.includes("route.js") || n.includes("server"))) return true;
+  if (n.includes("/checkout/") && !isUiCheckoutPath(n) && (n.includes("/api/") || n.includes("provider") || n.includes("session") || n.includes("route.ts") || n.includes("route.js"))) return true;
+  return false;
+}
+function matchesAnyContractRule(file, rules) {
+  return rules.some((rule) => matchesContractPattern(file, rule));
+}
+async function detectCiChangedFiles(cwd, base, head) {
+  var _a2;
+  const warnings = [];
+  let baseUsed = (base == null ? void 0 : base.trim()) || "";
+  let headUsed = (head == null ? void 0 : head.trim()) || "";
+  if (!headUsed) {
+    try {
+      const { stdout } = await execa3("git", ["rev-parse", "HEAD"], { cwd });
+      headUsed = stdout.trim();
+    } catch (e) {
+      headUsed = "HEAD";
+    }
+  }
+  if (!baseUsed) {
+    const ghBase = (_a2 = process.env.GITHUB_BASE_REF) == null ? void 0 : _a2.trim();
+    if (ghBase) {
+      baseUsed = `origin/${ghBase}`;
+    }
+  }
+  if (!baseUsed) {
+    for (const candidate of ["origin/main", "origin/master", "main", "master", "HEAD~1"]) {
+      try {
+        await execa3("git", ["rev-parse", "--verify", candidate], { cwd });
+        baseUsed = candidate;
+        break;
+      } catch (e) {
+        continue;
+      }
+    }
+  }
+  if (!baseUsed) {
+    warnings.push("Could not infer a base ref. Using working tree changes only.");
+  }
+  let diffFiles = [];
+  if (baseUsed) {
+    try {
+      const { stdout } = await execa3("git", ["diff", "--name-only", `${baseUsed}...${headUsed}`], { cwd });
+      diffFiles = stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    } catch (e) {
+      warnings.push(`Could not diff ${baseUsed}...${headUsed}. Falling back to local changes.`);
+    }
+  }
+  if (diffFiles.length === 0) {
+    try {
+      const { stdout } = await execa3("git", ["diff", "--name-only"], { cwd });
+      diffFiles = stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    } catch (e) {
+    }
+  }
+  try {
+    const { stdout } = await execa3("git", ["status", "--porcelain"], { cwd });
+    const untracked = stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith("?? ")).map((line) => line.slice(3).trim());
+    diffFiles = dedupeFiles([...diffFiles, ...untracked]);
+  } catch (e) {
+  }
+  return {
+    files: dedupeFiles(diffFiles.map((f) => f.replace(/\\/g, "/"))),
+    baseUsed: baseUsed || "(local)",
+    headUsed,
+    warnings
+  };
+}
+function detectMcpConfigState(configPath, found) {
+  if (!found || !configPath) return "not found";
+  try {
+    const raw = JSON.parse(fs13.readFileSync(configPath, "utf-8"));
+    const servers = raw.mcpServers && typeof raw.mcpServers === "object" ? raw.mcpServers : {};
+    return servers.runtrim ? "configured" : "missing runtrim";
+  } catch (e) {
+    return "missing runtrim";
+  }
+}
+function hasCurrentRuntrimBlock(filePath) {
+  if (!fs13.existsSync(filePath)) return { exists: false, current: false };
+  const content = fs13.readFileSync(filePath, "utf-8");
+  const hasBlock = content.includes("<!-- RUNTRIM:START -->") && content.includes("<!-- RUNTRIM:END -->");
+  const hasVersion = content.includes(`RUNTRIM_AGENT_INSTRUCTIONS_VERSION: ${RUNTRIM_AGENT_INSTRUCTIONS_VERSION}`);
+  return { exists: hasBlock, current: hasBlock && hasVersion };
+}
+function readMcpLastUsed(cwd) {
+  const p = path13.join(getProjectMcpDir(cwd), "last-used.json");
+  if (!fs13.existsSync(p)) return { tracked: false, tool: null, usedAt: null };
+  try {
+    const parsed = JSON.parse(fs13.readFileSync(p, "utf-8"));
+    return {
+      tracked: true,
+      tool: typeof parsed.tool === "string" ? parsed.tool : null,
+      usedAt: typeof parsed.usedAt === "string" ? parsed.usedAt : null
+    };
+  } catch (e) {
+    return { tracked: false, tool: null, usedAt: null };
+  }
+}
+function writeMcpLastUsed(cwd, tool) {
+  try {
+    const dir = getProjectMcpDir(cwd);
+    if (!fs13.existsSync(dir)) fs13.mkdirSync(dir, { recursive: true });
+    const payload = {
+      tool,
+      usedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      projectPath: cwd
+    };
+    fs13.writeFileSync(path13.join(dir, "last-used.json"), `${JSON.stringify(payload, null, 2)}
+`, "utf-8");
+  } catch (e) {
+  }
+}
 function appendContractAmendment(cwd, approvalText) {
   const p = path13.join(cwd, ".runtrim", "contracts", "latest.md");
   if (!fs13.existsSync(p)) return { ok: false, reason: "missing_contract" };
@@ -7521,6 +7873,7 @@ async function buildRuntrimCreateContractMcp(cwd, args) {
   const handoff = writeAgentHandoffArtifacts(cwd, apply, path13.relative(cwd, previewPath));
   const run = saveRun(mergedTask, previewResult.audit, previewResult.contract, cwd);
   updateRun(run.id, { status: "guarded" }, cwd);
+  await captureRestorePoint(cwd, run.id, mergedTask);
   const payload = {
     contract_created: true,
     task: taskRaw,
@@ -7715,6 +8068,7 @@ async function startMcpServerStdio(cwd) {
         });
         return;
       }
+      writeMcpLastUsed(cwd, name);
       send({
         jsonrpc: "2.0",
         id,
@@ -8202,6 +8556,7 @@ async function initializeRunTrim(cwd, options = {}) {
   const runsDir = getRunsDir(cwd);
   if (!fs13.existsSync(configDir)) fs13.mkdirSync(configDir, { recursive: true });
   if (!fs13.existsSync(runsDir)) fs13.mkdirSync(runsDir, { recursive: true });
+  ensureInternalArtifactDirs(cwd);
   const existingConfig = hadConfig ? loadConfig(cwd) : null;
   const baseConfig = __spreadValues(__spreadValues({}, DEFAULT_CONFIG), detectProjectInfo(cwd));
   const nextConfig = options.refresh && existingConfig ? __spreadValues({}, existingConfig) : baseConfig;
@@ -8221,13 +8576,8 @@ async function initializeRunTrim(cwd, options = {}) {
     fs13.writeFileSync(memoryPath, buildBaselineMemoryMarkdown(baseline), "utf-8");
   }
   ensureStarterPromptIfMissing(cwd);
-  const gitignorePath = path13.join(cwd, ".gitignore");
-  if (fs13.existsSync(gitignorePath)) {
-    const content = fs13.readFileSync(gitignorePath, "utf-8");
-    if (!content.includes(".runtrim/runs")) {
-      fs13.appendFileSync(gitignorePath, "\n# RunTrim run history\n.runtrim/runs/\n");
-    }
-  }
+  ensureRuntrimReadme(cwd);
+  ensureRuntrimGitignoreGuidance(cwd);
   return { ok: true };
 }
 async function runPrepareTask(task, options) {
@@ -8262,7 +8612,7 @@ async function runPrepareTask(task, options) {
     console.log("");
     console.log(DIM("  Task      ") + chalk.white(truncate(task, 70)));
     console.log(DIM("  Prompt    ") + chalk.white(promptPath2));
-    console.log(DIM("  Run saved ") + chalk.white(`.runtrim/runs/${run.id}.json`));
+    console.log(DIM("  Run saved ") + chalk.white(`.runtrim/internal/runs/${run.id}.json`));
     console.log("");
     printPrepareAgentInstructions(selectedAgent, config.lastPromptPath);
     console.log("");
@@ -8282,6 +8632,7 @@ async function runPrepareTask(task, options) {
   const promptPath = writeLatestPromptFile(contract.contractText, config, cwd);
   if (options.copy !== false) await copyToClipboardSafe(contract.contractText);
   updateRun(run.id, { status: "guarded" }, cwd);
+  await captureRestorePoint(cwd, run.id, task);
   const riskColors = {
     low: chalk.green,
     medium: chalk.yellow,
@@ -8304,7 +8655,7 @@ async function runPrepareTask(task, options) {
   );
   console.log(DIM("  Reduction ") + chalk.white(contract.riskReductionPercent + "%"));
   console.log(DIM("  Prompt    ") + chalk.white(promptPath));
-  console.log(DIM("  Run saved ") + chalk.white(`.runtrim/runs/${run.id}.json`));
+  console.log(DIM("  Run saved ") + chalk.white(`.runtrim/internal/runs/${run.id}.json`));
   console.log("");
   printPrepareAgentInstructions(selectedAgent, config.lastPromptPath);
   console.log("");
@@ -8448,6 +8799,9 @@ program.command("start").description("Guided RunTrim onboarding and daily loop")
   console.log(chalk.white("  runtrim mcp config --print"));
   console.log(chalk.white("  runtrim mcp start"));
   console.log("");
+  console.log(DIM("  Check readiness"));
+  console.log(chalk.white("  runtrim doctor"));
+  console.log("");
   console.log(DIM("  Adapters"));
   console.log(chalk.white("  runtrim adapters"));
   console.log(chalk.white("  runtrim adapters status"));
@@ -8529,6 +8883,108 @@ program.command("start").description("Guided RunTrim onboarding and daily loop")
     console.log("");
   }
 });
+program.command("doctor").description("Check whether the current project is RunTrim-ready for agents, MCP, memory and finish verification").action(async () => {
+  const cwd = process.cwd();
+  const repoCheck = await assertFreeRepoAllowed(cwd);
+  const profilePath = path13.join(getConfigDir(cwd), "project-profile.json");
+  const memoryPath = path13.join(getConfigDir(cwd), "memory", "current.md");
+  const instructionsPath = path13.join(getConfigDir(cwd), "agent", "instructions.md");
+  const snippetsDir = getProjectMcpDir(cwd);
+  const snippetFiles = [
+    path13.join(snippetsDir, "claude-desktop.json"),
+    path13.join(snippetsDir, "cursor.json"),
+    path13.join(snippetsDir, "generic.json")
+  ];
+  const profileReady = fs13.existsSync(profilePath);
+  const memoryReady = fs13.existsSync(memoryPath) && fs13.readFileSync(memoryPath, "utf-8").trim().length > 0;
+  const instructionsReady = fs13.existsSync(instructionsPath) && fs13.readFileSync(instructionsPath, "utf-8").trim().length > 0;
+  const claudeBlock = hasCurrentRuntrimBlock(path13.join(cwd, "CLAUDE.md"));
+  const agentsBlock = hasCurrentRuntrimBlock(path13.join(cwd, "AGENTS.md"));
+  const cursorRulePath = path13.join(cwd, ".cursor", "rules", "runtrim.mdc");
+  const cursorRuleExists = fs13.existsSync(cursorRulePath);
+  const cursorRuleCurrent = cursorRuleExists ? fs13.readFileSync(cursorRulePath, "utf-8").includes(`RUNTRIM_AGENT_INSTRUCTIONS_VERSION: ${RUNTRIM_AGENT_INSTRUCTIONS_VERSION}`) : false;
+  const anySurfaceInstalled = claudeBlock.exists || agentsBlock.exists || cursorRuleExists;
+  const runtrimBlockCurrent = [claudeBlock.current, agentsBlock.current, cursorRuleCurrent].some(Boolean);
+  const snippetsGenerated = snippetFiles.every((p) => fs13.existsSync(p));
+  const knownMcp = detectKnownMcpConfigPresence();
+  const claudeMcpState = detectMcpConfigState(knownMcp.claudeConfigPath, knownMcp.claudeConfigFound);
+  const cursorMcpState = detectMcpConfigState(knownMcp.cursorConfigPath, knownMcp.cursorConfigFound);
+  const genericReady = snippetsGenerated ? "ready" : "missing";
+  const tools = buildMcpTools();
+  const hasContractTool = tools.some((t) => t.name === "runtrim_create_contract");
+  const hasPathTool = tools.some((t) => t.name === "runtrim_check_path");
+  const hasApprovalTool = tools.some((t) => t.name === "runtrim_suggest_approval");
+  const hasFinishTool = tools.some((t) => t.name === "runtrim_finish_guidance");
+  const contract = parseContractSummary(cwd);
+  const lastMcp = readMcpLastUsed(cwd);
+  const setupCorrupt = configExists(cwd) && (!profileReady || !memoryReady || !instructionsReady);
+  const artifactFiles = listArtifactFiles(cwd);
+  const artifactCount = artifactFiles.length;
+  let readiness = "partial";
+  if (!repoCheck.allowed || setupCorrupt) {
+    readiness = "blocked";
+  } else if (profileReady && memoryReady && instructionsReady && anySurfaceInstalled && snippetsGenerated && hasContractTool && hasPathTool && hasApprovalTool && hasFinishTool) {
+    readiness = "ready";
+  }
+  console.log("");
+  console.log(BOLD("RunTrim") + DIM("  doctor"));
+  console.log("");
+  console.log(BOLD("Project"));
+  console.log(chalk.white(`- Project profile: ${profileReady ? "ready" : "missing"}`));
+  console.log(chalk.white(`- Project memory: ${memoryReady ? "ready" : "missing"}`));
+  console.log(chalk.white(`- Agent instructions: ${instructionsReady ? "ready" : "missing"}`));
+  console.log(chalk.white(`- Active contract: ${contract.active ? "active" : "none"}`));
+  console.log("");
+  console.log(BOLD("Agent rules"));
+  console.log(chalk.white(`- CLAUDE.md: ${claudeBlock.exists ? "installed" : "not found"}`));
+  console.log(chalk.white(`- AGENTS.md: ${agentsBlock.exists ? "installed" : "not found"}`));
+  console.log(chalk.white(`- Cursor rules: ${cursorRuleExists ? "installed" : "not found"}`));
+  console.log(chalk.white(`- RunTrim instruction block: ${runtrimBlockCurrent ? "current" : anySurfaceInstalled ? "stale" : "missing"}`));
+  console.log("");
+  console.log(BOLD("MCP"));
+  console.log(chalk.white("- MCP server: available"));
+  console.log(chalk.white(`- Project snippets: ${snippetsGenerated ? "generated" : "missing"}`));
+  console.log(chalk.white(`- Claude Desktop config: ${claudeMcpState}`));
+  console.log(chalk.white(`- Cursor MCP config: ${cursorMcpState}`));
+  console.log(chalk.white(`- Generic config: ${genericReady}`));
+  if (lastMcp.tracked && lastMcp.tool && lastMcp.usedAt) {
+    console.log(chalk.white(`- Last MCP tool call: ${lastMcp.tool}, ${lastMcp.usedAt}`));
+  } else {
+    console.log(chalk.white("- Last MCP tool call: not tracked yet"));
+  }
+  console.log("");
+  console.log(BOLD("Automation readiness"));
+  console.log(chalk.white(`- Contract creation tool: ${hasContractTool ? "available" : "missing"}`));
+  console.log(chalk.white(`- Path check tool: ${hasPathTool ? "available" : "missing"}`));
+  console.log(chalk.white(`- Approval tool: ${hasApprovalTool ? "available" : "missing"}`));
+  console.log(chalk.white(`- Finish guidance tool: ${hasFinishTool ? "available" : "missing"}`));
+  console.log(chalk.white(`- Local artifacts: ${artifactCount}`));
+  console.log("");
+  console.log(BOLD("Readiness"));
+  console.log(chalk.white(`- State: ${readiness}`));
+  console.log("");
+  console.log(BOLD("Next"));
+  if (repoCheck.status === "blocked_repair") {
+    console.log(chalk.yellow("- RunTrim local state needs repair. Run runtrim repo repair."));
+  } else if (repoCheck.status === "blocked_limit") {
+    console.log(chalk.yellow("- Free includes 1 tracked repo. Continue in tracked repo, unlink with runtrim repo unlink --force, or upgrade to Builder."));
+  } else if (readiness === "ready") {
+    if (claudeMcpState !== "configured" && cursorMcpState !== "configured") {
+      console.log(chalk.white("- Ready locally, MCP client not connected."));
+      console.log(chalk.white("- Run runtrim mcp instructions or copy .runtrim/mcp/cursor.json into your MCP client."));
+    } else {
+      console.log(chalk.white("- Your project is RunTrim-aware. Open Cursor/Claude/Codex and use normal language."));
+    }
+  } else {
+    console.log(chalk.white("- Run runtrim start."));
+    console.log(chalk.white("- Run runtrim mcp instructions."));
+    console.log(chalk.white("- Run runtrim mcp config --print."));
+  }
+  if (artifactCount > 25) {
+    console.log(chalk.white(`- Local artifacts: ${artifactCount}. Run runtrim clean --dry-run to review cleanup.`));
+  }
+  console.log("");
+});
 var PROTOCOL_BLOCK_START = "<!-- RUNTRIM_PROTOCOL_START -->";
 var PROTOCOL_BLOCK_END = "<!-- RUNTRIM_PROTOCOL_END -->";
 var PROTOCOL_POINTER_BLOCK = `
@@ -9633,6 +10089,146 @@ agentCommand.command("prompt-mode <mode>").description("Set how guarded contract
   console.log(ACCENT.bold("  Agent prompt mode updated to: " + m));
   console.log("");
 });
+var ciCommand = program.command("ci").description("RunTrim CI checks for pull requests and merges");
+ciCommand.command("check").description("Evaluate changed files and RunTrim context for CI-safe PASS/WARN/BLOCKED verdict").option("--base <ref>", "Base ref to diff from").option("--head <ref>", "Head ref to diff to").option("--strict", "Treat WARN as failing and require RunTrim context").option("--allow-warn", "Allow WARN even when --strict is set").option("--json", "Print machine-readable JSON output").option("--report", "Include extra diagnostic context in output").action(async (options) => {
+  const cwd = process.cwd();
+  const strict = options.strict === true;
+  const allowWarn = options.allowWarn === true;
+  const outputJson = options.json === true;
+  const report = options.report === true;
+  const repoCheck = await assertFreeRepoAllowed(cwd);
+  const detection = await detectCiChangedFiles(cwd, options.base, options.head);
+  const changedFiles = detection.files;
+  const contract = parseContractSummary(cwd);
+  const latestRun = loadLatestRun(cwd);
+  const hasRuntrimContext = contract.exists || Boolean(latestRun);
+  const issues = [];
+  const warnings = [...detection.warnings];
+  const nextSteps = [];
+  let verdict = "PASS";
+  if (repoCheck.status === "blocked_repair") {
+    issues.push("RunTrim local state needs repair before CI can trust local guard state.");
+    nextSteps.push("Run: runtrim repo repair");
+    verdict = "BLOCKED";
+  } else if (repoCheck.status === "blocked_limit") {
+    issues.push("Free includes 1 tracked repo and this repo is not currently tracked.");
+    nextSteps.push("Continue in tracked repo, unlink with runtrim repo unlink --force, or upgrade to Builder.");
+    verdict = "BLOCKED";
+  }
+  if (changedFiles.length === 0) {
+    warnings.push("No changed files detected for this diff.");
+  }
+  const secretFiles = changedFiles.filter(isSecretLikePath);
+  if (secretFiles.length > 0) {
+    issues.push(`Sensitive file path changed: ${secretFiles[0]}`);
+    nextSteps.push("Remove secret/env/key/cert files from this PR before merge.");
+    verdict = "BLOCKED";
+  }
+  const highRiskFiles = changedFiles.filter((f) => isHighRiskLogicPath(f) && !isSecretLikePath(f));
+  if (highRiskFiles.length > 0) {
+    if (!hasRuntrimContext) {
+      issues.push(`High-risk path changed without RunTrim context: ${highRiskFiles[0]}`);
+      nextSteps.push("Create a dedicated guarded run and finish it before merging.");
+      verdict = "BLOCKED";
+    } else if (contract.allowedPaths.length > 0 && !matchesAnyContractRule(highRiskFiles[0], contract.allowedPaths)) {
+      issues.push(`High-risk path is outside contract allowed scope: ${highRiskFiles[0]}`);
+      nextSteps.push(`Run: runtrim approve "Allow ${highRiskFiles[0]} for this run only"`);
+      verdict = "BLOCKED";
+    }
+  }
+  if (contract.forbiddenPaths.length > 0) {
+    const forbiddenTouched = changedFiles.filter((f) => matchesAnyContractRule(f, contract.forbiddenPaths));
+    if (forbiddenTouched.length > 0) {
+      issues.push(`Contract-forbidden path touched: ${forbiddenTouched[0]}`);
+      nextSteps.push("Split the task or get explicit scoped approval before merge.");
+      verdict = "BLOCKED";
+    }
+  }
+  if (contract.allowedPaths.length > 0) {
+    const outOfScope = changedFiles.filter((f) => !matchesAnyContractRule(f, contract.allowedPaths));
+    if (outOfScope.length > 0) {
+      issues.push(`Changed file is outside latest contract scope: ${outOfScope[0]}`);
+      nextSteps.push(`Run: runtrim approve "Allow ${outOfScope[0]} for this run only"`);
+      verdict = "BLOCKED";
+    }
+  }
+  const docsOnly = changedFiles.length > 0 && changedFiles.every((f) => isDocsLikePath(f));
+  if (!hasRuntrimContext && verdict !== "BLOCKED") {
+    if (docsOnly) {
+      warnings.push("No RunTrim contract/report found. Docs-only change treated as low risk.");
+      verdict = "WARN";
+    } else {
+      warnings.push("No RunTrim contract/report found. CI could not fully verify scope context.");
+      verdict = "WARN";
+    }
+  }
+  if (strict && !hasRuntrimContext && verdict !== "BLOCKED") {
+    issues.push("Strict mode requires RunTrim contract/report context.");
+    verdict = "BLOCKED";
+  }
+  if (verdict === "PASS" && warnings.length > 0) {
+    verdict = "WARN";
+  }
+  if (nextSteps.length === 0) {
+    if (verdict === "PASS") {
+      nextSteps.push("Safe to merge under current RunTrim CI policy.");
+    } else if (verdict === "WARN") {
+      nextSteps.push("Run runtrim finish locally to strengthen verification context.");
+    } else {
+      nextSteps.push("Resolve blocked issues, then rerun runtrim ci check.");
+    }
+  }
+  let exitCode = 0;
+  if (verdict === "BLOCKED") exitCode = 1;
+  if (verdict === "WARN" && strict && !allowWarn) exitCode = 1;
+  const jsonPayload = {
+    verdict: verdict.toLowerCase(),
+    exitCode,
+    changedFiles,
+    issues,
+    warnings,
+    nextSteps
+  };
+  if (outputJson) {
+    process.stdout.write(`${JSON.stringify(jsonPayload, null, 2)}
+`);
+    process.exit(exitCode);
+    return;
+  }
+  console.log("");
+  console.log(BOLD("RunTrim") + DIM("  CI Check"));
+  console.log("");
+  const verdictColor = verdict === "PASS" ? chalk.green : verdict === "WARN" ? chalk.yellow : chalk.red;
+  console.log(DIM("  Verdict: ") + verdictColor(verdict));
+  console.log("");
+  console.log(DIM("  Changed files:"));
+  if (changedFiles.length === 0) console.log(chalk.white("  - (none detected)"));
+  for (const f of changedFiles.slice(0, 20)) console.log(chalk.white("  - " + f));
+  if (changedFiles.length > 20) console.log(DIM(`  ... and ${changedFiles.length - 20} more`));
+  console.log("");
+  if (issues.length > 0) {
+    console.log(DIM("  Issues:"));
+    for (const i of issues) console.log(chalk.red("  - " + i));
+    console.log("");
+  }
+  if (warnings.length > 0) {
+    console.log(DIM("  Warnings:"));
+    for (const w of warnings) console.log(chalk.yellow("  - " + w));
+    console.log("");
+  }
+  console.log(DIM("  Next:"));
+  for (const n of nextSteps) console.log(chalk.white("  - " + n));
+  if (report) {
+    console.log("");
+    console.log(DIM("  Report:"));
+    console.log(chalk.white(`  - Base: ${detection.baseUsed}`));
+    console.log(chalk.white(`  - Head: ${detection.headUsed}`));
+    console.log(chalk.white(`  - Contract: ${contract.exists ? contract.active ? "active" : "present" : "none"}`));
+    console.log(chalk.white(`  - Latest run: ${latestRun ? latestRun.status : "none"}`));
+  }
+  console.log("");
+  process.exit(exitCode);
+});
 var authCommand = program.command("auth").description("Configure sync token for dashboard sync");
 authCommand.command("set <token>").description("Set sync token and enable sync").action((token) => {
   const cwd = process.cwd();
@@ -9774,6 +10370,214 @@ repoCommand.command("unlink").description("Unlink tracked repo from local free-p
   console.log(DIM("  No tracked repo found."));
   console.log("");
 });
+program.command("clean").description("Clean old local RunTrim artifacts while preserving active project state").option("--dry-run", "Preview files that would be removed").option("--keep <n>", "Number of latest run-linked artifacts to keep", "10").action(async (options) => {
+  var _a2;
+  const cwd = process.cwd();
+  const dryRun = (options == null ? void 0 : options.dryRun) === true;
+  const keep = Math.max(1, Number.parseInt((_a2 = options == null ? void 0 : options.keep) != null ? _a2 : "10", 10) || 10);
+  ensureInternalArtifactDirs(cwd);
+  const runs = loadAllRuns(cwd);
+  const keepRunIds = new Set(runs.slice(0, keep).map((r) => r.id));
+  const files = listArtifactFiles(cwd);
+  const removable = files.filter((filePath) => {
+    const runId = parseRunIdFromArtifact(filePath);
+    if (!runId) return true;
+    return !keepRunIds.has(runId);
+  });
+  const byCategory = {
+    runs: 0,
+    previews: 0,
+    restores: 0,
+    archives: 0,
+    other: 0
+  };
+  for (const filePath of removable) {
+    const rel = path13.relative(cwd, filePath).replace(/\\/g, "/").toLowerCase();
+    if (rel.includes(".runtrim/internal/runs/") || rel.includes(".runtrim/runs/")) byCategory.runs += 1;
+    else if (rel.includes(".runtrim/internal/previews/") || rel.includes(".runtrim/previews/")) byCategory.previews += 1;
+    else if (rel.includes(".runtrim/internal/restores/") || rel.includes(".runtrim/restores/")) byCategory.restores += 1;
+    else if (rel.includes("archive")) byCategory.archives += 1;
+    else byCategory.other += 1;
+  }
+  if (!dryRun) {
+    for (const filePath of removable) {
+      try {
+        fs13.rmSync(filePath, { force: true });
+      } catch (e) {
+      }
+    }
+  }
+  console.log("");
+  console.log(BOLD("RunTrim") + DIM("  clean"));
+  console.log("");
+  console.log(DIM("  Mode              ") + chalk.white(dryRun ? "dry-run" : "apply"));
+  console.log(DIM("  Keep latest runs  ") + chalk.white(String(keep)));
+  console.log(DIM("  Candidate files   ") + chalk.white(String(removable.length)));
+  console.log("");
+  console.log(DIM("  Cleanup summary"));
+  console.log(chalk.white(`  - runs: ${byCategory.runs}`));
+  console.log(chalk.white(`  - previews: ${byCategory.previews}`));
+  console.log(chalk.white(`  - restores: ${byCategory.restores}`));
+  console.log(chalk.white(`  - archives: ${byCategory.archives}`));
+  if (byCategory.other > 0) console.log(chalk.white(`  - other: ${byCategory.other}`));
+  console.log("");
+  if (removable.length > 0) {
+    const sample = removable.slice(0, 10).map((p) => path13.relative(cwd, p).replace(/\\/g, "/"));
+    console.log(DIM("  Sample files"));
+    for (const rel of sample) console.log(chalk.white(`  - ${rel}`));
+    if (removable.length > sample.length) {
+      console.log(DIM(`  ... and ${removable.length - sample.length} more`));
+    }
+    console.log("");
+  }
+  if (dryRun) {
+    console.log(chalk.white("  No files were removed."));
+    console.log(chalk.white("  Re-run without --dry-run to apply cleanup."));
+  } else {
+    console.log(chalk.white("  Cleanup complete."));
+    console.log(chalk.white("  Active contract, latest files, memory current, and MCP snippets were preserved."));
+  }
+  console.log("");
+});
+var restoreCommand = program.command("restore").description("Preview or apply local restore for guarded runs");
+restoreCommand.argument("[runId]", "Run ID to restore, or use 'last'").option("--preview", "Preview restore plan").option("--apply", "Apply restore plan").option("--force", "Apply even if unrelated new changes are detected").action(async (runIdArg, options) => {
+  var _a2, _b, _c, _d;
+  const cwd = process.cwd();
+  const doPreview = (options == null ? void 0 : options.preview) === true;
+  const doApply = (options == null ? void 0 : options.apply) === true;
+  const force = (options == null ? void 0 : options.force) === true;
+  if (!doPreview && !doApply) {
+    console.log("");
+    console.log(chalk.yellow("Choose --preview or --apply."));
+    console.log("");
+    return;
+  }
+  if (doPreview && doApply) {
+    console.log("");
+    console.log(chalk.yellow("Use either --preview or --apply, not both."));
+    console.log("");
+    return;
+  }
+  const runs = loadAllRuns(cwd);
+  const runIdInput = (runIdArg != null ? runIdArg : "last").trim();
+  let targetRunId = runIdInput;
+  if (runIdInput === "last") {
+    const latest = runs.find((r) => r.status === "completed" || r.status === "guarded" || r.status === "executed" || r.status === "checked");
+    if (!latest) {
+      console.log("");
+      console.log(chalk.yellow("No runs available for restore."));
+      console.log("");
+      return;
+    }
+    targetRunId = latest.id;
+  }
+  const run = runs.find((r) => r.id === targetRunId);
+  if (!run) {
+    console.log("");
+    console.log(chalk.yellow(`Run not found: ${targetRunId}`));
+    console.log("");
+    return;
+  }
+  const restore = loadRestorePoint(cwd, targetRunId);
+  if (!restore) {
+    console.log("");
+    console.log(chalk.yellow("No restore point found for this run."));
+    console.log("");
+    return;
+  }
+  const postFiles = (_b = (_a2 = restore.postRun) == null ? void 0 : _a2.changedFiles) != null ? _b : [];
+  const sensitive = postFiles.filter((f) => isSensitivePath(f) || isSecretLikePath(f));
+  const safeFiles = postFiles.filter((f) => !sensitive.includes(f));
+  const gitAvailable = await isGitRepo(cwd);
+  const method = gitAvailable && restore.preRun.commit ? "git checkout from pre-run commit" : "metadata-only (limited)";
+  const nowChanged = gitAvailable ? dedupeFiles((await getGitChangedFiles(cwd)).map((f) => f.path)) : [];
+  const unrelated = nowChanged.filter((f) => !postFiles.includes(f));
+  if (doPreview) {
+    console.log("");
+    console.log(BOLD("RunTrim") + DIM("  restore preview"));
+    console.log("");
+    console.log(DIM("  Run ID   ") + chalk.white(targetRunId));
+    console.log(DIM("  Task     ") + chalk.white(truncate(run.task, 80)));
+    console.log(DIM("  Method   ") + chalk.white(method));
+    console.log(DIM("  Verdict  ") + chalk.white((_d = (_c = restore.postRun) == null ? void 0 : _c.finishVerdict) != null ? _d : "unknown"));
+    console.log("");
+    console.log(DIM("  Files to restore"));
+    if (safeFiles.length === 0) console.log(chalk.white("  - (none)"));
+    for (const f of safeFiles.slice(0, 20)) console.log(chalk.white("  - " + f));
+    if (safeFiles.length > 20) console.log(DIM(`  ... and ${safeFiles.length - 20} more`));
+    if (sensitive.length > 0) {
+      console.log("");
+      console.log(DIM("  Sensitive files (listed by path only)"));
+      for (const f of sensitive.slice(0, 20)) console.log(chalk.yellow("  - " + f));
+      console.log(chalk.yellow("  Sensitive files are skipped by default and not auto-restored."));
+    }
+    if (unrelated.length > 0) {
+      console.log("");
+      console.log(chalk.yellow("  Warning: repo has new changes after this run."));
+      console.log(chalk.yellow("  Use --apply --force or review manually before restore."));
+    }
+    console.log("");
+    return;
+  }
+  if (!doApply) return;
+  if (!gitAvailable || !restore.preRun.commit) {
+    console.log("");
+    console.log(chalk.red("Restore apply requires git and a pre-run commit restore point."));
+    console.log("");
+    process.exit(1);
+    return;
+  }
+  if (unrelated.length > 0 && !force) {
+    console.log("");
+    console.log(chalk.red("Restore blocked: new unrelated changes detected after this run."));
+    console.log(chalk.red("Re-run with --apply --force after manual review."));
+    console.log("");
+    process.exit(1);
+    return;
+  }
+  const restored = [];
+  const skippedSensitive = [...sensitive];
+  const failed = [];
+  for (const file of safeFiles) {
+    try {
+      let existedBefore = false;
+      try {
+        await execa3("git", ["cat-file", "-e", `${restore.preRun.commit}:${file}`], { cwd });
+        existedBefore = true;
+      } catch (e) {
+        existedBefore = false;
+      }
+      if (existedBefore) {
+        await execa3("git", ["checkout", restore.preRun.commit, "--", file], { cwd });
+      } else if (fs13.existsSync(path13.join(cwd, file))) {
+        fs13.rmSync(path13.join(cwd, file), { force: true });
+      }
+      restored.push(file);
+    } catch (e) {
+      failed.push(file);
+    }
+  }
+  const report = {
+    runId: targetRunId,
+    appliedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    restored,
+    skippedSensitive,
+    failed,
+    forced: force
+  };
+  const reportPath = path13.join(getRestoresDir(cwd), `${targetRunId}.report.${Date.now()}.json`);
+  fs13.writeFileSync(reportPath, JSON.stringify(report, null, 2), "utf-8");
+  console.log("");
+  console.log(BOLD("RunTrim") + DIM("  restore apply"));
+  console.log("");
+  console.log(DIM("  Run ID             ") + chalk.white(targetRunId));
+  console.log(DIM("  Restored files     ") + chalk.white(String(restored.length)));
+  console.log(DIM("  Skipped sensitive  ") + chalk.white(String(skippedSensitive.length)));
+  console.log(DIM("  Failed             ") + chalk.white(String(failed.length)));
+  console.log(DIM("  Report             ") + chalk.white(path13.relative(cwd, reportPath)));
+  console.log("");
+  if (failed.length > 0) process.exit(1);
+});
 program.command("guard <task>").description("Audit a task and generate a guarded run contract").action(async (task) => {
   var _a2, _b, _c;
   const cwd = process.cwd();
@@ -9861,7 +10665,7 @@ program.command("guard <task>").description("Audit a task and generate a guarded
     const run2 = saveRun(task, audit, contract, cwd);
     updateRun(run2.id, { status: "blocked" }, cwd);
     console.log("");
-    console.log(DIM("  Run saved: .runtrim/runs/" + run2.id + ".json  (status: blocked)"));
+    console.log(DIM("  Run saved: .runtrim/internal/runs/" + run2.id + ".json  (status: blocked)"));
     console.log("");
     console.log(DIM("  Next:  ") + chalk.white('runtrim guard "<one system at a time>"'));
     console.log("");
@@ -9941,7 +10745,7 @@ program.command("guard <task>").description("Audit a task and generate a guarded
   }
   const run = saveRun(task, audit, contract, cwd);
   console.log("");
-  console.log(DIM("  Run saved: .runtrim/runs/" + run.id + ".json"));
+  console.log(DIM("  Run saved: .runtrim/internal/runs/" + run.id + ".json"));
   console.log("");
   console.log(DIM("  After your agent run:  ") + chalk.white("runtrim check"));
   console.log("");
@@ -9991,6 +10795,7 @@ program.command("run <task>").description("Guard then run configured local agent
       },
       cwd
     );
+    await captureRestorePoint(cwd, run.id, task);
     const copySavings = estimateSavingsFromTokens2(
       parseEstimatedNumber3(String(contract.estimatedTokensTrimmed))
     );
@@ -10071,6 +10876,7 @@ program.command("run <task>").description("Guard then run configured local agent
       },
       cwd
     );
+    await captureRestorePoint(cwd, run.id, task);
     console.log(DIM("  Execution cancelled. Guarded contract copied to clipboard."));
     console.log("");
     return;
@@ -10127,6 +10933,7 @@ program.command("run <task>").description("Guard then run configured local agent
         },
         cwd
       );
+      await captureRestorePoint(cwd, run.id, task);
       console.log("");
       console.log(chalk.yellow("  Agent command not found. Falling back to copy mode guidance."));
       console.log(DIM("  Configure with: npm run runtrim -- agent set claude|codex|custom"));
@@ -10160,6 +10967,7 @@ program.command("run <task>").description("Guard then run configured local agent
       },
       cwd
     );
+    await captureRestorePoint(cwd, run.id, task);
     console.log("");
     console.log(chalk.yellow("  Agent command not found. Falling back to copy mode guidance."));
     console.log(DIM("  Configure with: npm run runtrim -- agent set claude|codex|custom"));
@@ -10203,7 +11011,7 @@ ${stderr}`, "utf-8");
         exitCode,
         stdoutPreview: stdout.slice(0, OUTPUT_PREVIEW_MAX),
         stderrPreview: stderr.slice(0, OUTPUT_PREVIEW_MAX),
-        outputPath: `.runtrim/runs/${run.id}.output.txt`
+        outputPath: `.runtrim/internal/runs/${run.id}.output.txt`
       },
       evaluation
     },
@@ -10353,6 +11161,7 @@ program.command("go <task>").description("Bridge Mode: generate a scoped contrac
     memoryUsed,
     providerRouting
   }, cwd);
+  await captureRestorePoint(cwd, run.id, task);
   const bridgeCtx = deriveBridgeContext(task, contract, runs, projectName);
   let bridgeWritten = [];
   let bridgeManagedPaths = [];
@@ -10411,7 +11220,7 @@ program.command("go <task>").description("Bridge Mode: generate a scoped contrac
   if (contract.contract.stopRules.length > 0) {
     console.log(DIM("  Stop rule     ") + chalk.white(truncate((_g = contract.contract.stopRules[contract.contract.stopRules.length - 1]) != null ? _g : "", 60)));
   }
-  console.log(DIM("  Run saved     ") + chalk.white(`.runtrim/runs/${run.id}.json`));
+  console.log(DIM("  Run saved     ") + chalk.white(`.runtrim/internal/runs/${run.id}.json`));
   console.log(DIM("  Contract      ") + chalk.white("created"));
   console.log("");
   if (bridgeWritten.length > 0) {
@@ -11766,6 +12575,18 @@ program.command("finish").description("Bridge Mode: evaluate agent output, check
   const blockedByExistingHard = scope.forbiddenFiles.length > 0 || scope.status === "limit_exceeded";
   const warnBySensitiveIgnored = sensitiveIgnored.length > 0;
   const finishVerdict = blockedBySensitive || blockedByContract || blockedByExistingHard ? "BLOCKED" : warnBySensitiveIgnored || scopeDriftStatus !== "passed" || evaluation.status === "needs_verification" || evaluation.status === "partial" ? "WARN" : "PASS";
+  const restoreRecord = loadRestorePoint(cwd, activeRun.id);
+  if (restoreRecord) {
+    restoreRecord.postRun = {
+      changedFiles,
+      forbiddenFiles: [...scope.forbiddenFiles, ...forbiddenPathFiles],
+      sensitiveFiles: scope.sensitiveFiles,
+      outOfScopeFiles: [...outOfContractFiles, ...scope.outOfScopeFiles],
+      finishVerdict,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    saveRestorePoint(cwd, restoreRecord);
+  }
   const verdictColor = finishVerdict === "PASS" ? chalk.green : finishVerdict === "WARN" ? chalk.yellow : chalk.red;
   const scopeColor = scopeDriftStatus === "passed" ? chalk.green : scopeDriftStatus === "forbidden_touched" ? chalk.red : chalk.yellow;
   const riskAfter = (_m = activeRun.contract.wasteRiskAfter) != null ? _m : "medium";