@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/prompts.js

@@ -0,0 +1,179 @@
+// System prompts for the main agent, sub-agents and compaction.
+
+import { environmentBlock, memoryFiles } from './context.js';
+import { APP_NAME, INSTALL_DIR } from './config.js';
+
+export function autoMemorySection({ dir, index }) {
+  return `# Auto memory
+You have a persistent, file-based memory for this project at \`${dir}\`. It survives across sessions: use it to remember what will help in future conversations with this user about this project. Write to it with the Write/Edit tools (the directory may not exist yet; Write creates it).
+
+- Each memory is one markdown file in that directory holding one fact, with frontmatter:
+  ---
+  name: short-kebab-case-slug
+  description: one-line summary, used to decide relevance later
+  type: user | feedback | project | reference
+  ---
+  followed by the fact. For feedback and project memories add a **Why:** line and a **How to apply:** line.
+- After writing a memory file, add a one-line pointer to \`MEMORY.md\` in the same directory: \`- [Title](file.md) — hook\`. MEMORY.md is the index loaded into your context at the start of every session; keep it under 200 lines and never put memory content in it.
+- Worth saving: who the user is and how they like to work (user); corrections and approaches the user confirmed, with the reason (feedback); goals, constraints and deadlines that are not visible in the code, with absolute dates (project); pointers to external resources (reference).
+- Not worth saving: anything the code, git history or CLAUDE.md already records, and details that only matter to the current conversation.
+- Before saving, look for an existing memory about the same thing and update it instead of adding a duplicate. Delete memories that turn out to be wrong.
+- When the user asks you to remember or forget something, do it right away.
+- A memory reflects what was true when it was written. Before relying on a remembered file, function or flag, check that it still exists.
+
+## Current MEMORY.md
+${index || '(empty: no memories saved yet)'}`;
+}
+
+export function mainSystemPrompt({ cwd, model, shellName, extra = '', autoMemory = null, selfRestart = false, snapshot = null }) {
+  const memory = memoryFiles(cwd);
+  const memoryText = memory.length
+    ? `\n\n# Memory\nCodebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.\n\n${memory
+      .map((m) => `Contents of ${m.file} (${m.scope === 'user' ? "user's private global instructions for all projects" : m.scope === 'local' ? "user's private project instructions, not checked in" : 'project instructions, checked into the codebase'}):\n\n${m.text}`)
+      .join('\n\n')}`
+    : '';
+
+  return `You are ${APP_NAME}, an interactive command line coding agent modelled on Claude Code. You help users with software engineering tasks: solving bugs, adding functionality, refactoring, explaining code, running builds and tests, and more. Use the instructions below and the tools available to you to assist the user.
+
+IMPORTANT: Assist with authorized security testing, defensive security, CTF challenges, and educational contexts. Refuse requests for destructive techniques, DoS attacks, mass targeting, supply chain compromise, or detection evasion for malicious purposes. Dual-use security tools (C2 frameworks, credential testing, exploit development) require clear authorization context: pentesting engagements, CTF competitions, security research, or defensive use cases.
+IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.
+
+# Tone and style
+- Your output is displayed in a command line interface and rendered as GitHub-flavored markdown in a monospace font. Keep responses scannable.
+- Be direct and skip filler (preamble, restating the request, closing summaries of what you just did), but never cut an answer short: match the length to the task. A review, analysis, plan or explanation should be as long as it takes to be complete and correct, while a simple question gets a short answer.
+- Your thinking and your tool calls are not subject to any brevity limit: think as long as the problem needs, and read as much as you need before acting.
+- Always reply in the same language the user writes in.
+- Only use emojis if the user explicitly requests it.
+- Communicate with the user only through your text output. Never use tools like Bash or code comments as a means to talk to the user.
+- Create files whenever the task needs them (code, tests, scripts, configs); prefer editing an existing file when that is the natural place for the change. Only write documentation files (*.md) when asked or clearly called for.
+- If you cannot or will not help with something, say so briefly without lecturing, and offer alternatives if possible.
+
+# Professional objectivity
+Prioritize technical accuracy and truthfulness over validating the user's beliefs. Provide direct, objective technical information. Disagree respectfully when the evidence warrants it; investigate to find the truth rather than instinctively confirming the user's assumptions.
+
+# Doing tasks
+The user will primarily request software engineering tasks. For these tasks:
+- For a task with several steps, plan it with the TodoWrite tool and keep the list current as you work (see Task management).
+- Understand before changing: use the search tools (Glob, Grep, Read) extensively, in parallel where possible, to learn the codebase and the user's request.
+- NEVER assume a library is available. Check the manifest (package.json, requirements.txt, Cargo.toml, ...) and neighbouring files first.
+- When editing, mimic the existing code style, naming, imports, frameworks and idioms. Look at surrounding context first.
+- Follow security best practices. Never introduce code that exposes or logs secrets, and never commit secrets.
+- Do not add comments to code unless the logic is non-obvious or the user asks.
+- Verify your work: run the project's tests, linters and type checkers when available. Never assume a specific test framework or script; check the README or manifest to find the right commands.
+- NEVER commit changes unless the user explicitly asks you to.
+- Tool results and user messages may include <system-reminder> tags. They contain useful information and reminders added by the harness; they are not part of the user's request.
+
+# Task management
+Use the TodoWrite tool for tasks with three or more distinct steps, so that you track your progress and the user can see it; skip it for simple tasks. Keep the list current: mark a step completed when it is done and the next one in_progress. Make each update in the same response as the tool calls you are making anyway (the tool calls of one response run together) rather than in a response of its own: every extra response re-reads the whole conversation.
+
+# Tool usage policy
+- Prefer the dedicated tools over shell commands: Read instead of cat/head/tail, Edit instead of sed/awk, Write instead of echo/heredoc redirection, Glob instead of find/ls for locating files, Grep instead of grep/rg.
+- You can call multiple tools in a single response. When several independent pieces of information are needed, batch the tool calls so they run in parallel. When calls depend on each other, run them sequentially.
+- For open-ended codebase exploration that may take many searches, use the Task tool with subagent_type "Explore" to save context. Use it proactively when a task matches a sub-agent's description.
+- If a tool call is blocked (by plan mode or a hook), do not retry the same call. Adjust your approach, or tell the user what is in the way.
+- If the user asks you to run tools in parallel, you MUST send a single message with multiple tool use blocks.
+
+# Full access and autonomy
+You run on the user's own test machine with full access: every tool call executes immediately and nothing asks for confirmation. Do not ask for permission to read, write, install, run or delete the things the task needs; the user wants you to use this freedom to get the job done.
+- Work end to end: investigate, implement, run the code, and verify the result before reporting back. Do not stop at a plan unless asked for one.
+- Prefer evidence over assumption: read the code before changing it, and reproduce a bug when you can. Report failures honestly, with the output.
+- Verify in proportion to the risk, cheapest check first: a syntax or type check, then the tests that cover what you changed, and the whole suite once at the end of a change to shared code (in the background while you do something else, when it is long). Do not run a full suite again when nothing it covers has changed since it passed. Keep existing tests: when a change alters behaviour on purpose, update their assertions instead of deleting them. Do not build extra harnesses, mutation checks or review passes unless the user asks or the change is risky (data loss, credentials, killing processes).
+- Keep going through errors: when something fails, diagnose it and try another approach instead of handing the problem back, unless you are genuinely blocked on something only the user can provide.
+- Use sub-agents (Task) for broad searches and independent subtasks, run independent tool calls in parallel, and use run_in_background for long jobs.
+- Full access is not a reason to be careless. Before doing something that cannot be undone and that the user did not ask for (force-pushing, publishing a package, deleting data outside the project, sending messages or spending money through external services), say what you are about to do and wait for an answer.
+- File changes you make with Write, Edit and NotebookEdit are checkpointed per user prompt, and the user can undo them with /rewind. Changes made through Bash are not tracked, so prefer the file tools for edits.
+- Use AskUserQuestion only for decisions that really are the user's to make.
+
+${selfRestart ? `# Your own source code
+You are ${APP_NAME}, running from the source code in ${INSTALL_DIR}. Changing files under src/ or bin/ there does not change the process you are running in: it keeps the old code until it restarts. After you change your own code (to fix a bug you ran into, or to add something you need), call the Restart tool: it first starts the new code in a separate process and refuses to restart if that fails (the error comes back to you: fix it and call Restart again); otherwise the program restarts when your turn ends and the conversation continues by itself. Use its \`then\` field to say what to check afterwards. The program also restarts by itself at the end of a turn in which its source changed. Never restart for any other reason, and never in a loop.
+The user wants you to fix yourself, also in the middle of a task in another project: when a tool of yours misbehaves, a limit of yours gets in the way of the task, or a feature the task needs is missing, and the cause is in your own code rather than in the project or the environment, fix it in ${INSTALL_DIR} right away instead of working around it or reporting it. Keep the fix small and to the point; read that repository's CLAUDE.md first. Verify it there (\`node --check\` on each changed file, then \`npm run check\` and the test files that cover the change, run with ${INSTALL_DIR} as the working directory), call Restart with \`then\` saying how to check the fix and what to go on with in the user's task, and mention the fix briefly in your final answer. Do not commit in that repository unless the user asks.
+
+` : ''}# Code references
+When referencing specific functions or pieces of code include the pattern \`file_path:line_number\` so the user can navigate to the source.
+
+${environmentBlock(cwd, { model, shellName, snapshot })}${memoryText}${autoMemory ? `\n\n${autoMemorySection(autoMemory)}` : ''}${extra ? `\n\n${extra}` : ''}`;
+}
+
+export function subagentSystemPrompt({ cwd, model, shellName, agentPrompt, snapshot = null }) {
+  return `${agentPrompt}
+
+Notes:
+- You are a sub-agent launched by the main agent. The main agent sees only your final message, so make it a complete, self-contained report of what you found or did. The user does not see your intermediate output.
+- Agent threads have their cwd reset between bash calls; use absolute file paths.
+- In your final response, share relevant file paths (always absolute) and code snippets. Include code snippets only when the exact text is load-bearing.
+- Do not use emojis.
+
+${environmentBlock(cwd, { model, shellName, snapshot })}`;
+}
+
+// The terminal tab's title follows the topic of the conversation: after each message the user sends, the
+// small model says whether it starts a new topic and names it (as the official client does).
+export const TOPIC_TITLE_SYSTEM = 'You name the topic of a conversation between a user and a coding assistant, for the title of a terminal tab. Reply with JSON only.';
+
+export function topicTitlePrompt(current, message) {
+  return `${current ? `Current title: ${current}` : 'There is no title yet.'}
+
+The user's new message:
+<message>
+${message}
+</message>
+
+${current ? 'Does this message start a new topic (a different task or question), or does it continue the current one (a follow-up, "continue", an answer, a correction)? ' : ''}Reply with only a JSON object: {"isNewTopic": ${current ? 'true or false' : 'true'}, "title": ...}. For a new topic, "title" names it in 2 to 6 words (at most about 16 characters in Chinese or Japanese), in the language of the user's message, with no quotes, no emoji and no punctuation at the end. Otherwise "title" is null.`;
+}
+
+export const PLAN_MODE_REMINDER = `<system-reminder>
+Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supersedes any other instructions you have received.
+Research the codebase with read-only tools, then present a concise implementation plan by calling the ExitPlanMode tool. Do not ask for approval in plain text; use ExitPlanMode.
+</system-reminder>`;
+
+// The system prompt of the plain summary request (see Agent.requestSummary).
+export const SUMMARY_SYSTEM = 'You are a helpful AI assistant tasked with summarizing conversations.';
+
+export function compactPrompt(instructions) {
+  return `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools: the conversation above is complete, and the only thing wanted now is the summary below.
+
+Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
+This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.
+
+Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts. Then write the summary in <summary> tags with these sections:
+
+1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
+2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Include full code snippets where applicable and a summary of why each file read or edit is important.
+4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent.
+7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
+8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, including file names and code snippets.
+9. Optional Next Step: The next step directly in line with the user's most recent explicit request. Include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off.
+
+Write the summary in the same language the user has been using.
+Do NOT call any tools. Respond with text only.${instructions ? `\n\nAdditional instructions from the user for this summary:\n${instructions}` : ''}`;
+}
+
+export function continuationMessage(summary, { auto }) {
+  return `This session is being continued from a previous conversation that ran out of context. The conversation is summarized below:
+${summary}${auto ? '\n\nPlease continue the conversation from where we left it off without asking the user any further questions. Continue with the last task that you were asked to work on.' : ''}`;
+}
+
+export const INIT_PROMPT = `Please analyze this codebase and create a CLAUDE.md file, which will be given to future instances of this coding agent to operate in this repository.
+
+What to add:
+1. Commands that will be commonly used, such as how to build, lint, and run tests. Include the necessary commands to develop in this codebase, such as how to run a single test.
+2. High-level code architecture and structure so that future instances can be productive more quickly. Focus on the "big picture" architecture that requires reading multiple files to understand.
+
+Usage notes:
+- If there's already a CLAUDE.md, suggest improvements to it.
+- When you make the initial CLAUDE.md, do not repeat yourself and do not include obvious instructions like "Provide helpful error messages to users" or "Write unit tests for all new utilities".
+- Avoid listing every component or file structure that can be easily discovered.
+- Don't include generic development practices.
+- If there are Cursor rules (in .cursor/rules/ or .cursorrules), Copilot rules (in .github/copilot-instructions.md) or an AGENTS.md, make sure to include the important parts.
+- If there is a README.md, make sure to include the important parts.
+- Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
+- Be sure to prefix the file with the following text:
+
+\`\`\`
+# CLAUDE.md
+
+This file provides guidance to coding agents when working with code in this repository.
+\`\`\``;

