@muggleai/works 5.31.0-staging.274 → 5.31.0-staging.276

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "muggleai",
       "source": "./plugin",
       "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-      "version": "5.31.0-staging.274"
+      "version": "5.31.0-staging.276"
     }
   ]
 }

package/dist/{chunk-7JQWRPFI.js → chunk-HK7XCCNT.js}

@@ -5,7 +5,7 @@ import { v4 } from 'uuid';
 import { z, ZodError } from 'zod';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as fs from 'fs';
-import { readFileSync, existsSync, rmSync, mkdirSync, readdirSync, createWriteStream, writeFileSync, statSync, readlinkSync, realpathSync, openSync, closeSync, writeSync, unlinkSync, copyFileSync, renameSync, appendFileSync, readSync } from 'fs';
+import { readFileSync, existsSync, rmSync, mkdirSync, readdirSync, createWriteStream, writeFileSync, statSync, readlinkSync, realpathSync, openSync, closeSync, writeSync, unlinkSync, copyFileSync, renameSync, appendFileSync, readSync, fstatSync } from 'fs';
 import * as path from 'path';
 import { join, dirname, resolve, win32, basename } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -2945,6 +2945,12 @@ var REMOTE_CONTROL_MAX_RESTARTS = 2;
 var REMOTE_CONTROL_RESTART_WINDOW_MS = 24 * 60 * 6e4;
 var REMOTE_CONTROL_RESTART_COOLDOWN_MS = 30 * 6e4;
 var REMOTE_CONTROL_NAME_COLUMN_WIDTH = 32;
+var USAGE_LIMIT_API_ERROR = "usage_limit_reached";
+var TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+var LIMIT_RESUME_PROMPT = "The usage limit that stopped your last turn has reset. Continue where you left off.";
+var LIMIT_RESUME_MAX_ATTEMPTS = 2;
+var LIMIT_RESUME_WINDOW_MS = 24 * 60 * 6e4;
+var LIMIT_STOP_MAX_AGE_MS = 8 * 24 * 60 * 6e4;
 var USAGE_WINDOW_EXHAUSTED_PERCENT = 100;
 var RELOAD_PLUGIN_SCOPE = "user";
 var MUGGLE_PLUGIN_ID = "muggleai@muggle-works";
@@ -4927,6 +4933,22 @@ function renderWatchStatus(snapshot, nowMs) {
       lines.push(`  ${decision.action.padEnd(14)} ${shortSessionId(decision.sessionId)} ${label} ${decision.reason}${outcome}`);
     }
   }
+  const limitDecisions = snapshot.limitResumes?.decisions ?? [];
+  if (limitDecisions.length > 0) {
+    const countOutcome = (outcome) => limitDecisions.filter((decision) => decision.outcome === outcome).length;
+    const countAction = (action) => limitDecisions.filter((decision) => decision.action === action).length;
+    const continueCount = countAction("continue" /* Continue */);
+    const continuedCount = countOutcome("resumed" /* Resumed */);
+    lines.push(
+      "",
+      `Stopped at a usage limit: ${continuedCount} continued, ${continueCount - continuedCount} failed, ${countAction("wait" /* Wait */)} waiting, ${countAction("skip" /* Skip */)} skipped`
+    );
+    for (const decision of limitDecisions) {
+      const outcome = decision.outcome === void 0 || decision.outcome === "resumed" /* Resumed */ ? "" : ` \u2014 ${decision.outcome}`;
+      const label = (decision.name ?? "").slice(0, REMOTE_CONTROL_NAME_COLUMN_WIDTH).padEnd(REMOTE_CONTROL_NAME_COLUMN_WIDTH);
+      lines.push(`  ${decision.action.padEnd(14)} ${shortSessionId(decision.sessionId)} ${label} ${decision.reason}${outcome}`);
+    }
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -4949,6 +4971,22 @@ function readFileHead(filePath) {
     if (fileDescriptor !== void 0) closeSync(fileDescriptor);
   }
 }
+function readFileTailLines(filePath, byteCount) {
+  let fileDescriptor;
+  try {
+    fileDescriptor = openSync(filePath, "r");
+    const fileSize = fstatSync(fileDescriptor).size;
+    const start = Math.max(0, fileSize - byteCount);
+    const buffer = Buffer.alloc(fileSize - start);
+    const bytesRead = readSync(fileDescriptor, buffer, 0, buffer.length, start);
+    const lines = buffer.subarray(0, bytesRead).toString("utf-8").split(/\r?\n/);
+    return (start > 0 ? lines.slice(1) : lines).filter((line) => line.length > 0);
+  } catch {
+    return void 0;
+  } finally {
+    if (fileDescriptor !== void 0) closeSync(fileDescriptor);
+  }
+}
 function cwdFromSessionHead(head) {
   const parts = head.match(/"cwd"\s*:\s*("(?:[^"\\]|\\.)*")/);
   if (!parts) return void 0;
@@ -5129,6 +5167,56 @@ function readCodexSessions(sessionsDir, nowMs) {
   }
   return sessions;
 }
