@love-moon/conductor-cli 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @love-moon/conductor-cli
 
+## 0.17.1
+
+### Patch Changes
+
+- 7e92c0f: When a task's model quota runs out ("You've hit your session limit · resets
+  1:20am"), fire no longer stops there. It reads the reset time, schedules a
+  one-off Conductor scheduled message to continue a minute or few after the
+  reset, and posts a single notice. Messages that arrive while waiting are queued
+  and handed to the resume turn together instead of each failing with another
+  "处理失败". The resume shows up in the task's scheduled-message list, where it
+  can be canceled. This also covers a quota hit while Claude works on its own
+  between user turns: ai-sdk now reports such a background turn that ends in an
+  error result (or a process exit after it) as a failed turn.
+- Updated dependencies [7e92c0f]
+  - @love-moon/ai-sdk@0.17.1
+  - @love-moon/conductor-sdk@0.17.1
+
 ## 0.17.0
 
 ### Minor Changes

package/bin/conductor-fire.js

@@ -26,6 +26,17 @@ import {
   resolveSessionRunDirectory as resolveCliSessionRunDirectory,
   resumeProviderForBackend as resumeProviderForCliBackend,
 } from "../src/fire/resume.js";
+import {
+  QUOTA_RESUME_MAX_ATTEMPTS,
+  buildQuotaResumePrompt,
+  computeQuotaResumeAt,
+  createQuotaResumeScheduler,
+  formatResumeTime,
+  isQuotaResumePrompt,
+  mergeQueuedMessages,
+  parseQuotaLimitError,
+  parseQuotaResumePrompt,
+} from "../src/fire/quota-resume.js";
 import {
   REMOTE_WORKTREE_ENV,
   buildRemoteWorktreeSessionOptions,
@@ -2100,8 +2111,19 @@ export class BridgeRunner {
     shouldProcessPrePrompt,
     createFreshBackendSession,
     withFreshSessionBootstrap,
+    quotaResumeScheduler,
+    now,
+    random,
   }) {
     this.backendSession = backendSession;
+    // Model quota handling (see src/fire/quota-resume.js). `undefined` means
+    // "build the HTTP scheduler from env on first use"; tests inject their own.
+    this.quotaResumeSchedulerOverride = quotaResumeScheduler;
+    this.now = typeof now === "function" ? now : () => new Date();
+    this.random = typeof random === "function" ? random : Math.random;
+    this.quotaWait = null;
+    this.quotaResumeAttempts = 0;
+    this.lastQuotaResumeQueue = null;
     this.createFreshBackendSession = createFreshBackendSession;
     this.withFreshSessionBootstrap = withFreshSessionBootstrap;
     this.conductor = conductor;
@@ -2428,6 +2450,7 @@ export class BridgeRunner {
       if (this.needsReconnectRecovery && !this.runningTurn) {
         await this.recoverAfterReconnect();
       }
+      await this.runLocalQuotaResumeIfDue();
       let processed = false;
       try {
         processed = await this.processIncomingBatch();
@@ -3255,6 +3278,19 @@ export class BridgeRunner {
   }
 
   async handleContinuousWorkingStatus(payload) {
+    // A turn claude ran on its own (after a background task or subagent) hit
+    // the quota: no user turn fails, so park the task here.
+    if (
+      payload?.background === true &&
+      payload?.phase === "turn_failed" &&
+      !this.runningTurn &&
+      (await this.enterQuotaWaitIfQuotaError(String(payload.status_done_line || ""), {
+        replyTo: undefined,
+        content: "",
+      }))
+    ) {
+      return;
+    }
     await this.reportRuntimeStatus(payload, payload?.replyTo);
   }
 
@@ -3319,6 +3355,228 @@ export class BridgeRunner {
     this.errorLoop = null;
   }
 
+  getQuotaResumeScheduler() {
+    if (this.quotaResumeSchedulerOverride !== undefined) {
+      return this.quotaResumeSchedulerOverride;
+    }
+    this.quotaResumeSchedulerOverride = createQuotaResumeScheduler();
+    return this.quotaResumeSchedulerOverride;
+  }
+
+  /**
+   * A turn failed because the model quota is used up: park the task until the
+   * quota resets. The resume is a one-off Conductor scheduled message, so it
+   * survives restarts and can be canceled from the schedule list; messages that
+   * arrive meanwhile are queued instead of each failing again. Returns false
+   * (report the error as usual) for other errors, or after
+   * QUOTA_RESUME_MAX_ATTEMPTS resumes in a row hit the quota again.
+   */
+  async enterQuotaWaitIfQuotaError(errorMessage, { replyTo, content }) {
+    const now = this.now();
+    const quota = parseQuotaLimitError(errorMessage, { now });
+    if (!quota) {
+      return false;
+    }
+    const failedItems = this.pendingItemsOfFailedTurn(replyTo, content);
+    if (this.quotaWait) {
+      // Already parked (a background failure, or a turn that raced the wait):
+      // fold this one in rather than scheduling a second resume.
+      await this.addToQuotaWait(failedItems);
+      return true;
+    }
+    this.quotaResumeAttempts += 1;
+    if (this.quotaResumeAttempts > QUOTA_RESUME_MAX_ATTEMPTS) {
+      log(`[quota] ${this.quotaResumeAttempts - 1} resumes in a row hit the quota again; not scheduling another`);
+      this.quotaResumeAttempts = 0;
+      this.lastQuotaResumeQueue = null;
+      return false;
+    }
+    this.lastQuotaResumeQueue = null;
+    const sendAt = computeQuotaResumeAt(quota.resetAt, { now, random: this.random });
+    // Set synchronously, before any await, so messages and background failures
+    // that arrive while the schedule is being created are queued into it.
+    const wait = {
+      // Messages that arrive before this are queued; later ones end the wait.
+      resumeAfter: quota.resetAt && quota.resetAt.getTime() > now.getTime() ? quota.resetAt : sendAt,
+      sendAt,
+      scheduleId: null,
+      localResumeAt: null,
+      queued: failedItems,
+    };
+    this.quotaWait = wait;
+    const scheduler = this.getQuotaResumeScheduler();
+    let scheduleNote = "可在定时消息列表里取消。";
+    let scheduledContent = "";
+    if (scheduler) {
+      // A fire that restarted mid-wait left its resume schedule behind; the new
+      // one replaces it, so carry over what it listed.
+      if (typeof scheduler.listActive === "function") {
+        try {
+          const leftover = await scheduler.listActive({ taskId: this.taskId });
+          wait.queued = mergeQueuedMessages(
+            ...leftover.map((row) => parseQuotaResumePrompt(row?.content)),
+            wait.queued,
+          );
+        } catch (error) {
+          log(`[quota] failed to read earlier resume schedules: ${error?.message || error}`);
+        }
+      }
+      scheduledContent = buildQuotaResumePrompt(wait.queued);
+      try {
+        const created = await scheduler.schedule({
+          taskId: this.taskId,
+          sendAt,
+          content: scheduledContent,
+        });
+        wait.scheduleId = created?.id || null;
+      } catch (error) {
+        log(`[quota] failed to schedule resume: ${error?.message || error}`);
+      }
+    }
+    if (!wait.scheduleId) {
+      // No server schedule: fire keeps the time itself (lost if fire restarts).
+      wait.localResumeAt = sendAt;
+      scheduleNote = "定时消息没有建成，改由本进程计时；如果 fire 重启，需要手动发消息继续。";
+    } else if (buildQuotaResumePrompt(wait.queued) !== scheduledContent) {
+      // Messages queued while the schedule was being created.
+      await this.syncQuotaResumeSchedule();
+    }
+    const resumeLabel = formatResumeTime(sendAt);
+    log(
+      `[quota] waiting until ${sendAt.toISOString()} (reset ${quota.resetAt ? quota.resetAt.toISOString() : "unknown"}) schedule=${wait.scheduleId || "local"} attempt=${this.quotaResumeAttempts}`,
+    );
+    await this.reportRuntimeStatus(
+      {
+        state: "WAITING",
+        phase: "quota_wait",
+        reply_in_progress: false,
+        status_done_line: `额度已用完，${resumeLabel} 自动继续`,
+        quota_resume_at: sendAt.toISOString(),
+      },
+      replyTo,
+    );
+    try {
+      await this.conductor.sendMessage(
+        this.taskId,
+        `${this.backendName} 额度已用完：${errorMessage}\n将在 ${resumeLabel} 自动继续，在此之前收到的消息会排队，届时一起处理。${scheduleNote}`,
+        {
+          severity: "warning",
+          backend: this.backendName,
+          reply_to: replyTo || undefined,
+          quota_wait: true,
+          quota_resume_at: sendAt.toISOString(),
+          cli_args: this.cliArgs,
+        },
+      );
+    } catch (error) {
+      log(`[quota] failed to post wait notice: ${error?.message || error}`);
+    }
+    return true;
+  }
+
+  /** What still has to run after a turn that hit the quota. */
+  pendingItemsOfFailedTurn(replyTo, content) {
+    const text = String(content || "").trim();
+    if (!text) {
+      // A background turn: nothing to redo beyond "continue".
+      return [];
+    }
+    if (!isQuotaResumePrompt(text)) {
+      return [{ messageId: replyTo || null, content: text }];
+    }
+    // A failed resume: what it carried. A fire that restarted mid-wait has no
+    // memory of it, so read the list back out of the prompt itself.
+    return this.lastQuotaResumeQueue
+      ? [...this.lastQuotaResumeQueue]
+      : parseQuotaResumePrompt(text);
+  }
+
+  async addToQuotaWait(items) {
+    const wait = this.quotaWait;
+    const before = wait.queued.length;
+    wait.queued = mergeQueuedMessages(wait.queued, items);
+    if (wait.queued.length !== before) {
+      await this.syncQuotaResumeSchedule();
+    }
+  }
+
+  /** Keep the scheduled resume's text complete, so a fire restart loses nothing. */
+  async syncQuotaResumeSchedule() {
+    const wait = this.quotaWait;
+    const scheduler = this.getQuotaResumeScheduler();
+    if (!wait?.scheduleId || typeof scheduler?.update !== "function") {
+      return;
+    }
+    try {
+      await scheduler.update({
+        taskId: this.taskId,
+        scheduleId: wait.scheduleId,
+        content: buildQuotaResumePrompt(wait.queued),
+      });
+    } catch (error) {
+      log(`[quota] failed to update resume schedule: ${error?.message || error}`);
+    }
+  }
+
+  isQuotaResumeMessage(message, content) {
+    const scheduledMessageId = message?.metadata?.scheduledMessageId;
+    if (scheduledMessageId && this.quotaWait?.scheduleId && scheduledMessageId === this.quotaWait.scheduleId) {
+      return true;
+    }
+    return isQuotaResumePrompt(content);
+  }
+
+  /** While waiting for the quota, queue the message. Returns false once the wait should end. */
+  async queueMessageDuringQuotaWait(message, content) {
+    const wait = this.quotaWait;
+    if (this.isQuotaResumeMessage(message, content)) {
+      return false;
+    }
+    if (this.now().getTime() >= wait.resumeAfter.getTime()) {
+      return false;
+    }
+    const replyTo = message?.message_id || null;
+    if (replyTo) {
+      this.processedMessageIds.add(replyTo);
+    }
+    await this.addToQuotaWait([{ messageId: replyTo, content }]);
+    log(`[quota] queued message ${replyTo || "(no id)"} until ${wait.sendAt.toISOString()} (${wait.queued.length} queued)`);
+    return true;
+  }
+
+  /** Ends the quota wait; returns the prompt for the turn that resumes the task. */
+  async leaveQuotaWait(message, content) {
+    const wait = this.quotaWait;
+    this.quotaWait = null;
+    const isResume = this.isQuotaResumeMessage(message, content);
+    const queued = [...wait.queued];
+    if (!isResume) {
+      // Someone wrote after the quota reset, before the scheduled resume fired.
+      queued.push({ messageId: message?.message_id || null, content });
+      const scheduler = this.getQuotaResumeScheduler();
+      // At or after the send time the schedule is (being) sent: leave it be.
+      if (wait.scheduleId && scheduler?.cancel && this.now().getTime() < wait.sendAt.getTime()) {
+        try {
+          await scheduler.cancel({ taskId: this.taskId, scheduleId: wait.scheduleId });
+        } catch (error) {
+          log(`[quota] failed to cancel resume schedule: ${error?.message || error}`);
+        }
+      }
+    }
+    this.lastQuotaResumeQueue = queued;
+    log(`[quota] resuming with ${queued.length} pending message(s)${isResume ? "" : " (ended by a new message)"}`);
+    return buildQuotaResumePrompt(queued);
+  }
+
+  /** The fallback when no server schedule could be made: resume from fire's own clock. */
+  async runLocalQuotaResumeIfDue() {
+    const wait = this.quotaWait;
+    if (!wait?.localResumeAt || this.runningTurn || this.now().getTime() < wait.localResumeAt.getTime()) {
+      return;
+    }
+    await this.respondToMessage({ role: "user", content: buildQuotaResumePrompt(wait.queued) });
+  }
+
   evaluateErrorLoop(errorMessage) {
     const normalizedKey = normalizeExecutionErrorKey(errorMessage);
     const now = Date.now();
@@ -3383,7 +3641,7 @@ export class BridgeRunner {
         )
       : [];
     const rawContent = String(message.content || "").trim();
-    const content = rawContent || (localAttachments.length ? "Analyze the attached files." : "");
+    let content = rawContent || (localAttachments.length ? "Analyze the attached files." : "");
     if (!content) {
       this.copilotLog(`skip empty message replyTo=${message?.message_id || "latest"}`);
       return;
@@ -3397,6 +3655,16 @@ export class BridgeRunner {
       this.copilotLog(`skip in-flight duplicated message replyTo=${replyTo}`);
       return;
     }
+    if (this.quotaWait) {
+      if (await this.queueMessageDuringQuotaWait(message, content)) {
+        return;
+      }
+      content = await this.leaveQuotaWait(message, content);
+    } else if (isQuotaResumePrompt(content)) {
+      // A resume this fire did not schedule (it restarted while waiting):
+      // its text already lists what was queued.
+      this.lastQuotaResumeQueue = null;
+    }
     if (replyTo) {
       this.inFlightMessageIds.add(replyTo);
     }
@@ -3538,6 +3806,8 @@ export class BridgeRunner {
         this.pendingInitialPrompt = "";
       }
       this.resetErrorLoop();
+      this.quotaResumeAttempts = 0;
+      this.lastQuotaResumeQueue = null;
       if (this.useSessionFileReplyStream) {
         this.copilotLog(`session_file turn settled replyTo=${replyTo || "latest"}`);
       } else {
@@ -3565,6 +3835,12 @@ export class BridgeRunner {
       if (await this.settleCodexCheckpointUnavailableAfterStream(replyTo, errorMessage)) {
         return;
       }
+      if (await this.enterQuotaWaitIfQuotaError(errorMessage, { replyTo, content })) {
+        if (replyTo) {
+          this.processedMessageIds.add(replyTo);
+        }
+        return;
+      }
       this.copilotLog(
         `turn failed replyTo=${replyTo || "latest"} elapsedMs=${Date.now() - turnStartedAt} error="${sanitizeForLog(errorMessage, 200)}"`,
       );
@@ -3942,6 +4218,12 @@ export class BridgeRunner {
     surfaceUserMessage,
     replyMetadata,
   }) {
+    if (this.quotaWait) {
+      // Parked on the quota (e.g. the pre-prompt just hit it): run this with the resume.
+      log(`[quota] ${logTag} queued until ${this.quotaWait.sendAt.toISOString()}`);
+      await this.addToQuotaWait([{ messageId: replyTarget || null, content: String(content || "") }]);
+      return;
+    }
     this.lastRuntimeStatusSignature = null;
     this.runningTurn = true;
     // Lets a target-less interrupt (`/stop`) reach this turn.
@@ -4032,6 +4314,9 @@ export class BridgeRunner {
       ) {
         return;
       }
+      if (await this.enterQuotaWaitIfQuotaError(errorMessage, { replyTo: replyTarget, content })) {
+        return;
+      }
       this.copilotLog(
         `${logTag} turn failed elapsedMs=${Date.now() - startedAt} error="${sanitizeForLog(errorMessage, 200)}"`,
       );

package/bin/conductor-task.js

@@ -19,7 +19,7 @@
  *   schedule update <id> <schedule-id> [<message>] [--delay|--at|--every ...]
  *   stop <id> | interrupt <id> [--target-reply-to <msg-id>]
  *   restart <id> [--strategy inplace|new_task] [--backend] [--refresh-session]
- *           [--daemon-host <h>] [--code-host <h>] [--first-message <text>]
+ *           [--daemon-host <h>] [--code-host <h>] [--first-message <text> [--new-worktree]]
  *   delete <id> --yes [--permanent] | archive <id> | unarchive <id> [--daemon-host <h>]
  *   rename <id> <title> | pin <id> | unpin <id> | labels <id> [<label-id>...] [--clear]
  *   move <id> [<project>] [--back] | share <id> | unshare <id> | shared <token|link>
@@ -875,7 +875,8 @@ export async function main(argvInput = hideBin(process.argv), deps = {}) {
           .option("refresh-session", { type: "boolean", default: false, describe: "Start a fresh AI session in place" })
           .option("daemon-host", { type: "string", describe: "Run the restarted AI on this daemon; with --strategy new_task it keeps working on the source task's code remotely when it can (add --code-host <same> to move the work there instead)" })
           .option("code-host", { type: "string", describe: "With --strategy new_task: daemon holding the code (default: the source task's); another daemon moves the work there and needs --daemon-host set to it" })
-          .option("first-message", { type: "string", describe: "With --strategy new_task: first message instead of the transcript handoff" }),
+          .option("first-message", { type: "string", describe: "With --strategy new_task: first message instead of the transcript handoff" })
+          .option("new-worktree", { type: "boolean", default: false, describe: "With --strategy new_task and --first-message: run the new task in its own fresh git worktree (a parallel branch) instead of the source task's workspace, without loading the source conversation; the source keeps its place in its agent group" }),
         run(extra.handleRestart),
       )
       .command(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.17.0",
-  "gitCommitId": "2799bc0",
+  "version": "0.17.1",
+  "gitCommitId": "e3dbbad",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovemoon-ai/conductor.git"
@@ -24,8 +24,8 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@love-moon/ai-sdk": "0.17.0",
-    "@love-moon/conductor-sdk": "0.17.0",
+    "@love-moon/ai-sdk": "0.17.1",
+    "@love-moon/conductor-sdk": "0.17.1",
     "@github/copilot-sdk": "^0.3.0",
     "chrome-launcher": "^1.2.1",
     "chrome-remote-interface": "^0.33.0",
@@ -38,7 +38,7 @@
   },
   "optionalDependencies": {
     "@roamhq/wrtc": "^0.10.0",
-    "@love-moon/chat-web": "0.17.0"
+    "@love-moon/chat-web": "0.17.1"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/fire/quota-resume.js

@@ -0,0 +1,313 @@
+/**
+ * Model quota ("session limit") handling for fire.
+ *
+ * When a backend turn fails because the subscription quota is used up, fire
+ * parks the task until the quota resets instead of failing every following
+ * message. The resume itself is a one-off Conductor scheduled message
+ * (`source: "quota_resume"`), so it survives fire/daemon restarts and shows up
+ * in the task's schedule list where a person can cancel it.
+ */
+
+const QUOTA_ERROR_PATTERNS = [
+  /hit your (?:[\w-]+ )?limit/i,
+  /usage limit (?:reached|exceeded)/i,
+  /\b(?:session|5-hour|five-hour|weekly|daily|opus|sonnet) limit\b/i,
+];
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+
+/** Used when the error names no reset time at all. */
+export const QUOTA_FALLBACK_WAIT_MS = HOUR_MS;
+/** Resume this long after the reset at the earliest, so the quota has really refilled. */
+export const QUOTA_RESUME_MIN_DELAY_MS = MINUTE_MS;
+/** Extra random spread on top, so tasks sharing one subscription do not all start at once. */
+export const QUOTA_RESUME_JITTER_MS = 4 * MINUTE_MS;
+/** Consecutive quota hits on resume before fire stops scheduling more. */
+export const QUOTA_RESUME_MAX_ATTEMPTS = 3;
+
+export const QUOTA_RESUME_PROMPT =
+  "[额度已恢复，自动继续] 模型额度用完时中断了你的工作。请继续中断前未完成的工作。";
+
+export function isQuotaLimitError(message) {
+  const text = String(message || "");
+  return QUOTA_ERROR_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+/**
+ * Recognises a quota error and works out when the quota resets.
+ * Returns null for any other error; `resetAt` is null when the text names no time.
+ */
+export function parseQuotaLimitError(message, { now = new Date(), defaultTimeZone } = {}) {
+  const text = String(message || "");
+  if (!isQuotaLimitError(text)) {
+    return null;
+  }
+  return { resetAt: parseQuotaResetAt(text, { now, defaultTimeZone }) };
+}
+
+export function parseQuotaResetAt(text, { now = new Date(), defaultTimeZone } = {}) {
+  const nowMs = now.getTime();
+
+  // Older Claude Code: "Claude AI usage limit reached|1759561200"
+  const epoch = /limit reached\|(\d{10,13})/i.exec(text);
+  if (epoch) {
+    const value = Number(epoch[1]);
+    return new Date(epoch[1].length === 10 ? value * 1000 : value);
+  }
+
+  // "try again in 2 hours 13 minutes"
+  const relative = /try again in\s+(?:(\d+)\s*(?:hours?|hrs?|h)\b)?\s*(?:(\d+)\s*(?:minutes?|mins?|m)\b)?/i.exec(text);
+  if (relative && (relative[1] || relative[2])) {
+    return new Date(nowMs + Number(relative[1] || 0) * HOUR_MS + Number(relative[2] || 0) * MINUTE_MS);
+  }
+
+  // "resets 1:20am (Asia/Shanghai)", "resets Oct 7, 2am (Asia/Shanghai)", "try again at 3:05 PM"
+  const clock =
+    /(?:resets?|try again at)\s+(?:at\s+)?(?:([A-Za-z]{3,9})\.?\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*([ap]\.?m\.?)?(?:\s*\(([^)]+)\))?/i.exec(
+      text,
+    );
+  if (!clock) {
+    return null;
+  }
+  const [, monthName, dayText, hourText, minuteText, meridiem, zoneText] = clock;
+  let hour = Number(hourText);
+  const minute = Number(minuteText || 0);
+  if (meridiem) {
+    const pm = meridiem.toLowerCase().startsWith("p");
+    if (hour < 1 || hour > 12) return null;
+    hour = (hour % 12) + (pm ? 12 : 0);
+  }
+  if (hour > 23 || minute > 59) {
+    return null;
+  }
+  const timeZone = resolveTimeZone(zoneText) || resolveTimeZone(defaultTimeZone) || undefined;
+  const today = zonedParts(nowMs, timeZone);
+
+  if (monthName) {
+    const month = MONTHS.indexOf(monthName.slice(0, 3).toLowerCase());
+    if (month < 0) return null;
+    const day = Number(dayText);
+    let resetMs = zonedWallTimeToUtc({ year: today.year, month: month + 1, day, hour, minute }, timeZone);
+    if (resetMs < nowMs - DAY_MS) {
+      resetMs = zonedWallTimeToUtc({ year: today.year + 1, month: month + 1, day, hour, minute }, timeZone);
+    }
+    return new Date(resetMs);
+  }
+
+  let resetMs = zonedWallTimeToUtc({ ...today, hour, minute }, timeZone);
+  if (resetMs <= nowMs - 10 * MINUTE_MS) {
+    // A time-only reset already behind us means tomorrow.
+    resetMs = zonedWallTimeToUtc({ ...today, day: today.day + 1, hour, minute }, timeZone);
+  } else if (resetMs < nowMs) {
+    resetMs = nowMs;
+  }
+  return new Date(resetMs);
+}
+
+/** When to send the resume message: after the reset, plus jitter. */
+export function computeQuotaResumeAt(resetAt, { now = new Date(), random = Math.random } = {}) {
+  const nowMs = now.getTime();
+  const base = resetAt instanceof Date && Number.isFinite(resetAt.getTime())
+    ? resetAt.getTime()
+    : nowMs + QUOTA_FALLBACK_WAIT_MS;
+  const jitter = Math.floor(Math.max(0, Math.min(1, Number(random()) || 0)) * QUOTA_RESUME_JITTER_MS);
+  return new Date(Math.max(base, nowMs) + QUOTA_RESUME_MIN_DELAY_MS + jitter);
+}
+
+/**
+ * The prompt for the resume turn: the resume note plus every message that has
+ * not been handled yet (the one whose turn hit the quota, then those that
+ * arrived while waiting).
+ */
+export function buildQuotaResumePrompt(queued = []) {
+  const parts = [QUOTA_RESUME_PROMPT];
+  const pending = queued.filter((item) => item && String(item.content || "").trim());
+  if (pending.length) {
+    parts.push(`以下 ${pending.length} 条消息还没有处理（按时间顺序）：`);
+    pending.forEach((item, index) => {
+      parts.push(`--- 消息 ${index + 1} ---\n${String(item.content).trim()}`);
+    });
+  }
+  return parts.join("\n\n");
+}
+
+export function isQuotaResumePrompt(content) {
+  return String(content || "").trim().startsWith(QUOTA_RESUME_PROMPT);
+}
+
+const RESUME_ITEM_SEPARATOR = /\n\n--- 消息 \d+ ---\n/;
+
+/**
+ * The pending messages a resume prompt lists (the inverse of
+ * buildQuotaResumePrompt), so a fire that restarted mid-wait can carry them on.
+ */
+export function parseQuotaResumePrompt(content) {
+  const text = String(content || "").trim();
+  if (!isQuotaResumePrompt(text)) {
+    return [];
+  }
+  return text
+    .split(RESUME_ITEM_SEPARATOR)
+    .slice(1)
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => ({ messageId: null, content: part }));
+}
+
+/** Concatenates pending-message lists, dropping repeats of the same text. */
+export function mergeQueuedMessages(...lists) {
+  const seen = new Set();
+  const merged = [];
+  for (const item of lists.flat()) {
+    const key = String(item?.content || "").trim();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    merged.push(item);
+  }
+  return merged;
+}
+
+export function formatResumeTime(date, timeZone) {
+  try {
+    return new Intl.DateTimeFormat("zh-CN", {
+      timeZone: resolveTimeZone(timeZone) || undefined,
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    }).format(date);
+  } catch {
+    return date.toISOString();
+  }
+}
+
+/**
+ * Creates and cancels the resume schedule through the Conductor HTTP API.
+ * Returns null when fire has no backend URL/token (e.g. a guest daemon).
+ */
+export function createQuotaResumeScheduler({ env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  const backendUrl = typeof env.CONDUCTOR_BACKEND_URL === "string" ? env.CONDUCTOR_BACKEND_URL.trim() : "";
+  const token = typeof env.CONDUCTOR_AGENT_TOKEN === "string" ? env.CONDUCTOR_AGENT_TOKEN.trim() : "";
+  if (!backendUrl || !token || typeof fetchImpl !== "function") {
+    return null;
+  }
+  const base = backendUrl.replace(/\/+$/, "");
+  // No X-Conductor-Actor header: this is fire itself, not the agent, so the
+  // task's agent schedule-access setting must not block it.
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+  const schedulesUrl = (taskId) => `${base}/api/tasks/${encodeURIComponent(taskId)}/scheduled-messages`;
+
+  return {
+    async schedule({ taskId, sendAt, content }) {
+      const response = await fetchImpl(schedulesUrl(taskId), {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          content,
+          source: "quota_resume",
+          schedule: { mode: "at", sendAt: sendAt.toISOString() },
+        }),
+      });
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`schedule quota resume failed: HTTP ${response.status} ${detail}`.trim());
+      }
+      const body = await response.json().catch(() => ({}));
+      return { id: typeof body?.id === "string" ? body.id : null };
+    },
+    /** Active quota_resume schedules of the task (left behind by an earlier fire). */
+    async listActive({ taskId }) {
+      const response = await fetchImpl(`${schedulesUrl(taskId)}?status=active`, { method: "GET", headers });
+      if (!response.ok) {
+        throw new Error(`list quota resumes failed: HTTP ${response.status}`);
+      }
+      const body = await response.json().catch(() => ({}));
+      const schedules = Array.isArray(body?.schedules) ? body.schedules : [];
+      // Servers before `source` existed: recognise the resume by its text.
+      return schedules.filter((row) =>
+        row?.source ? row.source === "quota_resume" : isQuotaResumePrompt(row?.content),
+      );
+    },
+    async update({ taskId, scheduleId, content }) {
+      const response = await fetchImpl(`${schedulesUrl(taskId)}/${encodeURIComponent(scheduleId)}`, {
+        method: "PATCH",
+        headers,
+        body: JSON.stringify({ content }),
+      });
+      if (!response.ok) {
+        throw new Error(`update quota resume failed: HTTP ${response.status}`);
+      }
+    },
+    async cancel({ taskId, scheduleId }) {
+      // cancel_only: never delete a row the dispatcher already sent (that
+      // would erase its history); a server without the flag still cancels
+      // active rows, and fire only cancels before the send time.
+      const response = await fetchImpl(
+        `${schedulesUrl(taskId)}/${encodeURIComponent(scheduleId)}?cancel_only=1`,
+        { method: "DELETE", headers },
+      );
+      if (!response.ok && response.status !== 404 && response.status !== 409) {
+        throw new Error(`cancel quota resume failed: HTTP ${response.status}`);
+      }
+    },
+  };
+}
+
+function resolveTimeZone(value) {
+  const zone = typeof value === "string" ? value.trim() : "";
+  if (!zone) return null;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+    return zone;
+  } catch {
+    return null;
+  }
+}
+
+function zonedParts(ms, timeZone) {
+  const parts = {};
+  for (const part of new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  }).formatToParts(new Date(ms))) {
+    if (part.type !== "literal") parts[part.type] = Number(part.value);
+  }
+  return {
+    year: parts.year,
+    month: parts.month,
+    day: parts.day,
+    hour: parts.hour === 24 ? 0 : parts.hour,
+    minute: parts.minute,
+    second: parts.second,
+  };
+}
+
+/** Offset of `timeZone` from UTC at instant `ms`, in ms (local minus UTC). */
+function zoneOffsetMs(ms, timeZone) {
+  const p = zonedParts(ms, timeZone);
+  const asUtc = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+  return asUtc - Math.floor(ms / 1000) * 1000;
+}
+
+/** UTC instant of a wall-clock time in `timeZone` (day overflow is normalised). */
+function zonedWallTimeToUtc({ year, month, day, hour, minute }, timeZone) {
+  const guess = Date.UTC(year, month - 1, day, hour, minute, 0);
+  const first = guess - zoneOffsetMs(guess, timeZone);
+  const second = guess - zoneOffsetMs(first, timeZone);
+  return second;
+}

package/src/task-commands.js

@@ -110,6 +110,12 @@ export async function handleRestart(argv, deps) {
     if (argv.strategy !== "new_task") throw argsError("--first-message requires --strategy new_task");
     body.first_message = trimmed(argv.firstMessage);
   }
+  if (argv.newWorktree) {
+    if (argv.strategy !== "new_task") throw argsError("--new-worktree requires --strategy new_task");
+    // A fresh worktree does not load the source conversation; the first message replaces it.
+    if (!trimmed(argv.firstMessage)) throw argsError("--new-worktree requires --first-message");
+    body.new_worktree = true;
+  }
   if (argv.refreshSession && argv.strategy) {
     throw argsError("--refresh-session cannot be combined with --strategy");
   }