package/src/ratelimit.js

@@ -0,0 +1,244 @@
+// Rate limits: reading when a limit resets from the response headers, deciding how long to wait
+// before retrying, and the wording shown to the user.
+//
+// Subscription (Claude Code OAuth) requests are limited by rolling windows, 5 hours and 7 days. When
+// one is used up the API answers 429, and the anthropic-ratelimit-unified-* headers say which window
+// it was and when it resets (epoch seconds; these are the fields the official client reads).
+// Waiting for such a reset takes hours, so it is a pause that ends by itself rather than one of the
+// few quick retries used for transient errors.
+
+export const LONG_WAIT_MS = 30_000; // waits this long or longer are shown as "rate limit reached, resuming at ..."
+export const MAX_RETRY_AFTER_MS = 5 * 60_000; // when waiting for limits is off, a longer Retry-After is reported instead
+const RESUME_MARGIN_MS = 2_000; // wake a little after the announced reset (clock skew)
+const RESUME_JITTER_MS = 8_000; // and spread out agents that were all waiting for the same reset
+const SLEEP_TICK_MS = 15_000; // long sleeps are cut into pieces so a suspended computer is noticed on waking
+const MIN_429_ATTEMPTS = 10; // quick retries for a 429 that announces a short wait
+
+// Replaceable clock, so tests can run an hours-long wait instantly.
+export const timing = {
+  now: () => Date.now(),
+  sleep: (ms, signal) => abortableSleep(ms, signal),
+};
+
+function abortableSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const aborted = () => Object.assign(new Error('aborted'), { name: 'AbortError' });
+    if (signal?.aborted) return reject(aborted());
+    const onAbort = () => { clearTimeout(timer); reject(aborted()); };
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+// Sleep until the wall clock reaches `deadline` (ms since epoch). The wait is made of short sleeps
+// and the clock is checked after each one: timers do not advance while the computer is suspended,
+// so a single long timeout could end hours after the limit was lifted.
+export async function sleepUntil(deadline, signal) {
+  for (;;) {
+    const left = deadline - timing.now();
+    if (left <= 0) return;
+    await timing.sleep(Math.min(left, SLEEP_TICK_MS), signal);
+  }
+}
+
+// Milliseconds a "Retry-After" header asks us to wait (delta-seconds or an HTTP date), or null.
+export function parseRetryAfter(value, now = Date.now()) {
+  const s = String(value ?? '').trim();
+  if (!s) return null;
+  if (/^\d+(?:\.\d+)?$/.test(s)) return Math.round(parseFloat(s) * 1000);
+  const at = Date.parse(s);
+  return Number.isFinite(at) ? Math.max(0, at - now) : null;
+}
+
+// Wait before quick retry number `attempt` (1-based): exponential backoff with jitter, or the
+// server's Retry-After when that is longer.
+export function retryDelay(attempt, retryAfterMs = null, rand = Math.random) {
+  const backoff = Math.min(32_000, 1000 * 2 ** (attempt - 1)) + Math.floor(rand() * 500);
+  return retryAfterMs == null ? backoff : Math.max(backoff, retryAfterMs);
+}
+
+function headerValue(headers, name) {
+  if (!headers) return null;
+  if (typeof headers.get === 'function') return headers.get(name);
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) return Array.isArray(value) ? value[0] : value;
+  }
+  return null;
+}
+
+// Epoch seconds, or milliseconds if the number is too big to be seconds. null if not a time.
+function epochMs(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n > 1e11 ? n : n * 1000;
+}
+
+const WINDOW_LABELS = {
+  five_hour: '5-hour limit',
+  seven_day: 'weekly limit',
+  seven_day_opus: 'weekly Opus limit',
+  seven_day_sonnet: 'weekly Sonnet limit',
+  overage: 'extra usage limit',
+};
+
+// What a 429's headers say about the limit:
+//   {label, claim, status, waitMs, resetAt, source}
+// waitMs is how long until a retry can succeed (null when the server did not say) and resetAt the
+// moment that is (ms since epoch). When both a unified reset and a Retry-After are present the
+// longer wait is taken: retrying early only gets rejected again.
+export function parseRateLimit(headers, now = Date.now()) {
+  const h = (name) => headerValue(headers, name) || null;
+  const status = h('anthropic-ratelimit-unified-status');
+  const overage = h('anthropic-ratelimit-unified-overage-status');
+  const claim = h('anthropic-ratelimit-unified-representative-claim');
+  const unifiedReset = epochMs(h('anthropic-ratelimit-unified-reset'));
+  const retryAfter = parseRetryAfter(h('retry-after'), now);
+
+  const found = [];
+  // The official client only treats the reset as a wait when the window is rejected and extra
+  // usage (overage) cannot take over.
+  if (status === 'rejected' && (!overage || overage === 'rejected') && unifiedReset !== null) {
+    found.push({ source: 'unified-reset', waitMs: Math.max(0, unifiedReset - now) });
+  }
+  if (retryAfter !== null) found.push({ source: 'retry-after', waitMs: retryAfter });
+  const best = found.sort((a, b) => b.waitMs - a.waitMs)[0] || null;
+
+  const label = WINDOW_LABELS[claim] || (claim?.startsWith('seven_day') ? 'weekly limit' : 'rate limit');
+  return {
+    label, claim, status,
+    waitMs: best ? best.waitMs : null,
+    resetAt: best ? now + best.waitMs : null,
+    source: best ? best.source : null,
+  };
+}
+
+// "45s", "12m 30s", "2h 13m", "5d 13h". From an hour up it is rounded to the nearest minute, so a
+// reset 2h 59m 59.6s away reads "3h 0m", in line with the clock time shown next to it.
+export function humanDuration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  const m = Math.round(s / 60);
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  return `${Math.floor(h / 24)}d ${h % 24}h`;
+}
+
+// Local time of day, with the date when it is not today: "21:05", "tomorrow 02:15", "Oct 9 21:05".
+export function formatClock(ms, now = Date.now()) {
+  const d = new Date(ms);
+  const hhmm = d.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit', hour12: false });
+  const day = (t) => new Date(t).setHours(0, 0, 0, 0);
+  const days = Math.round((day(ms) - day(now)) / 86_400_000);
+  if (days === 0) return hhmm;
+  if (days === 1) return `tomorrow ${hhmm}`;
+  return `${d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' })} ${hhmm}`;
+}
+
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
+// The error text when waiting is not possible or not allowed. `why` is 'budget' (the wait is longer
+// than rateLimitMaxWait) or 'off' (waiting for limits is switched off or not wanted here).
+function limitMessage(err, rl, state, budget, now, why) {
+  const base = err.message;
+  if (rl?.waitMs == null || rl.waitMs < LONG_WAIT_MS) {
+    return state.waitedMs > 0 ? `${base} (still rate limited after waiting ${humanDuration(state.waitedMs)})` : base;
+  }
+  if (err.status !== 429) return `${base} (the server asked to wait ${humanDuration(rl.waitMs)} before retrying)`;
+  const reset = `${capitalize(rl.label)} reached; it resets at ${formatClock(rl.resetAt, now)} (in ${humanDuration(rl.waitMs)})`;
+  if (why === 'budget') return `${base} (${reset}, beyond the ${humanDuration(budget)} this session may wait. CLAUDE_PRO_RATE_LIMIT_MAX_WAIT_MS raises that.)`;
+  return `${base} (${reset}${budget === 0 ? '. Set CLAUDE_PRO_RATE_LIMIT_MAX_WAIT_MS above 0 to wait for it automatically' : ''}.)`;
+}
+
+// Decide what to do after a failed request. Returns
+//   {action: 'throw', message?}                      give up (message replaces the error text)
+//   {action: 'wait', kind, delayMs, resumeAt, ...}   wait, then try again
+// kind is 'retry' for a quick retry and 'rate_limit' for a pause until a limit resets.
+//
+// `state` is {attempt, rateLimitHits, waitedMs}, kept across the attempts of one request.
+// 429s are handled as follows (unless rateLimitMaxWait is 0, retries are off, or allowWait is false):
+//  - the headers announce a wait of 30s or more (an exhausted 5-hour or weekly window): wait for
+//    that reset, as long as it fits in the budget (rateLimitMaxWait, default 6 hours);
+//  - a short announced wait: a few quick retries, counted like any other;
+//  - nothing announced: back off 1s, 2s, 4s ... up to rateLimitPoll (5 minutes) between attempts, within the budget.
+export function planRetry(err, state, config, { now = Date.now(), rand = Math.random, allowWait = true } = {}) {
+  if (!err.retryable) return { action: 'throw' };
+  const maxRetries = config.maxRetries;
+  const rl = err.rateLimit || null;
+  const budget = config.rateLimitMaxWait;
+  const quick = (attempt, max, retryAfterMs) => {
+    const delayMs = retryDelay(attempt, retryAfterMs, rand);
+    return { action: 'wait', kind: 'retry', delayMs, resumeAt: now + delayMs, attempt, maxRetries: max };
+  };
+
+  if (err.status === 429 && allowWait && maxRetries > 0 && budget > 0) {
+    const known = rl?.waitMs ?? null;
+    if (known !== null && known < LONG_WAIT_MS) {
+      state.attempt++;
+      const max = Math.max(maxRetries, MIN_429_ATTEMPTS);
+      return state.attempt > max ? { action: 'throw' } : quick(state.attempt, max, known);
+    }
+    state.rateLimitHits++;
+    const polling = known === null;
+    const delayMs = polling
+      ? Math.min(config.rateLimitPoll, 1000 * 2 ** (state.rateLimitHits - 1)) + Math.floor(rand() * 500)
+      : known + RESUME_MARGIN_MS + Math.floor(rand() * RESUME_JITTER_MS);
+    if (state.waitedMs + delayMs > budget) return { action: 'throw', message: limitMessage(err, rl, state, budget, now, 'budget') };
+    state.waitedMs += delayMs;
+    return {
+      action: 'wait',
+      kind: delayMs >= LONG_WAIT_MS ? 'rate_limit' : 'retry',
+      delayMs,
+      resumeAt: now + delayMs,
+      resetAt: rl?.resetAt ?? null,
+      label: rl?.label ?? 'rate limit',
+      polling,
+      attempt: state.rateLimitHits,
+      maxRetries: null,
+    };
+  }
+
+  // Everything else: a limited number of attempts with exponential backoff. What the server
+  // announced (a reset time or Retry-After) still counts: a wait too long to sit through is an error.
+  // That is 5 minutes for most errors. A 429 only gets here when nobody waits for limits (a diagnostic
+  // request, or waiting switched off): then a limit that lasts 30 seconds or more is reported with its
+  // reset time at once, rather than sat through attempt after attempt (10 of them, silently).
+  state.attempt++;
+  const max = err.status === 429 && maxRetries > 0 ? Math.max(maxRetries, MIN_429_ATTEMPTS) : maxRetries;
+  if (state.attempt > max) return { action: 'throw' };
+  const announced = rl?.waitMs ?? err.retryAfterMs ?? null;
+  const tooLong = announced !== null && (err.status === 429 ? announced >= LONG_WAIT_MS : announced > MAX_RETRY_AFTER_MS);
+  if (tooLong) return { action: 'throw', message: limitMessage(err, rl, state, budget, now, 'off') };
+  return quick(state.attempt, max, announced);
+}
+
+// Words for the pause notice, shared by the interactive and the print mode.
+export function describePause(ev, now = Date.now()) {
+  // The limit is over but the subscription login has expired meanwhile (its token lives 8 hours) and could
+  // not be renewed by this program: the request goes on as soon as there is a valid login in the file.
+  if (ev.waitingForLogin) {
+    const until = ev.giveUpAt ? ` Giving up at ${formatClock(ev.giveUpAt, now)}.` : '';
+    if (ev.renewError) return `The limit has reset, but the login could not be renewed: ${ev.renewError} Trying again every 5 minutes, and this continues by itself as soon as the login is valid.${until}`;
+    return `The limit has reset, but the Claude Code login has expired and cannot be renewed from here. Waiting for it to be renewed: run claude once, and this continues by itself.${until}`;
+  }
+  const label = capitalize(ev.label || 'rate limit');
+  const left = humanDuration(Math.max(0, ev.resumeAt - now));
+  const text = ev.polling
+    ? `${label} reached and the server gave no reset time. Checking again at ${formatClock(ev.resumeAt, now)} (in ${left}), and every few minutes after that, then continuing automatically.`
+    : `${label} reached. Pausing until ${formatClock(ev.resumeAt, now)} (in ${left}), then continuing automatically.`;
+  const warning = ev.loginExpiresAt && ev.loginExpiresAt < ev.resumeAt
+    ? ` The Claude Code login expires at ${formatClock(ev.loginExpiresAt, now)}, before that, and it cannot be renewed from here. If no Claude Code session is running to renew it, run claude once after the reset: this continues by itself once the login is valid again.`
+    : '';
+  return text + warning;
+}
+
+// Whether a rate_limit_wait event should be announced to the user. `prev` is the wait that was last
+// announced for the same pause (null at the first one). Polling repeats every few minutes and the
+// announced reset moves a little between waits: those only continue the pause already announced,
+// unless the reset moved by more than two minutes. Waiting for the login to be renewed is a different
+// kind of wait from waiting for the limit, and always worth saying when it begins.
+export function shouldAnnounce(prev, ev) {
+  if (!prev) return true;
+  if (Boolean(prev.waitingForLogin) !== Boolean(ev.waitingForLogin)) return true;
+  return !ev.polling && Math.abs(ev.resumeAt - prev.resumeAt) > 120_000;
+}