+function findTranscriptPath(projectsDir, sessionId) {
+  let projectDirNames;
+  try {
+    projectDirNames = readdirSync(projectsDir);
+  } catch {
+    return void 0;
+  }
+  const transcriptFileName = `${sessionId}.jsonl`;
+  for (const projectDirName of projectDirNames) {
+    const transcriptPath = join(projectsDir, projectDirName, transcriptFileName);
+    if (existsSync(transcriptPath)) return transcriptPath;
+  }
+  return void 0;
+}
+function parseTranscriptLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isConversationTurn(entry) {
+  return (entry.type === "user" || entry.type === "assistant") && entry.isSidechain !== true && entry.isMeta !== true;
+}
+function readLimitStop(projectsDir, sessionId) {
+  const transcriptPath = findTranscriptPath(projectsDir, sessionId);
+  if (transcriptPath === void 0) return void 0;
+  const lines = readFileTailLines(transcriptPath, TRANSCRIPT_TAIL_BYTES) ?? [];
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const entry = parseTranscriptLine(lines[index]);
+    if (entry === void 0 || !isConversationTurn(entry)) continue;
+    if (entry.type !== "assistant" || entry.apiError !== USAGE_LIMIT_API_ERROR) return void 0;
+    const noticedAtMs = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : Number.NaN;
+    if (typeof entry.uuid !== "string" || Number.isNaN(noticedAtMs)) return void 0;
+    const resetsAtSeconds = entry.apiErrorParams?.rate_limit_info?.resetsAt;
+    return {
+      noticeUuid: entry.uuid,
+      noticedAtMs,
+      ...typeof resetsAtSeconds === "number" ? { resetsAtMs: resetsAtSeconds * 1e3 } : {}
+    };
+  }
+  return void 0;
+}
+function findClaudeSessionCwd(projectsDir, sessionId) {
+  const transcriptPath = findTranscriptPath(projectsDir, sessionId);
+  if (transcriptPath === void 0) return void 0;
+  const head = readFileHead(transcriptPath);
+  return head === void 0 ? void 0 : cwdFromSessionHead(head);
+}
 
 // src/pr-watch/constants.ts
 var REBASE_KEY_SEPARATOR = "..";
@@ -5282,26 +5370,6 @@ function fetchPrLiveStatuses(prs, runCommand) {
   }
   return statusesByUrl;
 }
-function findTranscriptPath(projectsDir, sessionId) {
-  let projectDirNames;
-  try {
-    projectDirNames = readdirSync(projectsDir);
-  } catch {
-    return void 0;
-  }
-  const transcriptFileName = `${sessionId}.jsonl`;
-  for (const projectDirName of projectDirNames) {
-    const transcriptPath = join(projectsDir, projectDirName, transcriptFileName);
-    if (existsSync(transcriptPath)) return transcriptPath;
-  }
-  return void 0;
-}
-function findClaudeSessionCwd(projectsDir, sessionId) {
-  const transcriptPath = findTranscriptPath(projectsDir, sessionId);
-  if (transcriptPath === void 0) return void 0;
-  const head = readFileHead(transcriptPath);
-  return head === void 0 ? void 0 : cwdFromSessionHead(head);
-}
 function parseServiceLoopReport(outputText, writtenAtMs) {
   const reportLines = [];
   let kind = "silent" /* Silent */;
@@ -5735,6 +5803,106 @@ function readInstallHistory(installLogFile) {
   }
   return installs;
 }
