claude-use 9.10.1 → 9.12.0

package/README.md

@@ -264,6 +264,8 @@ Issues and pull requests are welcome. Please keep the tool itself free of assump
 - [docs/headroom-measurement.md](docs/headroom-measurement.md): measuring what headroom's transforms are worth on real conversations, offline: the replay method, the cache-weighted cost model and its limits.
 - [docs/rc-interception-rig.md](docs/rc-interception-rig.md): the Remote Control interception rig: bring-up, per-host TLS proof, teardown, and the manual login step.
 - [docs/rc-web-client.md](docs/rc-web-client.md): the self-hosted Remote Control web client: the page the door serves behind its control token for browser control of its sessions, how it authenticates and speaks the typed API, and how it is tested.
+- [docs/rc-agent-events.md](docs/rc-agent-events.md): the task and subagent lifecycle events a Remote Control session's read stream carries, and the keys that join them to the transcripts on disk.
+- [docs/agent-transcripts.md](docs/agent-transcripts.md): how Claude Code lays out a session's subagents, forks, workflow runs, tasks, teams and jobs on disk, and which fields are always present.
 
 ## License
 

package/dist/cli.cjs

@@ -33243,7 +33243,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "claude-use",
-      version: "9.10.1",
+      version: "9.12.0",
       description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
       license: "MIT",
       author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -34027,6 +34027,25 @@ function windowBurn(records, which) {
   }
   return (last.utilization - first.utilization) / (last.atMs - first.atMs);
 }
+function windowRatio(records) {
+  const points = [];
+  for (const record2 of records) {
+    const unified = record2.rateLimitHeaders === void 0 ? void 0 : parseUnifiedRateLimit(record2.rateLimitHeaders);
+    const five = unified?.fiveHour;
+    const seven = unified?.sevenDay;
+    if (five?.utilization !== void 0 && five.resetsAt !== void 0 && seven?.utilization !== void 0 && seven.resetsAt !== void 0) {
+      points.push({ fiveResetsAt: five.resetsAt, sevenResetsAt: seven.resetsAt, five: five.utilization, seven: seven.utilization });
+    }
+  }
+  const latest = points.at(-1);
+  const current = points.filter((point) => point.fiveResetsAt === latest?.fiveResetsAt && point.sevenResetsAt === latest.sevenResetsAt);
+  const first = current.at(0);
+  const last = current.at(-1);
+  if (first === void 0 || last === void 0 || last.five <= first.five || last.seven <= first.seven) {
+    return void 0;
+  }
+  return (last.seven - first.seven) / (last.five - first.five);
+}
 function percent(fraction) {
   return `${String(Math.round(fraction * PERCENT))}%`;
 }
@@ -34108,15 +34127,21 @@ function assessIdentity(member, nowMs) {
   }
   const remaining = Math.max(0, 1 - basis.window.utilization);
   const untilResetMs = basis.window.resetsAtMs === void 0 ? basis.windowMs : Math.max(basis.window.resetsAtMs - nowMs, MS_PER_SECOND3);
-  const score = remaining * plan.capacity / (untilResetMs / MS_PER_HOUR2);
+  const weeklyScore = remaining * plan.capacity / (untilResetMs / MS_PER_HOUR2);
   const fiveRemaining = five?.utilization === void 0 ? void 0 : Math.max(0, 1 - five.utilization);
   const fiveUntil = five?.resetsAtMs === void 0 ? FIVE_HOUR_WINDOW_MS : Math.max(five.resetsAtMs - nowMs, MS_PER_SECOND3);