package/src/restart.js

@@ -0,0 +1,115 @@
+// The program's side of restarting itself (the supervisor's is supervisor.js): what is handed from one
+// process to the next, the check that the new code starts before it is trusted, and the watch on the
+// source files.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { INSTALL_DIR } from './config.js';
+import { ENV_SUPERVISED, ENV_RESTART_FILE, ENV_RESTARTED, RESTART_EXIT_CODE } from './supervisor.js';
+
+export { RESTART_EXIT_CODE };
+
+export const MAX_RESTARTS = 5; // more than this many within RESTART_WINDOW_MS is a loop, not a workflow
+export const RESTART_WINDOW_MS = 5 * 60_000;
+
+// True in a session that runs under the supervisor, so that it can restart.
+export function canRestart(env = process.env) {
+  return env[ENV_SUPERVISED] === '1' && Boolean(env[ENV_RESTART_FILE]);
+}
+
+// Leave what the next process needs, where the supervisor said. Throws when it cannot be written, so
+// that a restart that would lose the conversation does not happen.
+export function writeRestartState(state, env = process.env) {
+  const file = env[ENV_RESTART_FILE];
+  if (!file) throw new Error('not running under the supervisor');
+  fs.writeFileSync(file, JSON.stringify(state), { mode: 0o600 });
+}
+
+// In a process that was started by a restart: what the previous one left (once). {} when there is nothing
+// readable, which still tells the caller that this is a restart, not a fresh start. null otherwise.
+export function takeRestartState(env = process.env) {
+  if (env[ENV_RESTARTED] !== '1') return null;
+  const file = env[ENV_RESTART_FILE];
+  if (!file) return {};
+  try {
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return state && typeof state === 'object' ? state : {};
+  } catch {
+    return {};
+  } finally {
+    try { fs.rmSync(file, { force: true }); } catch { /* ignore */ }
+  }
+}
+
+const tidy = (text) => text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '').replace(/\r/g, '').replace(/\n+Node\.js v[\d.]+\s*$/, '').trim().slice(0, 4000);
+
+// Start the program's own code in a throwaway process (`claude-pro --self-check`: every module loads, the
+// interface comes up in a fake terminal, the tools and the system prompt are well formed) and say whether
+// it worked. Resolves {ok, output, ms}; never rejects.
+export function runSelfCheck({ root = INSTALL_DIR, signal, timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve) => {
+    const began = Date.now();
+    const env = { ...process.env, CLAUDE_PRO_SELF_CHECK: '1' };
+    for (const key of [ENV_SUPERVISED, ENV_RESTART_FILE, ENV_RESTARTED]) delete env[key];
+    let output = '';
+    let timedOut = false;
+    let child;
+    try {
+      child = spawn(process.execPath, [path.join(root, 'bin', 'claude-pro.js'), '--self-check'], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (e) {
+      resolve({ ok: false, output: e.message, ms: 0 });
+      return;
+    }
+    const add = (chunk) => { if (output.length < 40_000) output += chunk; };
+    child.stdout.on('data', add);
+    child.stderr.on('data', add);
+    const kill = () => { try { child.kill(); } catch { /* already gone */ } };
+    const timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+    signal?.addEventListener('abort', kill, { once: true });
+    const done = (ok, text) => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', kill);
+      resolve({ ok, output: text, ms: Date.now() - began });
+    };
+    child.on('error', (e) => done(false, e.message));
+    child.on('close', (code) => {
+      if (timedOut) return done(false, `The check did not finish within ${Math.round(timeoutMs / 1000)} seconds.\n${tidy(output)}`.trim());
+      if (signal?.aborted) return done(false, 'The check was cancelled.');
+      done(code === 0, tidy(output));
+    });
+  });
+}
+
+// Watch the program's own source (src/ and bin/) and call `onChange(file)` once the files have stopped
+// changing for a moment. Returns {close()}. A platform that cannot watch just never calls back.
+export function watchSource(root, onChange) {
+  const watchers = [];
+  let timer = null;
+  const hit = (_event, name) => {
+    if (name && !/\.(m?js|json)$/i.test(String(name))) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => { try { onChange(String(name || '')); } catch { /* the callback's problem */ } }, 400);
+    timer.unref?.();
+  };
+  for (const dir of ['src', 'bin']) {
+    try {
+      const watcher = fs.watch(path.join(root, dir), { recursive: true, persistent: false }, hit);
+      watcher.on('error', () => { /* a directory that vanished, a watch limit: not worth a crash */ });
+      watchers.push(watcher);
+    } catch { /* not supported here */ }
+  }
+  return {
+    close() {
+      clearTimeout(timer);
+      for (const w of watchers) { try { w.close(); } catch { /* ignore */ } }
+    },
+  };
+}
+
+// What the model is told when the conversation continues in the new process. It starts with "[" so that it
+// is never taken for what the session is about (see firstUserText).
+export function restartNote({ reason = '', then = '' } = {}) {
+  const why = reason ? ` (${reason})` : '';
+  return `[claude-pro restarted${why}. The new code is loaded and the conversation was resumed from the saved session. ${then ? `Continue with: ${then}` : 'Carry on where you left off.'}]`;
+}