+function recentAttempts(attempts, nowMs) {
+  return attempts.filter((attempt) => nowMs - Date.parse(attempt.at) < LIMIT_RESUME_WINDOW_MS);
+}
+function decide(session, stop, action, reason) {
+  return {
+    sessionId: session.sessionId,
+    ...session.shortId === void 0 ? {} : { shortId: session.shortId },
+    ...session.name === void 0 ? {} : { name: session.name },
+    action,
+    reason,
+    noticeUuid: stop.noticeUuid
+  };
+}
+function planLimitResumes(sessions, limitStopsBySessionId, attemptsBySession, nowMs, isUsageLimitInForce, maxContinues) {
+  const decisions = [];
+  let continueCount = 0;
+  for (const session of sessions) {
+    const stop = limitStopsBySessionId.get(session.sessionId);
+    if (session.agent !== "claude" /* Claude */ || stop === void 0) continue;
+    const attempts = attemptsBySession[session.sessionId] ?? [];
+    if (nowMs - stop.noticedAtMs > LIMIT_STOP_MAX_AGE_MS) continue;
+    if (attempts.some((attempt) => attempt.noticeUuid === stop.noticeUuid && attempt.isContinued)) continue;
+    const isRunning = hasLiveProcess(session);
+    if (session.kind !== "background" /* Background */) {
+      decisions.push(decide(session, stop, "skip" /* Skip */, "terminal session, continue it there"));
+    } else if (session.shortId === void 0) {
+      decisions.push(decide(session, stop, "skip" /* Skip */, "no short id to continue it by"));
+    } else if (isRunning && session.turnStatus !== "idle" /* Idle */) {
+      decisions.push(decide(session, stop, "skip" /* Skip */, `turn in flight (${session.turnStatus ?? "unknown"})`));
+    } else if (stop.resetsAtMs !== void 0 && stop.resetsAtMs > nowMs) {
+      decisions.push(decide(session, stop, "wait" /* Wait */, `limit resets at ${new Date(stop.resetsAtMs).toISOString()}`));
+    } else if (isUsageLimitInForce) {
+      decisions.push(decide(session, stop, "wait" /* Wait */, "the account is still at a usage limit"));
+    } else if (recentAttempts(attempts, nowMs).length >= LIMIT_RESUME_MAX_ATTEMPTS) {
+      decisions.push(decide(session, stop, "skip" /* Skip */, `after ${LIMIT_RESUME_MAX_ATTEMPTS} tries today`));
+    } else if (continueCount >= maxContinues) {
+      decisions.push(decide(session, stop, "wait" /* Wait */, "tick cap reached"));
+    } else {
+      continueCount++;
+      const reason = stop.resetsAtMs === void 0 ? "usage limit cleared" : `limit reset at ${new Date(stop.resetsAtMs).toISOString()}`;
+      decisions.push({ ...decide(session, stop, "continue" /* Continue */, reason), ...isRunning ? { runningShortId: session.shortId } : {} });
+    }
+  }
+  return decisions;
+}
+function continuedOutcomeOf(outcome) {
+  if (outcome === "continued" /* Continued */) return "resumed" /* Resumed */;
+  return outcome === "copied" /* Copied */ ? "resume-forked" /* ResumeForked */ : "resume-failed" /* ResumeFailed */;
+}
+function eventKindOf(outcome) {
+  if (outcome === "resumed" /* Resumed */) return "resumed" /* Resumed */;
+  if (outcome === "resume-forked" /* ResumeForked */) return "resume-forked" /* ResumeForked */;
+  return outcome === "restart-refused" /* RestartRefused */ ? "restart-refused" /* RestartRefused */ : "resume-failed" /* ResumeFailed */;
+}
+function continueMessageOf(resumed, reason) {
+  if (resumed.outcome === "continued" /* Continued */) return `continued it after its usage limit reset (${reason})`;
+  if (resumed.outcome === "copied" /* Copied */) {
+    const copyNote = resumed.isCopyRemoved ? "stopped and removed the copy" : `run claude rm ${resumed.copyShortId}`;
+    return `could not continue it: Claude started copy ${resumed.copyShortId} instead; ${copyNote}`;
+  }
+  const cause = resumed.outcome === "still-running" /* StillRunning */ ? "it is still running" : "the resume did not start";
+  return `could not continue it after its usage limit: ${cause}`;
+}
+function executeLimitResumes(planned, attemptsBySession, deps) {
+  const at = new Date(deps.nowMs).toISOString();
+  const nextAttemptsBySession = {};
+  for (const [sessionId, attempts] of Object.entries(attemptsBySession)) {
+    const kept = attempts.filter((attempt) => deps.nowMs - Date.parse(attempt.at) < LIMIT_STOP_MAX_AGE_MS);
+    if (kept.length > 0) nextAttemptsBySession[sessionId] = kept;
+  }
+  const events = [];
+  const decisions = planned.map((decision) => {
+    if (decision.action !== "continue" /* Continue */) return decision;
+    const subject = `session ${decision.shortId ?? shortSessionId(decision.sessionId)}`;
+    const cwd = findClaudeSessionCwd(deps.claudeProjectsDir, decision.sessionId);
+    if (!cwd || !existsSync(cwd)) return { ...decision, outcome: "transcript-missing" /* TranscriptMissing */ };
+    let outcome;
+    let message;
+    if (decision.runningShortId !== void 0 && !deps.canRestartIn(cwd)) {
+      outcome = "restart-refused" /* RestartRefused */;
+      message = `left stopped at its usage limit: Claude would not resume it in ${cwd}`;
+    } else {
+      const resumed = resumeSession(
+        { sessionId: decision.sessionId, cwd, prompt: LIMIT_RESUME_PROMPT, runningShortId: decision.runningShortId },
+        deps.runCommand,
+        deps.waitForExit,
+        deps.isSessionRunning
+      );
+      outcome = continuedOutcomeOf(resumed.outcome);
+      message = continueMessageOf(resumed, decision.reason);
+    }
+    nextAttemptsBySession[decision.sessionId] = [
+      ...nextAttemptsBySession[decision.sessionId] ?? [],
+      { noticeUuid: decision.noticeUuid, at, isContinued: outcome === "resumed" /* Resumed */ }
+    ];
+    events.push({ at, kind: eventKindOf(outcome), subject, message });
+    return { ...decision, outcome };
+  });
+  return { decisions, attemptsBySession: nextAttemptsBySession, events };
+}
 function emptyLedgerState() {
   return { activeFindings: {}, recoveryAttemptsByOwner: {}, terminalPrsByUrl: {} };
 }
@@ -5949,7 +6117,7 @@ function readProcessTable(platform4, runCommand, nowMs) {
 }
 
 // src/watch/reload-plugins.ts