+  const ratio = windowRatio(member.records);
+  const fiveHourScore = basis.name === "sevenDay" && fiveRemaining !== void 0 && ratio !== void 0 ? Math.min(fiveRemaining * ratio, remaining) * plan.capacity / (fiveUntil / MS_PER_HOUR2) : void 0;
+  const fiveHourLeads = fiveHourScore !== void 0 && fiveHourScore > weeklyScore;
+  const score = fiveHourLeads ? fiveHourScore : weeklyScore;
+  const scoreWindow = fiveHourLeads ? "fiveHour" : basis.name;
+  const fiveHourTermReasons = basis.name !== "sevenDay" || fiveRemaining === void 0 ? [] : ratio === void 0 ? ["5h reset not scored: no measured 5h to 7d ratio yet"] : fiveHourLeads ? [`5h term leads: ${percent(fiveRemaining)} of 5h unused is about ${percent(Math.min(fiveRemaining * ratio, remaining))} of the week at the measured ratio, resets in ${formatAge(fiveUntil)}`] : [];
   const burn = windowBurn(member.records, "fiveHour");
   const sevenRemaining = seven?.utilization === void 0 ? void 0 : Math.max(0, 1 - seven.utilization);
   const sevenUntil = seven?.resetsAtMs === void 0 ? SEVEN_DAY_WINDOW_MS : Math.max(seven.resetsAtMs - nowMs, MS_PER_SECOND3);
   const sevenDayBurn = windowBurn(member.records, "sevenDay");
   return {
-    candidate: { ...base, class: "scored", score, scoreWindow: basis.name, reasons: [...windowReasons.map((reason, index) => index === windowReasons.length - 1 ? `${reason}${observedAgo}` : reason), ...planReasons] },
+    candidate: { ...base, class: "scored", score, scoreWindow, reasons: [...fiveHourTermReasons, ...windowReasons.map((reason, index) => index === windowReasons.length - 1 ? `${reason}${observedAgo}` : reason), ...planReasons] },
     ...fiveRemaining === void 0 ? {} : { fiveHour: { remaining: fiveRemaining, untilResetMs: fiveUntil } },
     ...burn === void 0 ? {} : { burn },
     ...sevenRemaining === void 0 ? {} : { sevenDay: { remaining: sevenRemaining, untilResetMs: sevenUntil } },
@@ -120492,7 +120517,7 @@ var PoolPickCandidateViewSchema = external_exports.strictObject({
   class: external_exports.enum(["scored", "unknown", "pay-per-use", "ineligible"]),
   /** Plan-size-weighted remaining quota per hour until its reset; present for `scored` only. */
   score: external_exports.number().optional(),
-  /** Which window's reset divides the score: the seven-day window, or the five-hour one when the member reports no seven-day utilisation; present with `score`. */
+  /** Which window's reset divides the score: the seven-day window, or the five-hour one when the member reports no seven-day utilisation or its measured-ratio five-hour term outranks the weekly one; present with `score`. */
   scoreWindow: external_exports.enum(["sevenDay", "fiveHour"]).optional(),
   /** False when the five-hour window would run dry, at the observed pace, before it resets. */
   feasible: external_exports.boolean(),
@@ -120610,6 +120635,82 @@ var CheckReportJsonSchema = external_exports.strictObject({
 init_middleware();
 init_preflight();
 
+// src/usage/resets.ts
+init_preflight();
+init_rateLimit();
+var MS_PER_HOUR3 = 36e5;
+var HOURS_PER_DAY4 = 24;
+var PERCENT4 = 100;
+function formatPeriod(window) {
+  if (window.periodMs === void 0) {
+    return window.period ?? "unknown period";
+  }
+  const hours = window.periodMs / MS_PER_HOUR3;
+  return hours >= HOURS_PER_DAY4 && Number.isInteger(hours / HOURS_PER_DAY4) ? `${String(hours / HOURS_PER_DAY4)}d` : `${String(hours)}h`;
+}
+function groupOf(row) {
+  return row.resetsAt === void 0 ? 2 : row.reset ? 1 : 0;
+}
+function compareRows(left, right) {
+  return groupOf(left) - groupOf(right) || (left.resetsAt ?? "").localeCompare(right.resetsAt ?? "") || left.identity.localeCompare(right.identity) || left.provider.localeCompare(right.provider) || left.window.localeCompare(right.window);
+}
+function rowOf(snapshot, provider, window, observedAt2, recorded, nowMs) {
+  const effective = effectiveWindow(recorded, nowMs);
+  return {
+    identity: snapshot.identity,
+    provider,
+    window,
+    observedAt: observedAt2,
+    ...recorded.resetsAt === void 0 ? {} : { resetsAt: recorded.resetsAt },
+    reset: effective.reset,
+    ...effective.utilization === void 0 ? {} : { utilization: effective.utilization },
+    ...effective.status === void 0 ? {} : { status: effective.status }
+  };
+}
+function collectResets(snapshots, nowMs) {
+  const rows = snapshots.flatMap(
+    (snapshot) => Object.entries(snapshot.providers).flatMap(([provider, state]) => {
+      const unified = state.rateLimit?.unified;
+      const observedAt2 = state.rateLimit?.observedAt;
+      const overage = unified === void 0 ? void 0 : soleOverageWindow(unified);
+      const headerRows = observedAt2 === void 0 || unified === void 0 ? [] : [
+        ...unified.fiveHour === void 0 ? [] : [rowOf(snapshot, provider, "5h", observedAt2, unified.fiveHour, nowMs)],
+        ...unified.sevenDay === void 0 ? [] : [rowOf(snapshot, provider, "7d", observedAt2, unified.sevenDay, nowMs)],
+        ...overage === void 0 ? [] : [rowOf(snapshot, provider, "extra usage", observedAt2, overage, nowMs)]
+      ];
+      const quota = state.quota;
+      const quotaRows = quota === void 0 ? [] : quota.windows.map((window) => rowOf(snapshot, provider, `${window.measures} ${formatPeriod(window)}`, quota.observedAt, window, nowMs));
+      return [...headerRows, ...quotaRows];
+    })
+  );
+  return { resets: rows.sort(compareRows) };
+}
+function formatResetRow(row, nowMs) {
+  const used = row.utilization === void 0 ? "usage unknown" : `${String(Math.round(row.utilization * PERCENT4))}% used`;
+  const when = row.resetsAt === void 0 ? "no reset time reported" : row.reset ? `reset at ${row.resetsAt}` : `resets ${row.resetsAt} (in ${formatAge(Date.parse(row.resetsAt) - nowMs)})`;
+  return `${row.identity} / ${row.provider}: ${row.window} ${used}, ${when}${row.status === void 0 ? "" : ` (${row.status})`}`;
+}
+
+// src/usage/resetsSchema.ts
+init_zod();
+var ResetRowSchema = external_exports.strictObject({
+  identity: external_exports.string(),
+  provider: external_exports.string(),
+  /** What the window is: `5h`, `7d` or `extra usage` for an Anthropic account, or the provider's own measure and period (`tokens 5h`). */
+  window: external_exports.string(),
+  /** When the state the window comes from was observed, as an ISO instant. */
+  observedAt: external_exports.iso.datetime(),
+  /** When the window resets, as an ISO instant; absent when the upstream reported none. */
+  resetsAt: external_exports.iso.datetime().optional(),
+  /** True when the reset time has passed, so the recorded observation describes a window that no longer exists and its utilisation reads as 0. */
+  reset: external_exports.boolean(),
+  /** The fraction used, as `effectiveWindow` reads it at the report's own clock. */
+  utilization: external_exports.number().optional(),
+  /** The window's own status, for a window that has not reset yet. */
+  status: external_exports.string().optional()
+});
+var ResetScheduleSchema = external_exports.strictObject({ resets: external_exports.readonly(external_exports.array(ResetRowSchema)) });
+
 // src/frontdoor/controlSchemas.ts
 var import_node_path41 = __toESM(require("node:path"), 1);
 init_zod();
@@ -123735,6 +123836,7 @@ function createControlApiRouter(deps) {
   return {
     usage: {
       list: authed.meta(openapi({ method: "GET", path: "/rest/usage/snapshots", summary: "List every identity's usage snapshot", tags: [USAGE_API_TAG] })).output(UsageListOutputSchema).handler(() => ({ snapshots: deps.usageSnapshots() })),
+      resets: authed.meta(openapi({ method: "GET", path: "/rest/usage/resets", summary: "List every recorded quota window with when it resets", tags: [USAGE_API_TAG] })).output(ResetScheduleSchema).handler(() => collectResets(deps.usageSnapshots(), deps.now())),
       effectiveWindow: authed.meta(openapi({ method: "GET", path: "/rest/usage/windows", summary: "Read one identity's effective quota windows", tags: [USAGE_API_TAG] })).input(UsageWindowsInputSchema).output(UsageWindowsOutputSchema).handler(({ input: input2 }) => {
         const snapshot = deps.usageSnapshotOf(input2.identity);
         if (snapshot === void 0) {
@@ -123924,11 +124026,11 @@ function rcFanoutOnDoorHub(fanout, hub) {
 
 // src/frontdoor/quotaExpiringEvents.ts
 init_schema2();
-var MS_PER_HOUR3 = 36e5;
+var MS_PER_HOUR4 = 36e5;
 var MS_PER_DAY3 = 864e5;
 var FIVE_HOUR_WINDOW_HOURS = 5;
 var SEVEN_DAY_WINDOW_DAYS = 7;
-var FIVE_HOUR_WINDOW_MS2 = FIVE_HOUR_WINDOW_HOURS * MS_PER_HOUR3;
+var FIVE_HOUR_WINDOW_MS2 = FIVE_HOUR_WINDOW_HOURS * MS_PER_HOUR4;
 var SEVEN_DAY_WINDOW_MS2 = SEVEN_DAY_WINDOW_DAYS * MS_PER_DAY3;
 var FINAL_SPAN_DENOMINATOR = 30;
 var QUOTA_EXPIRING_WINDOW_FRACTION = 1 / FINAL_SPAN_DENOMINATOR;
@@ -126747,7 +126849,7 @@ function numberOf(record2, field) {
   }
   return void 0;
 }
-function pageOfRcChannel(url2, rows, idOf, rowOf) {
+function pageOfRcChannel(url2, rows, idOf, rowOf2) {
   const query = new URL(url2, "http://127.0.0.1").searchParams;
   const anchor2 = query.get("after_event_id") ?? query.get("cursor");
   const rawLimit = query.get("limit");
@@ -126761,7 +126863,7 @@ function pageOfRcChannel(url2, rows, idOf, rowOf) {
   }
   const page = limit === void 0 ? rows.slice(from) : rows.slice(from, from + limit);
   const last = page[page.length - 1];
-  return { data: page.map(rowOf), ...last === void 0 ? {} : { next_cursor: idOf(last) } };
+  return { data: page.map(rowOf2), ...last === void 0 ? {} : { next_cursor: idOf(last) } };
 }
 async function serveRcClientChannels(ctx, tail, method, maxBatchEvents) {
   const { request: request7, response, host } = ctx;
@@ -139643,14 +139745,14 @@ function collectUsageReport(fs22, paths, filters) {
     invalidLines: log.invalidLines
   };
 }
-var PERCENT4 = 100;
+var PERCENT5 = 100;
 var DECIMAL_RADIX = 10;
 function formatWindow(label, window) {
   if (window === void 0) {
     return void 0;
   }
-  const used = window.utilization === void 0 ? "usage unknown" : `${String(Math.round(window.utilization * PERCENT4))}% used`;
-  const grace = window.graceUtilization === void 0 ? "" : `, in grace, ${String(Math.round(window.graceUtilization * PERCENT4))}% of the allowance used`;
+  const used = window.utilization === void 0 ? "usage unknown" : `${String(Math.round(window.utilization * PERCENT5))}% used`;
+  const grace = window.graceUtilization === void 0 ? "" : `, in grace, ${String(Math.round(window.graceUtilization * PERCENT5))}% of the allowance used`;
   return `${label} ${used}${grace}${window.resetsAt === void 0 ? "" : `, resets ${window.resetsAt}`}${window.status === void 0 ? "" : ` (${window.status})`}`;
 }
 function formatMoney(minor, currency) {
@@ -139687,15 +139789,6 @@ function formatLimit(limit) {
   return `last limit: ${limit.kind} (${String(limit.status)}) at ${limit.observedAt}${limit.window === void 0 ? "" : ` on the ${limit.window} window`}${wait2.length === 0 ? "" : `, ${wait2.join(", ")}`}`;
 }
 var MONEY_DECIMALS = 2;
-var MS_PER_HOUR4 = 36e5;
-var HOURS_PER_DAY4 = 24;
-function formatPeriod(window) {
-  if (window.periodMs === void 0) {
-    return window.period ?? "unknown period";
-  }
-  const hours = window.periodMs / MS_PER_HOUR4;
-  return hours >= HOURS_PER_DAY4 && Number.isInteger(hours / HOURS_PER_DAY4) ? `${String(hours / HOURS_PER_DAY4)}d` : `${String(hours)}h`;
-}
 function formatCount(value2) {
   return String(Number(value2.toFixed(MONEY_DECIMALS)));
 }
@@ -139704,7 +139797,7 @@ function formatQuota(quota) {
     const counts = window.used !== void 0 && window.limit !== void 0 ? `, ${formatCount(window.used)} of ${formatCount(window.limit)}` : "";
     const resets = window.resetsAt === void 0 ? "" : `, resets ${window.resetsAt}`;
     const head = index === 0 ? `quota via ${quota.source}${quota.level === void 0 ? "" : ` (${quota.level})`}, observed ${quota.observedAt}: ` : "                                           ";
-    return `  ${head}${window.measures} ${formatPeriod(window)} ${String(Math.round(window.utilization * PERCENT4))}% used${counts}${resets}`;
+    return `  ${head}${window.measures} ${formatPeriod(window)} ${String(Math.round(window.utilization * PERCENT5))}% used${counts}${resets}`;
   });
 }
 function snapshotLines(snapshot, provider) {
@@ -139831,7 +139924,7 @@ function registerUsageCommands(program2, deps) {
   withExamples(
     program2.command("usage").description(
       `Report recorded requests, token usage and the latest quota state per identity and provider, from the usage log the front door writes (the last ${String(USAGE_RETENTION_MS / DAY_MS3)} days). Read-only.`
-    ).option("--identity <name>", "Only this identity's requests and snapshot.").option("--provider <name>", "Only this provider's requests (anthropic for OAuth sessions).").option("--since <duration>", "Only requests from this long ago on: a count followed by m, h, d or w, such as 5h or 7d.", parseDurationOption).option("--refresh", "First fetch the quota of providers that report it through their own usage endpoint (z.ai) or a plan-window usage endpoint (Anthropic subscriptions), regardless of how fresh the stored one is.").option("--json", "Print the report as JSON.").action(async (options) => {
+    ).option("--identity <name>", "Only this identity's requests and snapshot.").option("--provider <name>", "Only this provider's requests (anthropic for OAuth sessions).").option("--since <duration>", "Only requests from this long ago on: a count followed by m, h, d or w, such as 5h or 7d.", parseDurationOption).option("--refresh", "First fetch the quota of providers that report it through their own usage endpoint (z.ai) or a plan-window usage endpoint (Anthropic subscriptions), regardless of how fresh the stored one is.").option("--resets", "Instead of the usage report, list every recorded quota window with when it resets, soonest first.").option("--json", "Print the report as JSON.").action(async (options) => {
       if (options.refresh === true) {
         for (const warning of await refreshQuotas(paths, { ...options.identity === void 0 ? {} : { identity: options.identity }, ...options.provider === void 0 ? {} : { provider: options.provider } })) {
           console.error(warning);
@@ -139842,6 +139935,18 @@ function registerUsageCommands(program2, deps) {
         ...options.provider === void 0 ? {} : { provider: options.provider },
         ...options.since === void 0 ? {} : { sinceMs: Date.now() - options.since }
       });
+      if (options.resets === true) {
+        const nowMs = Date.now();
+        const schedule = collectResets(report.snapshots, nowMs);
+        if (options.json === true) {
+          printJson(schedule);
+          return;
+        }
+        for (const line of schedule.resets.length === 0 ? ["no quota windows recorded yet"] : schedule.resets.map((row) => formatResetRow(row, nowMs))) {
+          console.log(line);
+        }
+        return;
+      }
       if (options.json === true) {
         printJson(report);
         return;
@@ -139850,7 +139955,7 @@ function registerUsageCommands(program2, deps) {
         console.log(line);
       }
     }),
-    ["agent-shim usage", "agent-shim usage --identity work --since 5h", "agent-shim usage --provider z --refresh --json"]
+    ["agent-shim usage", "agent-shim usage --identity work --since 5h", "agent-shim usage --provider z --refresh --json", "agent-shim usage --resets"]
   );
   const account = withExamples(program2.command("account").description("Inspect the Claude account behind each identity: plan, tier and latest quota."), [
     "agent-shim account show work"