@muggleai/works 5.19.0-staging.129 → 5.19.0-staging.131

package/dist/{chunk-JNYP5PWT.js → chunk-ODEPI25T.js}

@@ -1,4 +1,4 @@
-import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getActiveRuntimeTarget, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, reconcileProjectPreferences, getDataDir, PREFERENCES_FILE_NAME, isFirstRun, writePreferences, DEFAULT_PREFERENCES, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, getElectronAppSignedFromVersion, getReleaseSignerIdentityUri, verifyFileChecksum, calculateFileChecksum, initTelemetry, Surface, ServiceName, track, EventName, getQaTools, getLocalQaTools, performLogout, assertDeviceCodeClientProvisioned, performLogin, toolRequiresAuth, getCallerCredentials, hasShownDisclosure, markDisclosureShown, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require, getDisclosureCopy, buildOnboardingPlan, applyOnboardingAnswers, needsOnboarding, OnboardingBlanketChoice, PreferenceKey } from './chunk-ESPHO3WB.js';
+import { __export, getLogger, getConfig, createChildLogger, buildElectronAppReleaseAssetUrl, getActiveRuntimeTarget, getAuthService, hasApiKey, getElectronAppVersion, getElectronAppDir, getPlatformKey, reconcileProjectPreferences, getDataDir, PREFERENCES_FILE_NAME, isFirstRun, writePreferences, DEFAULT_PREFERENCES, isElectronAppInstalled, getElectronAppChecksums, getChecksumForPlatform, getElectronAppSignedFromVersion, getReleaseSignerIdentityUri, verifyFileChecksum, calculateFileChecksum, initTelemetry, Surface, ServiceName, track, EventName, getQaTools, getLocalQaTools, performLogout, assertDeviceCodeClientProvisioned, performLogin, toolRequiresAuth, getCallerCredentials, hasShownDisclosure, markDisclosureShown, getBundledElectronAppVersion, getElectronAppVersionSource, getCredentialsFilePath, buildElectronAppChecksumsUrl, __require, getDisclosureCopy, buildOnboardingPlan, applyOnboardingAnswers, needsOnboarding, OnboardingBlanketChoice, PreferenceKey } from './chunk-U6ZACW6K.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { v4 } from 'uuid';
@@ -754,7 +754,7 @@ async function resolveGsScreenshotUrls(report, opts) {
     if (gsUrls.length === 0) {
       return report;
     }
-    const mcps = await import('./src-ZF6QSZJV.js');
+    const mcps = await import('./src-C2IZ3MAZ.js');
     const credentials = await mcps.getCallerCredentialsAsync();
     if (!credentials.bearerToken && !credentials.apiKey) {
       stderrWrite(
@@ -807,7 +807,7 @@ var withSentinel = (s) => s ? `${REPORT_SECTION_SENTINEL}
 ${s}` : s;
 async function resolveDashboardBaseUrl(stderrWrite) {
   try {
-    const mcps = await import('./src-ZF6QSZJV.js');
+    const mcps = await import('./src-C2IZ3MAZ.js');
     return mcps.resolveActiveProfile().dashboardBaseUrl;
   } catch (err) {
     stderrWrite(

package/dist/{chunk-ESPHO3WB.js → chunk-U6ZACW6K.js}

@@ -2230,6 +2230,7 @@ var PreferenceKey = /* @__PURE__ */ ((PreferenceKey2) => {
   PreferenceKey2["AutoRouteBuildToMuggleDo"] = "autoRouteBuildToMuggleDo";
   PreferenceKey2["AutoWatchPR"] = "autoWatchPR";
   PreferenceKey2["WatcherLifetime"] = "watcherLifetime";
+  PreferenceKey2["MaxCatchUpRebases"] = "maxCatchUpRebases";
   PreferenceKey2["ReusePreparePlan"] = "reusePreparePlan";
   return PreferenceKey2;
 })(PreferenceKey || {});
@@ -2241,6 +2242,9 @@ var PreferenceValue = /* @__PURE__ */ ((PreferenceValue2) => {
   PreferenceValue2["Remote"] = "remote";
   PreferenceValue2["OneDay"] = "1d";
   PreferenceValue2["SevenDays"] = "7d";
+  PreferenceValue2["TenRebases"] = "10";
+  PreferenceValue2["TwentyRebases"] = "20";
+  PreferenceValue2["FiftyRebases"] = "50";
   return PreferenceValue2;
 })(PreferenceValue || {});
 
@@ -2271,7 +2275,8 @@ var DEFAULT_PREFERENCES = {
   ["autoRouteBuildToMuggleDo" /* AutoRouteBuildToMuggleDo */]: "always" /* Always */,
   ["autoWatchPR" /* AutoWatchPR */]: "always" /* Always */,
   ["reusePreparePlan" /* ReusePreparePlan */]: "always" /* Always */,
-  ["watcherLifetime" /* WatcherLifetime */]: "7d" /* SevenDays */
+  ["watcherLifetime" /* WatcherLifetime */]: "7d" /* SevenDays */,
+  ["maxCatchUpRebases" /* MaxCatchUpRebases */]: "20" /* TwentyRebases */
 };
 var ALWAYS_ASK_NEVER = [
   "always" /* Always */,
@@ -2292,6 +2297,12 @@ var WATCHER_LIFETIMES = [
   "7d" /* SevenDays */,
   "never" /* Never */
 ];
+var CATCH_UP_REBASE_BUDGETS = [
+  "10" /* TenRebases */,
+  "20" /* TwentyRebases */,
+  "50" /* FiftyRebases */,
+  "never" /* Never */
+];
 var PREFERENCE_ALLOWED_VALUES = {
   ["autoLogin" /* AutoLogin */]: ALWAYS_ASK_NEVER,
   ["autoSelectProject" /* AutoSelectProject */]: ALWAYS_ASK_NEVER,
@@ -2315,7 +2326,8 @@ var PREFERENCE_ALLOWED_VALUES = {
   ["autoRouteBuildToMuggleDo" /* AutoRouteBuildToMuggleDo */]: ALWAYS_ASK_NEVER,
   ["autoWatchPR" /* AutoWatchPR */]: ALWAYS_ASK_NEVER,
   ["reusePreparePlan" /* ReusePreparePlan */]: ALWAYS_ASK_NEVER,
-  ["watcherLifetime" /* WatcherLifetime */]: WATCHER_LIFETIMES
+  ["watcherLifetime" /* WatcherLifetime */]: WATCHER_LIFETIMES,
+  ["maxCatchUpRebases" /* MaxCatchUpRebases */]: CATCH_UP_REBASE_BUDGETS
 };
 var PREFERENCES_SCHEMA = {
   ["autoLogin" /* AutoLogin */]: {
@@ -2386,6 +2398,9 @@ var PREFERENCES_SCHEMA = {
   },
   ["watcherLifetime" /* WatcherLifetime */]: {
     description: "How long a muggle-pr-followup watch loop polls before retiring itself \u2014 1d, 7d, or never (unbounded, which leaves no time-based reaper for an orphaned loop)"
+  },
+  ["maxCatchUpRebases" /* MaxCatchUpRebases */]: {
+    description: "How many catch-up rebases muggle-pr-followup runs on one PR before it stops and reports the branch back to its owner \u2014 10, 20, 50, or never (unbounded, which lets an active base rebase a PR for as long as it stays open)"
   }
 };
 
@@ -3892,23 +3907,10 @@ __export(e2e_exports, {
   executeQaTool: () => executeQaTool,
   getQaToolByName: () => getQaToolByName
 });
-
-var ENV_CONNECTION_STRING = "APPLICATIONINSIGHTS_CONNECTION_STRING";
-var ENV_VITE_CONNECTION_STRING = "VITE_APPLICATIONINSIGHTS_CONNECTION_STRING";
-var ENV_TELEMETRY_DISABLED = "MUGGLE_TELEMETRY_DISABLED";
-
-var DATA_DIR_NAME2 = ".muggle-ai";
 var INSTALL_ID_FILENAME = "install-id.json";
-var PREFS_FILENAME = "preferences.json";
-var OAUTH_SESSION_FILENAME = "oauth-session.json";
-var RELEASE_MANIFEST_FILENAME = "release-manifest.json";
-function getDataDir3() {
-  return path11.join(os4.homedir(), DATA_DIR_NAME2);
-}
-
 var cachedInstallId;
 function installIdFilePath() {
-  return join(getDataDir3(), INSTALL_ID_FILENAME);
+  return join(getDataDir(), INSTALL_ID_FILENAME);
 }
 function generateAndPersist(filePath) {
   const installId = randomUUID();
@@ -3921,8 +3923,7 @@ function isValid(value) {
   return typeof value === "object" && value !== null && typeof value.installId === "string" && value.installId.length > 0;
 }
 function getInstallId() {
-  if (cachedInstallId !== void 0)
-    return cachedInstallId;
+  if (cachedInstallId !== void 0) return cachedInstallId;
   const filePath = installIdFilePath();
   if (!existsSync(filePath)) {
     cachedInstallId = generateAndPersist(filePath);
@@ -3943,6 +3944,113 @@ function getInstallId() {
   }
 }
 
+// packages/mcps/src/shared/register.ts
+var CONFLICT_STATUS = 409;
+var THROTTLED_STATUS = 429;
+async function registerAccount(email, userProvidedPassword) {
+  const logger6 = getLogger();
+  const config = getConfig();
+  const registerUrl = `${config.e2e.promptServiceBaseUrl}/v1/public/auth/register`;
+  try {
+    const response = await axios.post(
+      registerUrl,
+      {
+        email,
+        password: userProvidedPassword,
+        installId: getInstallId()
+      },
+      { headers: { "Content-Type": "application/json" } }
+    );
+    const created = response.data;
+    saveApiKey({ apiKey: created.apiKey, apiKeyId: created.userId });
+    logger6.info("[Register] Account created and credential stored", {
+      userId: created.userId,
+      plan: created.plan
+    });
+    return {
+      outcome: "created" /* Created */,
+      userId: created.userId,
+      email: created.email,
+      plan: created.plan,
+      emailVerified: created.emailVerified,
+      tokensGranted: created.tokensGranted,
+      tokensOnVerification: created.tokensOnVerification,
+      credentialStored: true,
+      message: `Account created on the ${created.plan} plan and the API key stored \u2014 remote tools will use it automatically. ${created.tokensGranted.toLocaleString()} tokens are available now. Verifying ${created.email} upgrades the account to the Starter package \u2014 free and permanent \u2014 and raises that to ${created.tokensOnVerification.toLocaleString()}.`
+    };
+  } catch (error) {
+    const status = axios.isAxiosError(error) ? error.response?.status : void 0;
+    if (status === CONFLICT_STATUS) {
+      return {
+        outcome: "already-registered" /* AlreadyRegistered */,
+        message: "An account already exists for this email. Use muggle-remote-auth-login to sign in instead."
+      };
+    }
+    if (status === THROTTLED_STATUS) {
+      const retryAfterSeconds = axios.isAxiosError(error) ? error.response?.data?.retryAfterSeconds : void 0;
+      return {
+        outcome: "throttled" /* Throttled */,
+        retryAfterSeconds,
+        message: retryAfterSeconds ? `Too many registrations from this machine. Try again in ${retryAfterSeconds} seconds.` : "Too many registrations from this machine. Try again later."
+      };
+    }
+    logger6.error("[Register] Registration failed", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+
+var ENV_CONNECTION_STRING = "APPLICATIONINSIGHTS_CONNECTION_STRING";
+var ENV_VITE_CONNECTION_STRING = "VITE_APPLICATIONINSIGHTS_CONNECTION_STRING";
+var ENV_TELEMETRY_DISABLED = "MUGGLE_TELEMETRY_DISABLED";
+
+var DATA_DIR_NAME2 = ".muggle-ai";
+var INSTALL_ID_FILENAME2 = "install-id.json";
+var PREFS_FILENAME = "preferences.json";
+var OAUTH_SESSION_FILENAME = "oauth-session.json";
+var RELEASE_MANIFEST_FILENAME = "release-manifest.json";
+function getDataDir3() {
+  return path11.join(os4.homedir(), DATA_DIR_NAME2);
+}
+
+var cachedInstallId2;
+function installIdFilePath2() {
+  return join(getDataDir3(), INSTALL_ID_FILENAME2);
+}
+function generateAndPersist2(filePath) {
+  const installId = randomUUID();
+  const contents = { installId };
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(contents, null, 2) + "\n", "utf8");
+  return installId;
+}
+function isValid2(value) {
+  return typeof value === "object" && value !== null && typeof value.installId === "string" && value.installId.length > 0;
+}
+function getInstallId2() {
+  if (cachedInstallId2 !== void 0)
+    return cachedInstallId2;
+  const filePath = installIdFilePath2();
+  if (!existsSync(filePath)) {
+    cachedInstallId2 = generateAndPersist2(filePath);
+    return cachedInstallId2;
+  }
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (isValid2(parsed)) {
+      cachedInstallId2 = parsed.installId;
+      return cachedInstallId2;
+    }
+    cachedInstallId2 = generateAndPersist2(filePath);
+    return cachedInstallId2;
+  } catch {
+    cachedInstallId2 = generateAndPersist2(filePath);
+    return cachedInstallId2;
+  }
+}
+
 var DEV_MANIFEST2 = {
   release: "dev",
   buildId: "dev",
@@ -3959,7 +4067,7 @@ var MANIFEST_PATH2 = (() => {
   }
 })();
 var cachedManifest2;
-function isValid2(value) {
+function isValid3(value) {
   if (typeof value !== "object" || value === null)
     return false;
   const m = value;
@@ -3972,7 +4080,7 @@ function readReleaseManifest2() {
   try {
     const raw = readFileSync(path17, "utf8");
     const parsed = JSON.parse(raw);
-    cachedManifest2 = isValid2(parsed) ? parsed : DEV_MANIFEST2;
+    cachedManifest2 = isValid3(parsed) ? parsed : DEV_MANIFEST2;
     return cachedManifest2;
   } catch (err) {
     const code = err.code;
@@ -4017,7 +4125,7 @@ function buildCommonProperties(serviceName, surface) {
     buildId: manifest.buildId,
     commitSha: manifest.commitSha,
     buildTime: manifest.buildTime,
-    installId: getInstallId(),
+    installId: getInstallId2(),
     nodeVersion: process.version,
     platform: process.platform
   };
@@ -4658,6 +4766,10 @@ var AuthLoginInputSchema = z.object({
   timeoutMs: z.number().int().positive().min(1e3).max(9e5).optional().describe("Maximum time to wait for login completion in milliseconds. Default: 120000"),
   forceNewSession: z.boolean().optional().describe("Force a fresh login by clearing any existing Auth0 browser session before redirecting to the device activation page. Use this to switch accounts. Default: false")
 });
+var AuthRegisterInputSchema = z.object({
+  email: z.string().email().describe("Email address to register the new Muggle AI account under"),
+  password: z.string().min(8).describe("Password for the new account, at least 8 characters. Sent once and not stored locally.")
+});
 var AuthPollInputSchema = z.object({
   deviceCode: z.string().optional().describe("Device code from the login response. Optional if a login was recently started.")
 });
@@ -4705,42 +4817,6 @@ function detectMcpHost(env = process.env) {
   }
   return "unknown";
 }
-var INSTALL_ID_FILENAME2 = "install-id.json";
-var cachedInstallId2;
-function installIdFilePath2() {
-  return join(getDataDir(), INSTALL_ID_FILENAME2);
-}
-function generateAndPersist2(filePath) {
-  const installId = randomUUID();
-  const contents = { installId };
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, JSON.stringify(contents, null, 2) + "\n", "utf8");
-  return installId;
-}
-function isValid3(value) {
-  return typeof value === "object" && value !== null && typeof value.installId === "string" && value.installId.length > 0;
-}
-function getInstallId2() {
-  if (cachedInstallId2 !== void 0) return cachedInstallId2;
-  const filePath = installIdFilePath2();
-  if (!existsSync(filePath)) {
-    cachedInstallId2 = generateAndPersist2(filePath);
-    return cachedInstallId2;
-  }
-  try {
-    const raw = readFileSync(filePath, "utf8");
-    const parsed = JSON.parse(raw);
-    if (isValid3(parsed)) {
-      cachedInstallId2 = parsed.installId;
-      return cachedInstallId2;
-    }
-    cachedInstallId2 = generateAndPersist2(filePath);
-    return cachedInstallId2;
-  } catch {
-    cachedInstallId2 = generateAndPersist2(filePath);
-    return cachedInstallId2;
-  }
-}
 
 // packages/mcps/src/mcp/e2e/upstream-client.ts
 var MUTATING_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
@@ -4791,7 +4867,7 @@ var PromptServiceClient = class {
    */
   buildHeaders(credentials, correlationId) {
     const manifest = readReleaseManifest();
-    const installId = getInstallId2();
+    const installId = getInstallId();
     const host = detectMcpHost();
     const headers = {
       "X-Correlation-Id": correlationId,
@@ -6511,6 +6587,19 @@ var userFeedbackTools = [
   }
 ];
 var authTools = [
+  {
+    name: "muggle-remote-auth-register",
+    description: "Create a new Muggle AI account from an email and password and start using E2E features on the free plan immediately \u2014 no browser, no human step. Verifying the address on that account upgrades it to the Starter package for free and permanently, raising the monthly token allowance tenfold; the account keeps working unverified, with less. Use this when there is no account yet; use muggle-remote-auth-login when one already exists. The API key it returns is stored automatically, so remote tools work straight afterwards.",
+    inputSchema: AuthRegisterInputSchema,
+    requiresAuth: false,
+    mapToUpstream: () => {
+      throw new Error("LOCAL_HANDLER_ONLY");
+    },
+    localHandler: async (input) => {
+      const authRegisterInput = input;
+      return registerAccount(authRegisterInput.email, authRegisterInput.password);
+    }
+  },
   {
     name: "muggle-remote-auth-status",
     description: "Check current authentication status. Shows if you're logged in and when your session expires.",
@@ -7796,6 +7885,7 @@ __export(e2e_exports2, {
   ApiKeyRevokeInputSchema: () => ApiKeyRevokeInputSchema,
   AuthLoginInputSchema: () => AuthLoginInputSchema,
   AuthPollInputSchema: () => AuthPollInputSchema,
+  AuthRegisterInputSchema: () => AuthRegisterInputSchema,
   BulkPreviewJobCancelInputSchema: () => BulkPreviewJobCancelInputSchema,
   BulkPreviewJobGetInputSchema: () => BulkPreviewJobGetInputSchema,
   BulkPreviewJobKindSchema: () => BulkPreviewJobKindSchema,
@@ -8121,6 +8211,17 @@ var ONBOARDING_CHOICE_GROUPS = [
       { value: "7d" /* SevenDays */, label: "Retire after 7 days" },
       { value: "never" /* Never */, label: "Never retire \u2014 no time-based reaper for an orphaned loop" }
     ]
+  },
+  {
+    header: "Rebase budget",
+    key: "maxCatchUpRebases" /* MaxCatchUpRebases */,
+    prompt: "How many times should a PR be rebased onto a moving base before you are asked to step in?",
+    optionLabels: [
+      { value: "10" /* TenRebases */, label: "Stop after 10" },
+      { value: "20" /* TwentyRebases */, label: "Stop after 20" },
+      { value: "50" /* FiftyRebases */, label: "Stop after 50" },
+      { value: "never" /* Never */, label: "Never stop \u2014 an active base can rebase a PR for as long as it stays open" }
+    ]
   }
 ];
 var ONBOARDING_BLANKET_OPTIONS = [

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-JNYP5PWT.js';
-import './chunk-ESPHO3WB.js';
+import { runCli } from './chunk-ODEPI25T.js';
+import './chunk-U6ZACW6K.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-JNYP5PWT.js';
-export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-ESPHO3WB.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-ODEPI25T.js';
+export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-U6ZACW6K.js';

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "5.19.0-staging.129",
+  "version": "5.19.0-staging.131",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "5.19.0-staging.129",
+  "version": "5.19.0-staging.131",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/config/preference-defaults.json

@@ -1,25 +1,26 @@
-{
-  "autoLogin": "always",
-  "autoSelectProject": "always",
-  "autoSelectLocalHost": "always",
-  "showElectronBrowser": "always",
-  "openTestResultsAfterRun": "always",
-  "defaultExecutionMode": "local",
-  "suggestRelatedUseCases": "always",
-  "suggestRelatedTestCases": "always",
-  "autoDetectChanges": "always",
-  "postPRVisualWalkthrough": "always",
-  "autoCreatePR": "always",
-  "checkForUpdates": "always",
-  "verboseOutput": "never",
-  "autoUseWorktree": "always",
-  "autoRebase": "always",
-  "autoCleanup": "always",
-  "autoE2ETest": "always",
-  "autoResolveConflicts": "always",
-  "autoReuseValidationContext": "always",
-  "autoRouteBuildToMuggleDo": "always",
-  "autoWatchPR": "always",
-  "reusePreparePlan": "always",
-  "watcherLifetime": "7d"
-}
+{
+  "autoLogin": "always",
+  "autoSelectProject": "always",
+  "autoSelectLocalHost": "always",
+  "showElectronBrowser": "always",
+  "openTestResultsAfterRun": "always",
+  "defaultExecutionMode": "local",
+  "suggestRelatedUseCases": "always",
+  "suggestRelatedTestCases": "always",
+  "autoDetectChanges": "always",
+  "postPRVisualWalkthrough": "always",
+  "autoCreatePR": "always",
+  "checkForUpdates": "always",
+  "verboseOutput": "never",
+  "autoUseWorktree": "always",
+  "autoRebase": "always",
+  "autoCleanup": "always",
+  "autoE2ETest": "always",
+  "autoResolveConflicts": "always",
+  "autoReuseValidationContext": "always",
+  "autoRouteBuildToMuggleDo": "always",
+  "autoWatchPR": "always",
+  "reusePreparePlan": "always",
+  "watcherLifetime": "7d",
+  "maxCatchUpRebases": "20"
+}

package/dist/plugin/skills/do/resolve-conflicts.md

@@ -1,59 +1,68 @@
-# Rebase (watcher-dispatched)
-
-Rebase a PR's branch onto its base — whether it's merely **behind** (out of date, no conflict) or actually **conflicting** — behind a verify-or-rollback gate, then force-push, so a PR doesn't sit stale or un-mergeable forever. A dumb-pipe dispatch like fix-ci: the watcher detects the branch is behind or conflicting and hands off; the executor owns the rebase (and any conflict resolution), never the decision to dispatch.
-
-## Turn preamble
-
-```
-**/muggle-do rebase** — rebasing <owner>/<repo>#<n> onto <base> to bring the branch up to date.
-```
-
-## Input
-
-`$ARGUMENTS` carries a `github.com/.../pull/<n>` URL, `slug=<slug>`, and a `rebase` directive (no review ids, no failing check names). Parse all three.
-
-## Inputs from disk
-
-From `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR + branch + `head_sha`), `last_seen.json` (`conflict_resolve_attempts`, `conflict_escalated_keys`, `pushed_shas`), `state.md` (worktree path, validation strategy, base branch).
-
-## Procedure
-
-### Step 1 — Re-attach
-
-Materialize the PR branch in its worktree per [`../_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) (or use `state.md`'s `worktreePath`). Capture `rebase_sha = prs.json[0].head_sha` and the base branch (`baseRefName` from [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md)). Capture the base tip too — `.base_commit.sha` from that recipe's `compare` call — and form `rebase_key = "<rebase_sha>..<base_tip_sha>"`. Both budget fields below are keyed on that pair, matching the watcher's Step 5; writing a bare SHA instead leaves an entry the watcher ignores, and the rebase re-dispatches forever.
-
-### Step 2 — Rebase onto base (resolve conflicts if any)
-
-Run the rebase from [`../_shared/sync-branch-with-base.md`](../_shared/sync-branch-with-base.md) against the base branch, taking its `always` path unconditionally — this programmatic mode never asks, so skip the `autoRebase` prompt (the watcher already decided a rebase is due).
-
-- **Clean replay** — a behind-only branch (and any rebase that hits no conflicts) replays without intervention. Proceed to Step 3.
-- **Conflicts** — handle per [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
-  - `never` → abort and escalate per Step 5 (`kind: "rebase-conflict"`). The watcher keeps polling; the user resolves on GitHub.
-  - `always` → resolve via [`../_shared/resolve-rebase-conflicts.md`](../_shared/resolve-rebase-conflicts.md); Steps 3 and 5 below are this mode's instance of the [`../_shared/verify-or-rollback-gate.md`](../_shared/verify-or-rollback-gate.md).
-
-### Step 3 — Verify the resolution
-
-Build (typecheck + lint on the changed surface) + unit suite must pass. Run E2E per [`e2e-acceptance.md`](e2e-acceptance.md) when app logic changed and the session carries validation context. A rebase that does not verify is rolled back → escalate per Step 5. **Never push an unverified rebase.**
-
-### Step 4 — Force-push + respawn
-
-Force-push per [`../_shared/vcs/common/push-to-branch.md`](../_shared/vcs/common/push-to-branch.md) (tool-agnostic instruction; handles the signing gate for rebased commits and directs to provider-specific force-push paths). Use `git push --force-with-lease` for the force operation. Append the new SHA to `last_seen.pushed_shas`; increment `last_seen.conflict_resolve_attempts[rebase_key]` — both whole-file rewrites (Read → change field → Write) per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md), never the Edit tool. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md). Its next tick re-checks the branch against its base on the new head — the rebase is its own verify loop, bounded by the per-SHA attempt budget.
-
-### Step 5 — Escalate (can't resolve / budget spent)
-
-When `autoResolveConflicts=never`, the resolution failed verification, or `conflict_resolve_attempts[rebase_key]` has reached 2:
-
-1. Add `rebase_key` to `last_seen.conflict_escalated_keys` so the watcher does not re-dispatch this head against this base. If the base later moves, the key changes and the branch re-arms on its own — a conflict the user resolved upstream stops being this watcher's dead end.
-2. Emit one terminal escalation naming the PR and the conflicting files (or the failing verification, for a behind-only rebase that didn't verify).
-3. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md) — it keeps polling for the user's manual resolution or any new reviews.
-
-### Step 6 — Telemetry
-
-Emit one `muggle-do:cycle` event ([`../_shared/telemetry-events/muggle-do-cycle.md`](../_shared/telemetry-events/muggle-do-cycle.md)) with `outcome: "rebased"` (a verified rebase pushed — behind-only or conflicts resolved) or `"rebase-escalated"`.
-
-## Guardrails
-
-- Max 2 rebase attempts per SHA; then escalate rather than churn.
-- Never push an unverified rebase — verify-or-rollback always.
-- Never push unsigned commits — every push or force-push goes through the signing gate in [`../_shared/vcs/common/push-to-branch.md`](../_shared/vcs/common/push-to-branch.md).
-- Resolve `autoResolveConflicts` from the configured preference (per the gate contract — don't assume a default): `always` resolves conflicts behind the verify-or-rollback gate, `never` escalates to the user. A clean behind-only rebase needs neither.
+# Rebase (watcher-dispatched)
+
+Rebase a PR's branch onto its base — whether it's merely **behind** (out of date, no conflict) or actually **conflicting** — behind a verify-or-rollback gate, then force-push, so a PR doesn't sit stale or un-mergeable forever. A dumb-pipe dispatch like fix-ci: the watcher detects the branch is behind or conflicting and hands off; the executor owns the rebase (and any conflict resolution), never the decision to dispatch.
+
+## Turn preamble
+
+```
+**/muggle-do rebase** — rebasing <owner>/<repo>#<n> onto <base> to bring the branch up to date.
+```
+
+## Input
+
+`$ARGUMENTS` carries a `github.com/.../pull/<n>` URL, `slug=<slug>`, and a `rebase` directive (no review ids, no failing check names). Parse all three.
+
+## Inputs from disk
+
+From `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR + branch + `head_sha`), `last_seen.json` (`conflict_resolve_attempts`, `conflict_escalated_keys`, `catch_up_rebases`, `pushed_shas`), `state.md` (worktree path, validation strategy, base branch).
+
+## Procedure
+
+### Step 1 — Re-attach
+
+Materialize the PR branch in its worktree per [`../_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) (or use `state.md`'s `worktreePath`). Capture `rebase_sha = prs.json[0].head_sha` and the base branch (`baseRefName` from [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md)). Capture the base tip too — `.base_commit.sha` from that recipe's `compare` call — and form `rebase_key = "<rebase_sha>..<base_tip_sha>"`. Both budget fields below are keyed on that pair, matching the watcher's Step 5; writing a bare SHA instead leaves an entry the watcher ignores, and the rebase re-dispatches forever.
+
+### Step 2 — Rebase onto base (resolve conflicts if any)
+
+Run the rebase from [`../_shared/sync-branch-with-base.md`](../_shared/sync-branch-with-base.md) against the base branch, taking its `always` path unconditionally — this programmatic mode never asks, so skip the `autoRebase` prompt (the watcher already decided a rebase is due).
+
+- **Clean replay** — a behind-only branch (and any rebase that hits no conflicts) replays without intervention. Proceed to Step 3.
+- **Conflicts** — handle per [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
+  - `never` → abort and escalate per Step 5 (`kind: "rebase-conflict"`). The watcher keeps polling; the user resolves on GitHub.
+  - `always` → resolve via [`../_shared/resolve-rebase-conflicts.md`](../_shared/resolve-rebase-conflicts.md); Steps 3 and 5 below are this mode's instance of the [`../_shared/verify-or-rollback-gate.md`](../_shared/verify-or-rollback-gate.md).
+
+### Step 3 — Verify the resolution
+
+Build (typecheck + lint on the changed surface) + unit suite must pass. Run E2E per [`e2e-acceptance.md`](e2e-acceptance.md) when app logic changed and the session carries validation context. A rebase that does not verify is rolled back → escalate per Step 5. **Never push an unverified rebase.**
+
+### Step 4 — Force-push + respawn
+
+Force-push per [`../_shared/vcs/common/push-to-branch.md`](../_shared/vcs/common/push-to-branch.md) (tool-agnostic instruction; handles the signing gate for rebased commits and directs to provider-specific force-push paths). Use `git push --force-with-lease` for the force operation. Append the new SHA to `last_seen.pushed_shas`; increment `last_seen.conflict_resolve_attempts[rebase_key]` **and** `last_seen.catch_up_rebases` — all whole-file rewrites (Read → change field → Write) per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md), never the Edit tool. The second counter is unkeyed on purpose: `rebase_key` carries the base tip, so it mints a fresh budget every time the base moves and cannot bound a PR on an active base. Increment it on every push here, including one that later escalates, or a branch that fails the same way twenty times reads as having spent nothing. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md). Its next tick re-checks the branch against its base on the new head — the rebase is its own verify loop, bounded by the per-SHA attempt budget.
+
+### Step 5 — Escalate (can't resolve / budget spent)
+
+When `autoResolveConflicts=never`, the resolution failed verification, or `conflict_resolve_attempts[rebase_key]` has reached 2:
+
+1. Add `rebase_key` to `last_seen.conflict_escalated_keys` so the watcher does not re-dispatch this head against this base. If the base later moves, the key changes and the branch re-arms on its own — a conflict the user resolved upstream stops being this watcher's dead end.
+2. Emit one terminal escalation naming the PR and the conflicting files (or the failing verification, for a behind-only rebase that didn't verify).
+3. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md) — it keeps polling for the user's manual resolution or any new reviews.
+
+### Step 5a — Escalate (per-PR catch-up budget spent)
+
+When `catch_up_rebases` has reached [`maxCatchUpRebases`](../muggle-preferences/preference-gates/maxCatchUpRebases.md) (20 unless the user changed it), the PR is out of catch-up budget for good — a different escalation from Step 5, which retires one `rebase_key` and re-arms the moment the base moves.
+
+1. Set `last_seen.rebase_budget_exhausted` to `true`. The watcher stops dispatching rebases for this PR outright, so no base advance re-arms it.
+2. Emit one terminal escalation, and post it on the PR, naming the count, the cap, and `maxCatchUpRebases` as the way to raise it. Say what the owner has to decide — rebase onto a different base, split the branch, or close it — because the harness has stopped trying and silence here reads as a healthy watcher.
+3. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md); it keeps polling reviews and CI, and blocks with reason `rebase_budget_exhausted`.
+
+### Step 6 — Telemetry
+
+Emit one `muggle-do:cycle` event ([`../_shared/telemetry-events/muggle-do-cycle.md`](../_shared/telemetry-events/muggle-do-cycle.md)) with `outcome: "rebased"` (a verified rebase pushed — behind-only or conflicts resolved), `"rebase-escalated"`, or `"rebase-budget-exhausted"` (Step 5a).
+
+## Guardrails
+
+- Max 2 rebase attempts per `rebase_key`, and `maxCatchUpRebases` (20 by default) across the PR's whole life; then escalate rather than churn. The per-key cap alone bounds nothing on an active base, since a base advance mints a new key.
+- Never let an exhausted budget pass as silence — Step 5a reports on the PR. A watcher that stops without saying so is indistinguishable from one that has nothing to do.
+- Never push an unverified rebase — verify-or-rollback always.
+- Never push unsigned commits — every push or force-push goes through the signing gate in [`../_shared/vcs/common/push-to-branch.md`](../_shared/vcs/common/push-to-branch.md).
+- Resolve `autoResolveConflicts` from the configured preference (per the gate contract — don't assume a default): `always` resolves conflicts behind the verify-or-rollback gate, `never` escalates to the user. A clean behind-only rebase needs neither.