-function decide(session, action, reason) {
+function decide2(session, action, reason) {
   return {
     sessionId: session.sessionId,
     shortId: session.shortId,
@@ -5969,24 +6137,24 @@ function planReloadFanOut(sessions, pending, watchOwnerSessionIds, maxRestarts =
   for (const session of sessions) {
     if (session.agent !== "claude" /* Claude */) continue;
     if (!hasLiveProcess(session)) {
-      decisions.push(decide(session, "skip" /* Skip */, "no live process"));
+      decisions.push(decide2(session, "skip" /* Skip */, "no live process"));
     } else if (hasCurrentPlugins(session, pending)) {
-      decisions.push(decide(session, "skip" /* Skip */, "already on the installed build"));
+      decisions.push(decide2(session, "skip" /* Skip */, "already on the installed build"));
     } else if (pending.respawnedSessionIds.includes(session.sessionId) || pending.skippedSessionIds.includes(session.sessionId)) {
-      decisions.push(decide(session, "skip" /* Skip */, "already handled for this install"));
+      decisions.push(decide2(session, "skip" /* Skip */, "already handled for this install"));
     } else if (session.kind === "interactive" /* Interactive */) {
-      decisions.push(pending.notifiedSessionIds.includes(session.sessionId) ? decide(session, "skip" /* Skip */, "already asked to run /reload-plugins") : decide(session, "notify-manual" /* NotifyManual */, "terminal session \u2014 run /reload-plugins in it"));
+      decisions.push(pending.notifiedSessionIds.includes(session.sessionId) ? decide2(session, "skip" /* Skip */, "already asked to run /reload-plugins") : decide2(session, "notify-manual" /* NotifyManual */, "terminal session \u2014 run /reload-plugins in it"));
     } else if (session.kind !== "background" /* Background */ || !session.shortId) {
-      decisions.push(decide(session, "skip" /* Skip */, "not a background session the watch can restart"));
+      decisions.push(decide2(session, "skip" /* Skip */, "not a background session the watch can restart"));
     } else if (session.turnStatus !== "idle" /* Idle */) {
-      decisions.push(decide(session, "defer" /* Defer */, `turn in flight (${session.turnStatus ?? "unknown"})`));
+      decisions.push(decide2(session, "defer" /* Defer */, `turn in flight (${session.turnStatus ?? "unknown"})`));
     } else if (watchOwnerSessionIds.has(session.sessionId)) {
-      decisions.push(decide(session, "skip" /* Skip */, "owns open PR watches \u2014 left running; run /reload-plugins in it"));
+      decisions.push(decide2(session, "skip" /* Skip */, "owns open PR watches \u2014 left running; run /reload-plugins in it"));
     } else if (restartsPlanned >= maxRestarts) {
-      decisions.push(decide(session, "defer" /* Defer */, "restart cap reached this pass"));
+      decisions.push(decide2(session, "defer" /* Defer */, "restart cap reached this pass"));
     } else {
       restartsPlanned++;
-      decisions.push(decide(session, "respawn" /* Respawn */, "idle background session"));
+      decisions.push(decide2(session, "respawn" /* Respawn */, "idle background session"));
     }
   }
   return decisions;
@@ -6041,7 +6209,7 @@ function isTurnOver(session) {
 function recentRestartsMs(restartsBySession, sessionId, nowMs) {
   return (restartsBySession[sessionId] ?? []).map((restartedAt) => Date.parse(restartedAt)).filter((restartedAtMs) => !Number.isNaN(restartedAtMs) && nowMs - restartedAtMs < REMOTE_CONTROL_RESTART_WINDOW_MS);
 }
-function decide2(session, action, reason) {
+function decide3(session, action, reason) {
   return { sessionId: session.sessionId, shortId: session.shortId, name: session.name, cwd: session.cwd, action, reason };
 }
 function planRemoteControlRestarts(sessions, login, restartsBySession, nowMs, maxRestarts) {
@@ -6057,20 +6225,20 @@ function planRemoteControlRestarts(sessions, login, restartsBySession, nowMs, ma
     }
     const restartsMs = recentRestartsMs(restartsBySession, session.sessionId, nowMs);
     if (session.kind === "interactive" /* Interactive */) {
-      decisions.push(decide2(session, "notify-manual" /* NotifyManual */, `${gap} \u2014 terminal session, run /remote-control in it`));
+      decisions.push(decide3(session, "notify-manual" /* NotifyManual */, `${gap} \u2014 terminal session, run /remote-control in it`));
     } else if (session.kind !== "background" /* Background */ || !session.shortId) {
-      decisions.push(decide2(session, "skip" /* Skip */, `${gap} \u2014 not a background session the watch can restart`));
+      decisions.push(decide3(session, "skip" /* Skip */, `${gap} \u2014 not a background session the watch can restart`));
     } else if (restartsMs.length >= REMOTE_CONTROL_MAX_RESTARTS) {
-      decisions.push(decide2(session, "skip" /* Skip */, `${gap} after ${restartsMs.length} restarts today`));
+      decisions.push(decide3(session, "skip" /* Skip */, `${gap} after ${restartsMs.length} restarts today`));
     } else if (nowMs - Math.max(-Infinity, ...restartsMs) < REMOTE_CONTROL_RESTART_COOLDOWN_MS) {
-      decisions.push(decide2(session, "skip" /* Skip */, `${gap} \u2014 restarted recently, waiting for it to link`));
+      decisions.push(decide3(session, "skip" /* Skip */, `${gap} \u2014 restarted recently, waiting for it to link`));
     } else if (!isTurnOver(session)) {
-      decisions.push(decide2(session, "defer" /* Defer */, `${gap} \u2014 turn in flight (${session.processStatus ?? session.turnStatus ?? "unknown"})`));
+      decisions.push(decide3(session, "defer" /* Defer */, `${gap} \u2014 turn in flight (${session.processStatus ?? session.turnStatus ?? "unknown"})`));
     } else if (restartsPlanned >= maxRestarts) {
-      decisions.push(decide2(session, "defer" /* Defer */, `${gap} \u2014 restart cap reached this pass`));
+      decisions.push(decide3(session, "defer" /* Defer */, `${gap} \u2014 restart cap reached this pass`));
     } else {
       restartsPlanned++;
-      decisions.push(decide2(session, "respawn" /* Respawn */, gap));
+      decisions.push(decide3(session, "respawn" /* Respawn */, gap));
     }
   }
   return { connectedSessionIds, decisions };
@@ -6455,6 +6623,7 @@ function createDefaultWatchTickDeps(options) {
     isAutoReloadEnabled: options.isAutoReloadEnabled,
     isRecoveryEnabled: options.isRecoveryEnabled,
     isRemoteControlKeptOn: options.isRemoteControlKeptOn,
+    isLimitResumeEnabled: options.isLimitResumeEnabled,
     launchServiceLoop: createServiceLoopLauncher(process.platform, defaultCommandRunner)
   };
 }
@@ -6529,6 +6698,33 @@ function waitForExitVia(deps) {
 function isSessionRunningVia(deps) {
   return (sessionId) => isSessionRunning(deps.runCommand, deps.paths.claudeSessionRegistryDir, sessionId) !== false;
 }
+function resumeDepsOf(deps) {
+  return {
+    runCommand: deps.runCommand,
+    claudeProjectsDir: deps.paths.claudeProjectsDir,
+    nowMs: deps.nowMs,
+    canRestartIn: canRestartVia(deps),
+    waitForExit: waitForExitVia(deps),
+    isSessionRunning: isSessionRunningVia(deps)
+  };
+}
+function runLimitResumePass(claudeSessions, attemptsBySession, maxContinues, deps) {
+  const limitStopsBySessionId = /* @__PURE__ */ new Map();
+  for (const session of claudeSessions) {
+    const stop = readLimitStop(deps.paths.claudeProjectsDir, session.sessionId);
+    if (stop !== void 0) limitStopsBySessionId.set(session.sessionId, stop);
+  }
+  const planned = planLimitResumes(
+    claudeSessions,
+    limitStopsBySessionId,
+    attemptsBySession,
+    deps.nowMs,
+    isClaudeUsageLimitInForce(deps.paths.claudeGlobalConfigFile, deps.nowMs),
+    maxContinues
+  );
+  const executed = executeLimitResumes(planned, attemptsBySession, resumeDepsOf(deps));
+  return { report: { decisions: executed.decisions }, attemptsBySession: executed.attemptsBySession, events: executed.events };
+}
 function reloadTargetAtMs(deps, installs) {
   return resolveReloadTargetAtMs(installs, readMugglePluginUpdatedAtMs(deps.paths.claudeInstalledPluginsFile));
 }
@@ -6591,14 +6787,7 @@ function runTickUnlocked(deps) {
       sessionsById,
       isClaudeUsageLimitInForce(deps.paths.claudeGlobalConfigFile, deps.nowMs)
     );
-    const executed = executeWatcherRecoveries(planned, recoveryAttemptsByOwner, {
-      runCommand: deps.runCommand,
-      claudeProjectsDir: deps.paths.claudeProjectsDir,
-      nowMs: deps.nowMs,
-      canRestartIn: canRestartVia(deps),
-      waitForExit: waitForExitVia(deps),
-      isSessionRunning: isSessionRunningVia(deps)
-    });
+    const executed = executeWatcherRecoveries(planned, recoveryAttemptsByOwner, resumeDepsOf(deps));
     recoveries = executed.recoveries;
     recoveryAttemptsByOwner = executed.attemptsByOwner;
     events.push(...executed.events);
@@ -6613,6 +6802,22 @@ function runTickUnlocked(deps) {
     events.push(...started.events);
   }
   const restartedSessionIds = new Set(recoveries.filter(isRestartAttempted).map((recovery) => recovery.ownerSessionId));
+  let limitResumeAttemptsBySession = state.limitResumeAttemptsBySession ?? {};
+  let limitResumes;
+  if (deps.isLimitResumeEnabled && claudeSessions !== null) {
+    const pass = runLimitResumePass(
+      claudeSessions.filter((session) => !restartedSessionIds.has(session.sessionId)),
+      limitResumeAttemptsBySession,
+      Math.max(0, MAX_RESUMES_PER_TICK - restartedSessionIds.size),
+      deps
+    );
+    limitResumes = pass.report;
+    limitResumeAttemptsBySession = pass.attemptsBySession;
+    events.push(...pass.events);
+    for (const decision of pass.report.decisions) {
+      if (decision.outcome !== void 0) restartedSessionIds.add(decision.sessionId);
+    }
+  }
   let pendingReload = state.pendingReload;
   let reload;
   const targetAtMs = reloadTargetAtMs(deps, installs);
@@ -6649,7 +6854,8 @@ function runTickUnlocked(deps) {
     terminalPrsByUrl,
     pendingReload,
     claudeLogin,
-    remoteControlRestartsBySession
+    remoteControlRestartsBySession,
+    limitResumeAttemptsBySession
   });
   const snapshot = {
     takenAt: at,
@@ -6663,7 +6869,8 @@ function runTickUnlocked(deps) {
     recoveries,
     serviceArms,
     reload,
-    remoteControl
+    remoteControl,
+    limitResumes
   };
   writeWatchSnapshot(deps.paths.watchDir, snapshot);
   return snapshot;
@@ -6720,7 +6927,8 @@ function watchTickCommand(flags) {
       createDefaultWatchTickDeps({
         isAutoReloadEnabled: flags.autoReload,
         isRecoveryEnabled: flags.recovery,
-        isRemoteControlKeptOn: flags.remoteControl
+        isRemoteControlKeptOn: flags.remoteControl,
+        isLimitResumeEnabled: flags.limitResume
       })
     );
     if (flags.json) {
@@ -6762,7 +6970,7 @@ function watchReloadPluginsCommand(flags) {
   try {
     const isDryRun = flags.dryRun === true;
     const report = runReloadPluginsPass(
-      createDefaultWatchTickDeps({ isAutoReloadEnabled: true, isRecoveryEnabled: false, isRemoteControlKeptOn: false }),
+      createDefaultWatchTickDeps({ isAutoReloadEnabled: true, isRecoveryEnabled: false, isRemoteControlKeptOn: false, isLimitResumeEnabled: false }),
       isDryRun
     );
     if (!report) {
@@ -6849,7 +7057,7 @@ function createProgram() {
   stack.command("status").description("Show every lease, the line, and the services prepare tracks").option("--json", "Print the full report as JSON").action(stackStatusCommand);
   program.command("ci-install").description("Add the Muggle walkthrough check to this repository's GitHub Actions").option("--force", "Replace an existing workflow file").action(ciInstallCommand);
   const watch = program.command("watch").description("Standing watch over Claude/Codex sessions, their processes, and PR watchers");
-  watch.command("tick").description("Run one watch pass (the scheduled task runs this)").option("--no-auto-reload", "Do not start a plugin reload fan-out when installed plugins change").option("--no-recovery", "Report dead watchers without resuming their owner sessions").option("--no-remote-control", "Report sessions off Remote Control without restarting them").option("--json", "Print the full snapshot as JSON").action(watchTickCommand);
+  watch.command("tick").description("Run one watch pass (the scheduled task runs this)").option("--no-auto-reload", "Do not start a plugin reload fan-out when installed plugins change").option("--no-recovery", "Report dead watchers without resuming their owner sessions").option("--no-remote-control", "Report sessions off Remote Control without restarting them").option("--no-limit-resume", "Report sessions a usage limit cut off without continuing them").option("--json", "Print the full snapshot as JSON").action(watchTickCommand);
   watch.command("status").description("Show the last watch pass: sessions, processes, PR watches, findings").option("--json", "Print the snapshot as JSON").action(watchStatusCommand);
   watch.command("reload-plugins").description("Reload plugins across active Claude sessions (respawns idle background ones)").option("--dry-run", "Show what each session would get without respawning anything").option("--json", "Print the report as JSON").action(watchReloadPluginsCommand);
   watch.command("install").description("Schedule the watch with this OS's scheduler, or refresh the entry in place").option("--uninstall", "Remove the task; the ledger is kept").option("--no-wait", "Return once the task is registered, without waiting for its first pass").option("--from-preference", "Act on the autoInstallWatchService preference, as an install or upgrade does").action(watchInstallCommand);

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-7JQWRPFI.js';
+import { runCli } from './chunk-HK7XCCNT.js';
 import './chunk-7J7DS4SA.js';
 
 // src/cli/main.ts

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-7JQWRPFI.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-HK7XCCNT.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-7J7DS4SA.js';

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

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.codex-mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.31.0-staging.274",
+        "@muggleai/works@5.31.0-staging.276",
         "serve"
       ],
       "env": {

package/dist/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "muggle",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
   "author": {
     "name": "Muggle AI",

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

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.31.0-staging.274",
+        "@muggleai/works@5.31.0-staging.276",
         "serve"
       ]
     }

package/dist/plugin/skills/do/input-routing.md

@@ -6,7 +6,7 @@ How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–4 are programmatic
 2. **Fix-CI** — a PR/MR URL **and** a `fix ci` / `fix-ci` directive with failing check names (no review/discussion ids) → [`fix-ci.md`](fix-ci.md).
 3. **Rebase** — a PR/MR URL **and** a `rebase` directive (or legacy `resolve conflicts` / `resolve-conflicts`; no review/discussion ids, no check names) → [`resolve-conflicts.md`](resolve-conflicts.md). Rebases the branch onto its base whether it's merely behind or actually conflicting.
 4. **Post-merge cleanup** — a `cleanup` token and `slug=<slug>` (no PR URL, no review ids), optionally `state=<merged|closed>` (default `merged`) → [`cleanup.md`](cleanup.md).
-5. **Empty / `help` / `menu` / `?`** → menu + session selector.
+5. **Empty / `help` / `menu` / `?`** → menu + session selector, answered from this file alone: open no stage file. The menu offers describing a task to start the forward pipeline, plus `/muggle-status`, `/muggle-repair`, and `/muggle-upgrade`. The session selector lists each directory under `~/.muggle-ai/muggle-do/sessions/` with the PRs and states in its `prs.json`; picking one resumes that session.
 6. **Task automation** (perform an action on a website) → `muggle:muggle-browser-task`.
 7. **Otherwise** → forward pipeline at Stage 1.
 

package/dist/plugin/skills/do/unit-tests.md

@@ -19,7 +19,7 @@ You receive:
 
 For each repo:
 
-1. **Run the test command** using Bash in the repo's directory. Use the provided test command (default: `pnpm test`). Suites must run in one-shot mode (`CI=true`, `--watchAll=false`, `vitest run`) — never watch mode: an orphaned watcher fork-bombs on Windows. Launch through the shipped cap so the process tree is kernel-bounded and reaped if this run is killed: `node "${CLAUDE_PLUGIN_ROOT}/scripts/guard-run.mjs" -- <test command>`.
+1. **Run the test command** using Bash in the repo's directory. Use the provided test command (default: `pnpm test`). Suites must run in one-shot mode (`vitest run`, jest `--watchAll=false`) — never watch mode: an orphaned watcher fork-bombs on Windows. Never set `CI=true` for a local run: repos key their local worker cap and changed-files scoping on `CI` being unset, so it runs the full suite at one worker per core. Launch through the shipped cap so the process tree is kernel-bounded and reaped if this run is killed: `node "${CLAUDE_PLUGIN_ROOT}/scripts/guard-run.mjs" -- <test command>`.
 2. **Capture the full output** — both stdout and stderr.
 3. **Determine pass/fail** — exit code 0 means pass, anything else means fail.
 4. **If tests fail**, extract the specific failing test names/descriptions from the output.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.26.0",
-  "buildId": "run-274-1",
-  "commitSha": "79c091d63782313be3672ba64db5ae65c44e2c2b",
-  "buildTime": "2026-11-01T07:21:17Z",
+  "buildId": "run-276-1",
+  "commitSha": "b471e9f5955a787d6752dc41a20db87ceaf0a73e",
+  "buildTime": "2026-11-01T16:33:57Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "description": "13 years of Microsoft hyperscale engineering, packaged as a harness for your AI coding agent.",
   "type": "module",
   "main": "dist/index.js",

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

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.codex-mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.31.0-staging.274",
+        "@muggleai/works@5.31.0-staging.276",
         "serve"
       ],
       "env": {

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "muggle",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
   "author": {
     "name": "Muggle AI",

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

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.31.0-staging.274",
+  "version": "5.31.0-staging.276",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.31.0-staging.274",
+        "@muggleai/works@5.31.0-staging.276",
         "serve"
       ]
     }

package/plugin/skills/do/input-routing.md

@@ -6,7 +6,7 @@ How `/muggle-do` resolves `$ARGUMENTS` to a mode. Modes 1–4 are programmatic
 2. **Fix-CI** — a PR/MR URL **and** a `fix ci` / `fix-ci` directive with failing check names (no review/discussion ids) → [`fix-ci.md`](fix-ci.md).
 3. **Rebase** — a PR/MR URL **and** a `rebase` directive (or legacy `resolve conflicts` / `resolve-conflicts`; no review/discussion ids, no check names) → [`resolve-conflicts.md`](resolve-conflicts.md). Rebases the branch onto its base whether it's merely behind or actually conflicting.
 4. **Post-merge cleanup** — a `cleanup` token and `slug=<slug>` (no PR URL, no review ids), optionally `state=<merged|closed>` (default `merged`) → [`cleanup.md`](cleanup.md).
-5. **Empty / `help` / `menu` / `?`** → menu + session selector.
+5. **Empty / `help` / `menu` / `?`** → menu + session selector, answered from this file alone: open no stage file. The menu offers describing a task to start the forward pipeline, plus `/muggle-status`, `/muggle-repair`, and `/muggle-upgrade`. The session selector lists each directory under `~/.muggle-ai/muggle-do/sessions/` with the PRs and states in its `prs.json`; picking one resumes that session.
 6. **Task automation** (perform an action on a website) → `muggle:muggle-browser-task`.
 7. **Otherwise** → forward pipeline at Stage 1.
 

package/plugin/skills/do/unit-tests.md

@@ -19,7 +19,7 @@ You receive:
 
 For each repo:
 
-1. **Run the test command** using Bash in the repo's directory. Use the provided test command (default: `pnpm test`). Suites must run in one-shot mode (`CI=true`, `--watchAll=false`, `vitest run`) — never watch mode: an orphaned watcher fork-bombs on Windows. Launch through the shipped cap so the process tree is kernel-bounded and reaped if this run is killed: `node "${CLAUDE_PLUGIN_ROOT}/scripts/guard-run.mjs" -- <test command>`.
+1. **Run the test command** using Bash in the repo's directory. Use the provided test command (default: `pnpm test`). Suites must run in one-shot mode (`vitest run`, jest `--watchAll=false`) — never watch mode: an orphaned watcher fork-bombs on Windows. Never set `CI=true` for a local run: repos key their local worker cap and changed-files scoping on `CI` being unset, so it runs the full suite at one worker per core. Launch through the shipped cap so the process tree is kernel-bounded and reaped if this run is killed: `node "${CLAUDE_PLUGIN_ROOT}/scripts/guard-run.mjs" -- <test command>`.
 2. **Capture the full output** — both stdout and stderr.
 3. **Determine pass/fail** — exit code 0 means pass, anything else means fail.
 4. **If tests fail**, extract the specific failing test names/descriptions from the output.

package/scripts/muggle-watch/README.md

@@ -8,6 +8,7 @@ A standing per-user scheduled job that runs `muggle watch tick` every few minute
 - **Closes out finished slots.** A slot whose PR GitHub reports merged or closed, with no loop and no running owner, is finalized the way a watcher's terminal tick would: `prs.json` takes the state, `followup.log` the terminal line, and `result.md` is written. Only local files change; post-merge cleanup is left to a session and recorded as not run.
 - **Keeps sessions on the installed build.** A session loaded before the newest global install (or a later user-scope update of the muggle plugin) is behind; other plugins updating restart nothing. Idle background sessions are respawned onto the new build, up to 3 per tick, keeping their own id and name. A session that owns open PR watches is left running. Before a restart, a throwaway background launch in the session's workspace confirms Claude will bring it back; a workspace that refuses is left running and named once. Busy or waiting sessions wait for a later tick, and terminal sessions get one notification to run `/reload-plugins`. No interface runs a slash command inside another session.
 - **Keeps sessions on Remote Control.** With `remoteControlAtStartup` on in Claude's settings, a live background session is off when its `~/.claude/sessions/<pid>.json` entry has no Remote Control link, or its process started before the current claude.ai login took effect, so its link serves another account. Such a session is respawned once its turn is over (registry status `idle` or `shell`), sharing the 3-per-tick cap with the reload. That keeps the same session id, so there is no duplicate in the agent view, and nothing is typed into it. Background commands carry over to the restarted process, PR watch loops included, so they keep reporting to that session. Each restart opens a new Remote Control session, so a session already on is never restarted. A restarted session gets 30 minutes to link, and one still off after 2 restarts in a day is left alone. Terminal sessions that are off are listed for `/remote-control`.
+- **Continues sessions a usage limit cut off.** Claude never retries a turn a usage limit ended: the session stays stopped on the limit notice. A background session whose last turn is that notice is resumed in place with one continue prompt once the notice's own reset time has passed and Claude's usage cache shows no window still exhausted. A running session is stopped first, between turns only, and a copy Claude starts instead is removed. Each notice is continued once, a session at most twice a day, sharing the per-tick cap with owner wakes; a notice older than 8 days is left alone, and terminal sessions are listed to continue by hand.
 - **Records and alerts.** Results go to `status.json` (last snapshot, with open-PR and Remote Control coverage), `state.json` (active findings, recovery attempts, reload progress, the login last seen, Remote Control restarts) and `events.jsonl` (raise/clear/resume/respawn/close-out history) under `~/.muggle-ai/watch/`. New alerts raise one desktop notification per tick.
 
 ## Install
@@ -45,6 +46,7 @@ On Windows the PowerShell installer also takes flags directly:
 | `-NoRecovery` | Report dead watchers without resuming their owners |
 | `-NoAutoReload` | Never restart sessions onto a new build |
 | `-NoRemoteControl` | Report sessions off Remote Control without restarting them |
+| `-NoLimitResume` | Report sessions a usage limit cut off without continuing them |
 | `-NoWait` | Return once the task is registered, before its first tick |
 | `-MuggleEntry <path>` | Run a specific `bin\muggle.js` instead of the global install |
 | `-Uninstall` | Remove the task; the ledger is kept |

package/scripts/muggle-watch/install-muggle-watch.ps1

@@ -3,7 +3,8 @@
 # Codex sessions, their processes and every PR-watch slot, alerts on dead or deaf
 # watchers, red CI and stale branches, restarts the loop of a registered slot
 # whose watcher died, fans plugin reloads out across sessions, and restarts
-# sessions that are off Remote Control under the current login.
+# sessions that are off Remote Control under the current login, and continues
+# background sessions a usage limit cut off once that limit resets.
 #
 # The task runs the global @muggleai/works install, whose path survives
 # `muggle upgrade`, so the service always runs the current release. Only the
@@ -22,6 +23,7 @@ param(
     [switch]$NoAutoReload,
     [switch]$NoRecovery,
     [switch]$NoRemoteControl,
+    [switch]$NoLimitResume,
     # Return once the task is registered; its trigger runs the first tick a minute later.
     [switch]$NoWait,
     [switch]$Uninstall
@@ -64,6 +66,7 @@ $tickFlags = @()
 if ($NoAutoReload) { $tickFlags += "--no-auto-reload" }
 if ($NoRecovery) { $tickFlags += "--no-recovery" }
 if ($NoRemoteControl) { $tickFlags += "--no-remote-control" }
+if ($NoLimitResume) { $tickFlags += "--no-limit-resume" }
 $launcherArguments = @("`"$installedLauncher`"", "`"$($nodeCommand.Source)`"", "`"$MuggleEntry`"") + $tickFlags
 
 # wscript.exe rather than node.exe is what keeps every run off the desktop; see