runtrim 0.1.17 → 0.1.18

package/dist-cli/runtrim.cjs

@@ -687,6 +687,28 @@ function buildCategoryScope(category, hasSrc, hasApp, hasPages) {
           "Check no regression in adjacent routes"
         ]
       };
+    case "docs":
+      return {
+        allowedHints: [
+          "README.md - project documentation",
+          "docs/ - documentation files",
+          "CHANGELOG.md or CONTRIBUTING.md if task-specific"
+        ],
+        forbiddenAdditions: [
+          "Do not touch auth internals, session logic, or JWT handling",
+          "Do not touch billing, subscription, payment, or webhook logic",
+          "Do not touch database schema or migrations",
+          "Do not touch .env files or secrets"
+        ],
+        stopRules: [
+          "Stop if the requested change requires code-path behavior changes outside docs",
+          "Stop if sensitive files or secrets are referenced"
+        ],
+        verificationSteps: [
+          "Confirm documentation text matches the requested task",
+          "Check markdown formatting renders correctly"
+        ]
+      };
     default:
       return {
         allowedHints: [],
@@ -2598,7 +2620,7 @@ function buildSyncPayload(input) {
   var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t;
   const { cwd, projectName, config, projectAudit, memoryMarkdown, runs } = input;
   const latest = runs[0];
-  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  const nowIso2 = (/* @__PURE__ */ new Date()).toISOString();
   const localProjectId = buildLocalProjectId(cwd);
   const latestPromptText = readTextFileIfExists(import_path6.default.join(cwd, ".runtrim", "latest-prompt.md"));
   const continuationPromptText = readTextFileIfExists(
@@ -2660,7 +2682,7 @@ function buildSyncPayload(input) {
       name: resolveProjectName2(cwd, projectName, projectAudit == null ? void 0 : projectAudit.projectName),
       stack: (_a2 = projectAudit == null ? void 0 : projectAudit.detectedStack) != null ? _a2 : config.stack ? config.stack.split(",").map((s) => s.trim()).filter(Boolean) : ["auto"],
       packageManager: (_c = (_b = projectAudit == null ? void 0 : projectAudit.packageManager) != null ? _b : config.packageManager) != null ? _c : null,
-      lastUpdated: nowIso
+      lastUpdated: nowIso2
     },
     memory: {
       markdown: memoryMarkdown,
@@ -2742,7 +2764,8 @@ function writeCanonicalRuntrimMd(cwd = process.cwd(), projectName) {
     "## How to start an AI coding task",
     "",
     "```",
-    'runtrim go "<task>"',
+    "runtrim start",
+    'runtrim agent "Your task" --copy',
     "```",
     "",
     "RunTrim creates a scoped contract, loads project memory, and generates a guarded prompt.",
@@ -2763,7 +2786,7 @@ function writeCanonicalRuntrimMd(cwd = process.cwd(), projectName) {
     "",
     "1. Read `.runtrim/contracts/latest.md`.",
     "   - If `Status: active` \u2014 a live task exists. Follow the contract strictly.",
-    '   - If `Status: none` \u2014 no active task. Ask the user to run `runtrim go "<task>"` first.',
+    '   - If `Status: none` \u2014 no active task. Ask the user to run `runtrim start` then `runtrim agent "Your task" --copy`.',
     "2. Do not assume any prior task is still active.",
     "3. Stay inside the allowed scope defined in the contract.",
     "4. Stop and ask before touching any forbidden area.",
@@ -2788,7 +2811,8 @@ function writeRestingContract(cwd = process.cwd()) {
     "Start one with:",
     "",
     "```",
-    'runtrim go "<your task>"',
+    "runtrim start",
+    'runtrim agent "Your task" --copy',
     "```",
     "",
     "---",
@@ -2811,7 +2835,8 @@ function writeRestingMemory(cwd = process.cwd()) {
     "Start a new session with:",
     "",
     "```",
-    'runtrim go "<your task>"',
+    "runtrim start",
+    'runtrim agent "Your task" --copy',
     "```",
     "",
     "---",
@@ -2932,7 +2957,7 @@ function writeBridgeInstructions(cwd = process.cwd()) {
     "1. Read `RUNTRIM.md`.",
     "2. Read `.runtrim/contracts/latest.md`.",
     "   - If `Status: active` \u2014 follow the contract strictly.",
-    '   - If `Status: none` \u2014 stop. Ask the user to run `runtrim go "<task>"` first.',
+    '   - If `Status: none` \u2014 stop. Ask the user to run `runtrim start` then `runtrim agent "Your task" --copy`.',
     "3. If the contract is active, read `.runtrim/memory/current.md` for session context.",
     "   If no active session, read `.runtrim/memory/baseline.md` for project baseline.",
     "",
@@ -3006,6 +3031,28 @@ function buildBridgePrompt(contractText, ctx) {
 // src/lib/run-watch.ts
 function normalizeScopeKeywords2(scope) {
   var _a2;
+  const genericStopwords = /* @__PURE__ */ new Set([
+    "read",
+    "write",
+    "reference",
+    "touch",
+    "modify",
+    "change",
+    "update",
+    "allow",
+    "scope",
+    "paths",
+    "path",
+    "files",
+    "file",
+    "only",
+    "with",
+    "without",
+    "before",
+    "after",
+    "inside",
+    "outside"
+  ]);
   const words = /* @__PURE__ */ new Set();
   for (const line of scope) {
     const lower = line.toLowerCase();
@@ -3015,7 +3062,7 @@ function normalizeScopeKeywords2(scope) {
     }
     const cleaned = lower.replace(/[^a-z0-9_./\s-]/g, " ").split(/\s+/).filter(Boolean);
     for (const token of cleaned) {
-      if (token.length >= 4) words.add(token);
+      if (token.length >= 4 && !genericStopwords.has(token)) words.add(token);
     }
   }
   return [...words];
@@ -3112,15 +3159,7 @@ var import_fs8 = __toESM(require("fs"), 1);
 var import_os = __toESM(require("os"), 1);
 var import_path8 = __toESM(require("path"), 1);
 var import_execa2 = require("execa");
-var DEFAULT_REGISTRY = {
-  version: 1,
-  plan: "free",
-  trackedRepos: [],
-  telemetry: {
-    enabled: false,
-    anonymousId: ""
-  }
-};
+var EMPTY_TELEMETRY = { enabled: false, anonymousId: "" };
 function normalizeRepoPath(input) {
   const resolved = import_path8.default.resolve(input);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
@@ -3128,41 +3167,208 @@ function normalizeRepoPath(input) {
 function hashValue(value) {
   return import_crypto2.default.createHash("sha256").update(value).digest("hex").slice(0, 16);
 }
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function randomId(prefix) {
+  return `${prefix}_${import_crypto2.default.randomBytes(12).toString("hex")}`;
+}
 function getGlobalRunTrimDir() {
   return import_path8.default.join(import_os.default.homedir(), ".runtrim");
 }
 function getGlobalRegistryPath() {
   return import_path8.default.join(getGlobalRunTrimDir(), "global.json");
 }
-function loadGlobalRegistry() {
+function getInstallStatePath() {
+  return import_path8.default.join(getGlobalRunTrimDir(), "install-state.json");
+}
+function buildSealInput(registry) {
+  const tracked = [...registry.trackedRepos].map((r) => ({
+    id: r.id,
+    name: r.name,
+    path: normalizeRepoPath(r.path),
+    gitRemote: r.gitRemote,
+    createdAt: r.createdAt,
+    lastSeenAt: r.lastSeenAt
+  })).sort((a, b) => `${a.id}:${a.path}`.localeCompare(`${b.id}:${b.path}`));
+  const payload = {
+    version: registry.version,
+    stateVersion: registry.stateVersion,
+    plan: registry.plan,
+    machineInstallId: registry.machineInstallId,
+    createdAt: registry.createdAt,
+    updatedAt: registry.updatedAt,
+    trackedRepos: tracked,
+    lastKnownRepo: registry.lastKnownRepo ? __spreadProps(__spreadValues({}, registry.lastKnownRepo), {
+      path: normalizeRepoPath(registry.lastKnownRepo.path)
+    }) : null
+  };
+  return JSON.stringify(payload);
+}
+function computeSeal(registry) {
+  return import_crypto2.default.createHash("sha256").update(buildSealInput(registry)).digest("hex");
+}
+function sanitizeTrackedRepoEntry(input) {
+  var _a2, _b, _c, _d, _e, _f;
+  const id = String((_a2 = input.id) != null ? _a2 : "").trim();
+  const rawPath = String((_b = input.path) != null ? _b : "").trim();
+  if (!id || !rawPath) return null;
+  return {
+    id,
+    name: String((_c = input.name) != null ? _c : "").trim(),
+    path: normalizeRepoPath(rawPath),
+    gitRemote: String((_d = input.gitRemote) != null ? _d : "").trim(),
+    createdAt: String((_e = input.createdAt) != null ? _e : "").trim(),
+    lastSeenAt: String((_f = input.lastSeenAt) != null ? _f : "").trim()
+  };
+}
+function readInstallStateRaw() {
+  var _a2, _b, _c;
+  const p = getInstallStatePath();
+  if (!import_fs8.default.existsSync(p)) return { exists: false, state: null };
+  try {
+    const parsed = JSON.parse(import_fs8.default.readFileSync(p, "utf-8"));
+    const machineInstallId = String((_a2 = parsed.machineInstallId) != null ? _a2 : "").trim();
+    if (!machineInstallId) return { exists: true, state: null };
+    return {
+      exists: true,
+      state: {
+        machineInstallId,
+        createdAt: String((_b = parsed.createdAt) != null ? _b : "").trim() || nowIso(),
+        updatedAt: String((_c = parsed.updatedAt) != null ? _c : "").trim() || nowIso()
+      }
+    };
+  } catch (e) {
+    return { exists: true, state: null };
+  }
+}
+function writeInstallState(state) {
+  const dir = getGlobalRunTrimDir();
+  if (!import_fs8.default.existsSync(dir)) import_fs8.default.mkdirSync(dir, { recursive: true });
+  import_fs8.default.writeFileSync(getInstallStatePath(), JSON.stringify(state, null, 2), "utf-8");
+}
+function ensureInstallState() {
+  const raw = readInstallStateRaw();
+  if (raw.exists && raw.state) return raw.state;
+  const created = {
+    machineInstallId: randomId("rt_install"),
+    createdAt: nowIso(),
+    updatedAt: nowIso()
+  };
+  writeInstallState(created);
+  return created;
+}
+function buildDefaultRegistry(install) {
+  const base = {
+    version: 2,
+    stateVersion: 2,
+    plan: "free",
+    machineInstallId: install.machineInstallId,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    trackedRepos: [],
+    lastKnownRepo: null,
+    telemetry: __spreadValues({}, EMPTY_TELEMETRY)
+  };
+  return __spreadProps(__spreadValues({}, base), {
+    integrity: {
+      algorithm: "sha256-local-seal-v1",
+      seal: computeSeal(base)
+    }
+  });
+}
+function saveRegistryWithSeal(registry) {
+  var _a2;
+  const dir = getGlobalRunTrimDir();
+  if (!import_fs8.default.existsSync(dir)) import_fs8.default.mkdirSync(dir, { recursive: true });
+  const normalizedBase = __spreadProps(__spreadValues({}, registry), {
+    version: 2,
+    stateVersion: 2,
+    trackedRepos: registry.trackedRepos.map((r) => __spreadProps(__spreadValues({}, r), { path: normalizeRepoPath(r.path) })),
+    telemetry: (_a2 = registry.telemetry) != null ? _a2 : __spreadValues({}, EMPTY_TELEMETRY)
+  });
+  const sealed = __spreadProps(__spreadValues({}, normalizedBase), {
+    integrity: {
+      algorithm: "sha256-local-seal-v1",
+      seal: computeSeal(normalizedBase)
+    }
+  });
+  import_fs8.default.writeFileSync(getGlobalRegistryPath(), JSON.stringify(sealed, null, 2), "utf-8");
+}
+function inspectGlobalRegistry() {
+  var _a2, _b, _c, _d, _e, _f, _g, _h, _i;
+  const installRaw = readInstallStateRaw();
+  const install = (_a2 = installRaw.state) != null ? _a2 : ensureInstallState();
   const registryPath = getGlobalRegistryPath();
-  if (!import_fs8.default.existsSync(registryPath)) return __spreadValues({}, DEFAULT_REGISTRY);
+  const defaultRegistry = buildDefaultRegistry(install);
+  if (!import_fs8.default.existsSync(registryPath)) {
+    if (installRaw.exists) {
+      return {
+        registry: defaultRegistry,
+        needsRepair: true,
+        repairReason: "missing_registry_after_initialization"
+      };
+    }
+    return { registry: defaultRegistry, needsRepair: false, repairReason: null };
+  }
   try {
     const raw = JSON.parse(import_fs8.default.readFileSync(registryPath, "utf-8"));
-    return {
-      version: 1,
+    const trackedRepos = Array.isArray(raw.trackedRepos) ? raw.trackedRepos.map((item) => sanitizeTrackedRepoEntry(item)).filter((item) => Boolean(item)) : [];
+    const base = {
+      version: 2,
+      stateVersion: 2,
       plan: raw.plan === "free" ? "free" : "free",
-      trackedRepos: Array.isArray(raw.trackedRepos) ? raw.trackedRepos.filter((item) => Boolean(item && typeof item === "object")).map((item) => ({
-        id: String(item.id || ""),
-        name: String(item.name || ""),
-        path: normalizeRepoPath(String(item.path || "")),
-        gitRemote: String(item.gitRemote || ""),
-        createdAt: String(item.createdAt || ""),
-        lastSeenAt: String(item.lastSeenAt || "")
-      })).filter((item) => Boolean(item.id && item.path)) : [],
+      machineInstallId: String((_b = raw.machineInstallId) != null ? _b : "").trim() || install.machineInstallId,
+      createdAt: String((_c = raw.createdAt) != null ? _c : "").trim() || nowIso(),
+      updatedAt: String((_d = raw.updatedAt) != null ? _d : "").trim() || nowIso(),
+      trackedRepos,
+      lastKnownRepo: raw.lastKnownRepo && typeof raw.lastKnownRepo === "object" ? {
+        id: String((_e = raw.lastKnownRepo.id) != null ? _e : "").trim(),
+        name: String((_f = raw.lastKnownRepo.name) != null ? _f : "").trim(),
+        path: normalizeRepoPath(String((_g = raw.lastKnownRepo.path) != null ? _g : "")),
+        gitRemote: String((_h = raw.lastKnownRepo.gitRemote) != null ? _h : "").trim(),
+        lastSeenAt: String((_i = raw.lastKnownRepo.lastSeenAt) != null ? _i : "").trim() || nowIso()
+      } : null,
       telemetry: {
         enabled: typeof raw.telemetry === "object" && raw.telemetry !== null && Boolean(raw.telemetry.enabled),
         anonymousId: typeof raw.telemetry === "object" && raw.telemetry !== null && typeof raw.telemetry.anonymousId === "string" ? String(raw.telemetry.anonymousId).slice(0, 120) : ""
       }
     };
+    const normalized = __spreadProps(__spreadValues({}, base), {
+      integrity: {
+        algorithm: "sha256-local-seal-v1",
+        seal: raw.integrity && typeof raw.integrity === "object" && typeof raw.integrity.seal === "string" ? String(raw.integrity.seal) : ""
+      }
+    });
+    if (normalized.machineInstallId !== install.machineInstallId) {
+      return {
+        registry: normalized,
+        needsRepair: true,
+        repairReason: "machine_install_id_mismatch"
+      };
+    }
+    const expectedSeal = computeSeal(base);
+    if (!normalized.integrity.seal || normalized.integrity.seal !== expectedSeal) {
+      return {
+        registry: normalized,
+        needsRepair: true,
+        repairReason: "integrity_seal_mismatch"
+      };
+    }
+    return { registry: normalized, needsRepair: false, repairReason: null };
   } catch (e) {
-    return __spreadValues({}, DEFAULT_REGISTRY);
+    return {
+      registry: defaultRegistry,
+      needsRepair: true,
+      repairReason: "registry_corrupt"
+    };
   }
 }
+function loadGlobalRegistry() {
+  return inspectGlobalRegistry().registry;
+}
 function saveGlobalRegistry(registry) {
-  const dir = getGlobalRunTrimDir();
-  if (!import_fs8.default.existsSync(dir)) import_fs8.default.mkdirSync(dir, { recursive: true });
-  import_fs8.default.writeFileSync(getGlobalRegistryPath(), JSON.stringify(registry, null, 2), "utf-8");
+  saveRegistryWithSeal(registry);
 }
 async function getCurrentRepoIdentity(cwd = process.cwd()) {
   const normalizedPath = normalizeRepoPath(cwd);
@@ -3192,36 +3398,71 @@ function findTrackedRepo(trackedRepos, currentRepo) {
   return byPath != null ? byPath : null;
 }
 async function assertFreeRepoAllowed(cwd = process.cwd()) {
-  const registry = loadGlobalRegistry();
+  const inspected = inspectGlobalRegistry();
+  const registry = inspected.registry;
   const currentRepo = await getCurrentRepoIdentity(cwd);
   const trackedRepo = findTrackedRepo(registry.trackedRepos, currentRepo);
-  if (registry.plan !== "free") {
-    return { allowed: true, plan: registry.plan, currentRepo, trackedRepo };
+  const base = {
+    plan: registry.plan,
+    currentRepo,
+    trackedRepo,
+    registryPath: getGlobalRegistryPath()
+  };
+  if (inspected.needsRepair) {
+    return __spreadProps(__spreadValues({}, base), {
+      allowed: false,
+      status: "blocked_repair",
+      repairRequired: true,
+      repairReason: inspected.repairReason
+    });
   }
-  if (trackedRepo) {
-    return { allowed: true, plan: registry.plan, currentRepo, trackedRepo };
+  if (registry.plan !== "free") {
+    return __spreadProps(__spreadValues({}, base), {
+      allowed: true,
+      status: "allowed",
+      repairRequired: false,
+      repairReason: null
+    });
   }
-  if (registry.trackedRepos.length === 0) {
-    return { allowed: true, plan: registry.plan, currentRepo, trackedRepo: null };
+  if (trackedRepo || registry.trackedRepos.length === 0) {
+    return __spreadProps(__spreadValues({}, base), {
+      allowed: true,
+      status: "allowed",
+      repairRequired: false,
+      repairReason: null
+    });
   }
-  return {
+  return __spreadProps(__spreadValues({}, base), {
     allowed: false,
-    plan: registry.plan,
-    currentRepo,
+    status: "blocked_limit",
+    repairRequired: false,
+    repairReason: null,
     trackedRepo: registry.trackedRepos[0]
-  };
+  });
 }
 async function registerCurrentRepo(cwd = process.cwd()) {
+  const check = await assertFreeRepoAllowed(cwd);
+  if (!check.allowed && check.status === "blocked_repair") {
+    throw new Error("runtrim_local_state_repair_required");
+  }
   const registry = loadGlobalRegistry();
   const currentRepo = await getCurrentRepoIdentity(cwd);
-  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const now = nowIso();
   const existing = findTrackedRepo(registry.trackedRepos, currentRepo);
   if (existing) {
     existing.lastSeenAt = now;
     existing.name = currentRepo.name;
     existing.path = currentRepo.path;
     existing.gitRemote = currentRepo.gitRemote;
-    saveGlobalRegistry(registry);
+    registry.updatedAt = now;
+    registry.lastKnownRepo = {
+      id: currentRepo.id,
+      name: currentRepo.name,
+      path: currentRepo.path,
+      gitRemote: currentRepo.gitRemote,
+      lastSeenAt: now
+    };
+    saveRegistryWithSeal(registry);
     return existing;
   }
   const entry = {
@@ -3232,24 +3473,110 @@ async function registerCurrentRepo(cwd = process.cwd()) {
     createdAt: now,
     lastSeenAt: now
   };
-  registry.trackedRepos.push(entry);
-  saveGlobalRegistry(registry);
+  registry.trackedRepos = [entry];
+  registry.updatedAt = now;
+  registry.lastKnownRepo = {
+    id: entry.id,
+    name: entry.name,
+    path: entry.path,
+    gitRemote: entry.gitRemote,
+    lastSeenAt: now
+  };
+  saveRegistryWithSeal(registry);
   return entry;
 }
+async function repairGlobalRegistry(cwd = process.cwd(), options = {}) {
+  const before = await assertFreeRepoAllowed(cwd);
+  if (!before.repairRequired) {
+    return { repaired: false, check: before };
+  }
+  const install = ensureInstallState();
+  const now = nowIso();
+  const repaired = buildDefaultRegistry(install);
+  repaired.createdAt = now;
+  repaired.updatedAt = now;
+  if (options.useCurrentRepo) {
+    const currentRepo = await getCurrentRepoIdentity(cwd);
+    repaired.trackedRepos = [
+      {
+        id: currentRepo.id,
+        name: currentRepo.name,
+        path: currentRepo.path,
+        gitRemote: currentRepo.gitRemote,
+        createdAt: now,
+        lastSeenAt: now
+      }
+    ];
+    repaired.lastKnownRepo = {
+      id: currentRepo.id,
+      name: currentRepo.name,
+      path: currentRepo.path,
+      gitRemote: currentRepo.gitRemote,
+      lastSeenAt: now
+    };
+  }
+  saveRegistryWithSeal(repaired);
+  const check = await assertFreeRepoAllowed(cwd);
+  return { repaired: true, check };
+}
 async function unlinkCurrentRepo(cwd = process.cwd(), force = false) {
   var _a2;
+  const check = await assertFreeRepoAllowed(cwd);
+  if (check.status === "blocked_repair") {
+    if (!force) {
+      return {
+        removed: false,
+        forced: false,
+        currentRepo: check.currentRepo,
+        trackedRepo: null
+      };
+    }
+    const install = ensureInstallState();
+    const repaired = buildDefaultRegistry(install);
+    repaired.updatedAt = nowIso();
+    repaired.lastKnownRepo = {
+      id: check.currentRepo.id,
+      name: check.currentRepo.name,
+      path: check.currentRepo.path,
+      gitRemote: check.currentRepo.gitRemote,
+      lastSeenAt: repaired.updatedAt
+    };
+    saveRegistryWithSeal(repaired);
+    return {
+      removed: true,
+      forced: true,
+      currentRepo: check.currentRepo,
+      trackedRepo: null
+    };
+  }
   const registry = loadGlobalRegistry();
   const currentRepo = await getCurrentRepoIdentity(cwd);
   const trackedRepo = findTrackedRepo(registry.trackedRepos, currentRepo);
   if (trackedRepo) {
     registry.trackedRepos = registry.trackedRepos.filter((repo) => repo.id !== trackedRepo.id);
-    saveGlobalRegistry(registry);
+    registry.updatedAt = nowIso();
+    registry.lastKnownRepo = {
+      id: trackedRepo.id,
+      name: trackedRepo.name,
+      path: trackedRepo.path,
+      gitRemote: trackedRepo.gitRemote,
+      lastSeenAt: registry.updatedAt
+    };
+    saveRegistryWithSeal(registry);
     return { removed: true, forced: false, currentRepo, trackedRepo };
   }
   if (force && registry.trackedRepos.length > 0) {
     const first = registry.trackedRepos[0];
     registry.trackedRepos = [];
-    saveGlobalRegistry(registry);
+    registry.updatedAt = nowIso();
+    registry.lastKnownRepo = {
+      id: first.id,
+      name: first.name,
+      path: first.path,
+      gitRemote: first.gitRemote,
+      lastSeenAt: registry.updatedAt
+    };
+    saveRegistryWithSeal(registry);
     return { removed: true, forced: true, currentRepo, trackedRepo: first };
   }
   return {
@@ -7150,6 +7477,24 @@ async function buildRuntrimCreateContractMcp(cwd, args) {
       isError: true
     };
   }
+  const repoCheck = await assertFreeRepoAllowed(cwd);
+  if (!repoCheck.allowed) {
+    const guidance = repoCheck.status === "blocked_repair" ? "RunTrim local state needs repair. Free includes 1 tracked repo. The local repo registry changed unexpectedly. Repair the registry or upgrade to Builder for unlimited repos." : "Free includes 1 tracked repo. This repo is not currently tracked. Continue in the tracked repo, unlink the tracked repo with runtrim repo unlink --force, or upgrade to Builder for unlimited repos.";
+    const blockedPayload = {
+      contract_created: false,
+      task: taskRaw,
+      error: repoCheck.status === "blocked_repair" ? "repo_registry_repair_required" : "repo_limit_blocked",
+      guidance,
+      next_action: guidance,
+      finish_command: "runtrim finish",
+      approval_command_example: 'runtrim approve "Allow <path> for this run only"'
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(blockedPayload, null, 2) }],
+      structuredContent: blockedPayload,
+      isError: true
+    };
+  }
   const latest = loadLatestRun(cwd);
   if ((latest == null ? void 0 : latest.status) === "guarded") {
     const blockedPayload = {
@@ -7811,6 +8156,21 @@ function isInteractiveTerminal() {
 async function ensureRepoAllowedForFree(cwd) {
   var _a2, _b;
   const check = await assertFreeRepoAllowed(cwd);
+  if (check.status === "blocked_repair") {
+    console.log(chalk.yellow("  RunTrim local state needs repair."));
+    console.log(chalk.yellow("  Free includes 1 tracked repo."));
+    console.log(chalk.yellow("  Your local repo registry changed unexpectedly."));
+    console.log("");
+    console.log(DIM("  Next:"));
+    console.log(chalk.white("  - runtrim repo status"));
+    console.log(chalk.white("  - runtrim repo repair"));
+    console.log(chalk.white("  - runtrim repo repair --use-current"));
+    console.log(chalk.white("  - runtrim repo unlink --force"));
+    console.log(chalk.white("  - upgrade to Builder for unlimited repos"));
+    console.log(chalk.white("  - sign in to restore cloud entitlements"));
+    console.log("");
+    return false;
+  }
   if (check.allowed) {
     await registerCurrentRepo(cwd);
     return true;
@@ -7824,9 +8184,12 @@ async function ensureRepoAllowedForFree(cwd) {
   console.log(chalk.white(`  ${check.currentRepo.path}`));
   console.log("");
   console.log(DIM("  Next:"));
-  console.log(chalk.white("  - continue in the tracked repo"));
-  console.log(chalk.white("  - unlink the tracked repo with runtrim repo unlink --force"));
-  console.log(chalk.white("  - join Builder early access for unlimited repos"));
+  console.log(
+    chalk.white(
+      "  Free includes 1 tracked repo. This repo is not currently tracked. Continue in the tracked repo, unlink the tracked repo with runtrim repo unlink --force, or upgrade to Builder for unlimited repos."
+    )
+  );
+  console.log(chalk.white("  Agent instructions were not installed because this repo is not tracked."));
   console.log("");
   console.log(
     DIM(
@@ -8193,7 +8556,8 @@ var PROTOCOL_POINTER_BLOCK = `
 ${PROTOCOL_BLOCK_START}
 This repo uses RunTrim as the guarded AI coding protocol.
 Before editing code, read RUNTRIM.md.
-Start every task with: runtrim go "<task>"
+Start every task with: runtrim start
+Then run: runtrim agent "Your task" --copy
 Stay inside .runtrim/contracts/latest.md.
 After edits, ask the user to run: runtrim finish
 ${PROTOCOL_BLOCK_END}
@@ -8889,6 +9253,8 @@ program.command("execute <task>").description("Create a controlled execution pac
 var agentCommand = program.command("agent").description("Start a guarded AI coding run with contract, scope, memory, and handoff");
 agentCommand.argument("[task]").option("--copy", "Copy the handoff to clipboard").option("--bridge", "Ensure local bridge is running for this agent run").option("--preview", "Generate an execution preview instead of running any agent").option("--apply", "Generate Agent Apply handoff artifacts").option("--execute", "Create a controlled execution packet and handoff").option("--run", "Alias for --execute").option("--dry-run", "Create execution packet in pending mode without ready status").option("--confirm", "Confirm high-risk apply handoff creation").action(async (task, options) => {
   if (task == null ? void 0 : task.trim()) {
+    const allowed = await ensureRepoAllowedForFree(process.cwd());
+    if (!allowed) return;
     const normalizedTask = (task != null ? task : "").trim();
     if (options == null ? void 0 : options.bridge) {
       const bridge = await ensureBridgeRunningForAgent(process.cwd());
@@ -9357,12 +9723,54 @@ repoCommand.command("status").description("Show local tracked repo status").acti
   console.log(DIM("  Current repo  ") + chalk.white(identity.path));
   console.log(DIM("  Tracked repo  ") + chalk.white((_b = tracked == null ? void 0 : tracked.path) != null ? _b : "(none)"));
   console.log(DIM("  Allowed       ") + chalk.white(check.allowed ? "yes" : "no"));
+  console.log(DIM("  State         ") + chalk.white(check.status));
   console.log("");
+  if (check.status === "blocked_repair") {
+    console.log(chalk.yellow("  RunTrim local state needs repair."));
+    console.log(chalk.yellow("  Free includes 1 tracked repo."));
+    console.log(chalk.yellow("  The local repo registry changed unexpectedly."));
+    console.log(DIM("  Run: runtrim repo repair"));
+    console.log("");
+  }
   if (tracked) {
     console.log(DIM("  A tracked repo is one codebase with its own .runtrim workspace."));
     console.log("");
   }
 });
+repoCommand.command("repair").description("Repair local free-plan repo registry integrity").option("--use-current", "Repair and set the current repo as the single tracked Free repo").action(async (options) => {
+  const cwd = process.cwd();
+  const before = await assertFreeRepoAllowed(cwd);
+  console.log("");
+  console.log(BOLD("RunTrim") + DIM("  repo repair"));
+  console.log("");
+  if (!before.repairRequired) {
+    console.log(DIM("  Local state is healthy. No repair required."));
+    console.log("");
+    return;
+  }
+  if (!options.useCurrent) {
+    console.log(chalk.yellow("  RunTrim local state needs repair."));
+    console.log(chalk.yellow("  Free includes 1 tracked repo."));
+    console.log(chalk.yellow("  Your local repo registry changed unexpectedly."));
+    console.log("");
+    console.log(DIM("  Safe next actions:"));
+    console.log(chalk.white("  - runtrim repo repair --use-current"));
+    console.log(chalk.white("  - runtrim repo unlink --force"));
+    console.log(chalk.white("  - upgrade to Builder for unlimited repos"));
+    console.log(chalk.white("  - sign in to restore cloud entitlements"));
+    console.log("");
+    return;
+  }
+  const result = await repairGlobalRegistry(cwd, { useCurrentRepo: true });
+  if (result.repaired) {
+    console.log(ACCENT.bold("  Local registry repaired."));
+    console.log(DIM("  Current repo is now the tracked Free repo."));
+    console.log("");
+    return;
+  }
+  console.log(DIM("  No repair changes applied."));
+  console.log("");
+});
 repoCommand.command("unlink").description("Unlink tracked repo from local free-plan registry").option("--force", "Force unlink tracked repo even when running from another path").action(async (options) => {
   const cwd = process.cwd();
   const result = await unlinkCurrentRepo(cwd, Boolean(options.force));
@@ -10529,7 +10937,7 @@ program.command("continue").description("Create a safe continuation prompt from
   const audit = (_a2 = loadProjectAudit(cwd)) != null ? _a2 : performBaselineProjectAudit(cwd, null);
   const reason = normalizeContinuationReason(options.reason);
   const agent = normalizeContinuationAgent(options.agent, config.defaultAgent);
-  const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+  const nowIso2 = (/* @__PURE__ */ new Date()).toISOString();
   const continuationPath = resolveContinuationPath(cwd);
   const latestPromptPath = resolvePromptPath(config, cwd);
   const latestPrompt = import_fs13.default.existsSync(latestPromptPath) ? import_fs13.default.readFileSync(latestPromptPath, "utf-8").trim() : "";
@@ -10719,14 +11127,14 @@ program.command("continue").description("Create a safe continuation prompt from
   import_fs13.default.writeFileSync(continuationPath, continuationPrompt, "utf-8");
   const copied = await copyToClipboardSafe(continuationPrompt);
   if (memory) {
-    const memoryWithContinuation = updateMemoryWithContinuation(memory, reason, continuationPath, nowIso);
+    const memoryWithContinuation = updateMemoryWithContinuation(memory, reason, continuationPath, nowIso2);
     import_fs13.default.writeFileSync(import_path13.default.join(getConfigDir(cwd), "memory.md"), memoryWithContinuation, "utf-8");
   }
   if (hasConfig) {
     const nextConfig = __spreadProps(__spreadValues({}, config), {
       lastContinuationReason: reason,
       continuationPromptPath: continuationPath.replace(/\\/g, "/"),
-      continuationCreatedAt: nowIso
+      continuationCreatedAt: nowIso2
     });
     saveConfig(nextConfig, cwd);
   }
@@ -11518,6 +11926,8 @@ program.command("finish").description("Bridge Mode: evaluate agent output, check
 program.command("sync").description("Sync local run history and project memory to your RunTrim dashboard").option("--dry-run", "Show what would be synced without uploading").action(async (opts) => {
   var _a2, _b;
   const cwd = process.cwd();
+  const allowed = await ensureRepoAllowedForFree(cwd);
+  if (!allowed) return;
   console.log("");
   console.log(BOLD("RunTrim") + DIM("  cloud sync"));
   console.log("");