paseo-smart-session 2.2.0 → 3.1.0

package/docs/session-guard.md

@@ -75,6 +75,21 @@ A new user message, another running turn, closing/archiving/removing the agent,
 
 If a reload or connection loss interrupts an unconfirmed stop/send, the pill reads **Check session**. Delivery acceptance may be ambiguous, so the plugin leaves that session for manual inspection instead of retrying a message that might already have arrived. Confirmed waiting work continues automatically.
 
+## With ZeroSub
+
+[ZeroSub](https://github.com/kapybara-org/zerosub) runs Claude and Codex agents on several subscription accounts. When an account hits a limit, ZeroSub moves the agent to another account and continues it. It switches only on the CLI's own limit notice, so an agent the guard interrupts or freezes first never switches. Paseo and the recorder also measure only the CLI's own login. When ZeroSub is enabled on the host, Session Guard reads ZeroSub's registry and usage readings from `$PASEO_HOME/zerosub/` and changes its behaviour as follows:
+
+- **Each agent is measured on its own account.**
+  - An agent on an account ZeroSub added is paused only when *that* account reaches the threshold.
+  - The CLI login keeps Paseo's and the recorder's reading.
+- **ZeroSub goes first.** The guard doesn't pause an agent while ZeroSub's automatic switching is on and another account of the same provider has room. Room means signed in, not disabled, no recorded limit, and a reading under 30 minutes old that is below the threshold.
+  - A session the guard already froze is released when such an account appears, so the CLI reaches the limit and ZeroSub can switch it.
+  - Once no account has room, the guard pauses and continues as before.
+- **A moved session continues sooner.** An interrupted session that ZeroSub moves to an account with room is continued as soon as that account's reading confirms the room. It doesn't wait for the old account's reset.
+- **Codex tasks aren't continued twice.** When ZeroSub carries a Codex task on in another tab, the old tab's waiting continuation is cancelled.
+
+The guard only reads account ids, flags, timestamps and percentages. It never writes ZeroSub's files and never opens an account's credential home. Without ZeroSub, or when its files can't be read, nothing changes.
+
 ## Daemon authentication
 
 For password-protected daemons, Smart Session reads `PASEO_PASSWORD`, then `PASEO_PASSWORD_FILE`, then `~/paseo-hub/secrets/daemon-password`. It never logs or stores the password. Provider usage comes through Paseo; provider credentials are not read directly.
@@ -85,4 +100,4 @@ Workspace labels support text and color. Session Guard uses the short amber labe
 
 ## Agents
 
-Inside Paseo, the `budget_status` tool adds one line about the calling session: whether Session Guard will pause it at the limit and continue it afterwards, or whether it is paused now. It covers only the caller, never other sessions or continuation text, and it cannot turn protection off or resume a pause.
+Inside Paseo, the `budget_status` tool adds one line about the calling session: whether Session Guard will pause it at the limit and continue it afterwards, or whether it is paused now. It covers only the caller, never other sessions or continuation text, and it cannot turn protection off or resume a pause. Under ZeroSub, `budget_status` names the Claude account the session runs on. For an account ZeroSub added, it reports ZeroSub's reading of that account in place of the CLI login's history, and it says when ZeroSub has another account with room.

package/index.server.ts

@@ -1,4 +1,5 @@
 import { contributeGuard } from "./server/guard/index.ts";
+import { zerosubBudgetAccount } from "./server/guard/zerosub.ts";
 import { contributeSessionMcp } from "./server/session-mcp.ts";
 import { displayPreferences } from "./shared/display";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
@@ -45,7 +46,7 @@ export default function contribute(server: PluginServerContext) {
   server.registerSettings(displayPreferences);
   // Pauses work at a provider's session limit; off until someone turns it on.
   const removeGuard = contributeGuard(server);
-  server.handle(budgetStatus, async () => {
+  server.handle(budgetStatus, async ({ agentId }) => {
     try {
       const since = Date.now() - 14 * 24 * 60 * 60 * 1000;
       const samples = await readUsage({ sinceMs: since });
@@ -73,8 +74,11 @@ export default function contribute(server: PluginServerContext) {
         .map((block) => ({ startAt: block.startAt, resetsAt: block.resetsAt, firstSeenAt: block.firstSeenAt, peakPct: block.peakPct }));
 
       const newestInstant = newest === null ? null : effectiveAt(newest);
+      // Under ZeroSub the agent may run on another account than the one recorded.
+      const account = agentId === undefined ? null : await zerosubBudgetAccount(agentId).catch(() => null);
       return {
-        windows,
+        windows: account?.windows ?? windows,
+        ...(account ? { account: account.account } : {}),
         past,
         recorder: {
           newestAt: newestInstant,

package/mcp.mjs

@@ -254,6 +254,32 @@ function describeRelative(iso) {
   return ms >= 0 ? `in ${text}` : `${text} ago`;
 }
 
+/**
+ * Which account `budget_status` describes, when ZeroSub runs agents on several.
+ *
+ * Without ZeroSub the RPC sends no `account`, and nothing changes. A label is shown
+ * only when the person chose it; ZeroSub's generated labels come from the email.
+ */
+function accountLines(account) {
+  if (account === undefined || account === null) return { head: [], tail: [], fromRecorder: true };
+  const name = account.label === null ? "" : ` "${account.label}"`;
+  const head = [
+    account.kind === "main"
+      ? `Account: the CLI's own Claude login${name} (ZeroSub routes this session there).`
+      : `Account: a Claude account ZeroSub added${name}, not the CLI login. These numbers are ZeroSub's reading of it${
+          account.readAt === null ? " (none yet)" : `, taken ${describeRelative(account.readAt)}`
+        }; there is no pace history for it.`,
+  ];
+  const tail = [];
+  const others = account.otherAccountsWithRoom;
+  if (account.autoSwitch && others > 0) {
+    tail.push(
+      `ZeroSub has ${others} other Claude account${others === 1 ? "" : "s"} with room and moves this session to one when this account hits a limit, so a full window here is not a reason to stop early.`,
+    );
+  }
+  return { head, tail, fromRecorder: account.kind === "main" };
+}
+
 /**
  * Session Guard's word on this session, for `budget_status`.
  *
@@ -321,13 +347,14 @@ const TOOLS = {
       "How much of the Claude plan's rolling 5-hour and weekly limits is already consumed, how fast, and when each window resets — and, inside Paseo, whether Session Guard will pause this session at the session limit and continue it after the reset. Call this before spawning several subagents, before a long autonomous run, or when deciding whether to use a more expensive model.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     async run() {
-      const result = await callPlugin("smart-session.budget", {});
+      const result = await callPlugin("smart-session.budget", AGENT_ID === null ? {} : { agentId: AGENT_ID });
       if (result.error) return `Could not read plan usage: ${result.error}`;
       const guard = await guardSummary();
+      const account = accountLines(result.account);
       const interesting = (result.windows ?? []).filter(
         (window) => window.id === "five_hour" || window.id === "seven_day" || window.pct > 0,
       );
-      if (interesting.length === 0) return ["No plan-usage reading recorded yet.", ...guard].join("\n");
+      if (interesting.length === 0) return [...account.head, "No plan-usage reading recorded yet.", ...account.tail, ...guard].join("\n");
 
       const lines = interesting.map((window) => {
         const name = window.id === "five_hour" ? "Session (5h)" : window.id === "seven_day" ? "Week" : window.id;
@@ -340,8 +367,10 @@ const TOOLS = {
         return `- ${parts.join(", ")}`;
       });
 
+      lines.unshift(...account.head);
+      lines.push(...account.tail);
       const recorder = result.recorder;
-      if (recorder?.ageSeconds !== null && recorder?.ageSeconds !== undefined && recorder.ageSeconds > 900) {
+      if (account.fromRecorder && recorder?.ageSeconds !== null && recorder?.ageSeconds !== undefined && recorder.ageSeconds > 900) {
         lines.push(
           `(Newest reading is ${Math.round(HOURS(recorder.ageSeconds * 1000) * 10) / 10}h old — treat these as a floor, not a current number.)`,
         );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "2.2.0",
+  "version": "3.1.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {

package/server/guard/engine.ts

@@ -9,6 +9,12 @@ import type { PublishTimeline } from "./timeline.ts";
  * passes one that also consults Smart Session's recorder (see `./usage.ts`).
  */
 export type ReadUsage = (client: GuardClient) => Promise<Usage>;
+/**
+ * Which account each agent runs on, when an account switcher (ZeroSub) is enabled;
+ * null otherwise. See `shared/guard/zerosub.ts`.
+ */
+export type ReadAccounts = (usage: Usage, policy: Policy) => Promise<AccountView | null>;
+import type { AccountView } from "../../shared/guard/zerosub.ts";
 import {
   isPending, protects, resetReady, sessionWindow, timestamp, usedPct,
   type Agent, type Pause, type Policy, type State, type Usage,
@@ -23,6 +29,10 @@ export class Engine {
   error: string | null = null;
   timelineError: string | null = null;
   usage: Usage | null = null;
+  /** The account view from the last pass, for the agent-facing status. */
+  accounts: AccountView | null = null;
+  /** Each agent's provider from the last pass. */
+  providers = new Map<string, string>();
   private store: Store;
   private policy: () => Promise<Policy>;
   private connect: Connect;
@@ -31,12 +41,14 @@ export class Engine {
   private publish?: PublishTimeline;
   private publishing: Promise<void> | null = null;
   private readUsage: ReadUsage;
+  private readAccounts: ReadAccounts;
   constructor(store: Store, policy: () => Promise<Policy>, connect: Connect, now: () => number = Date.now, processes?: ProcessControl, publish?: PublishTimeline,
-    readUsage: ReadUsage = client => client.listProviderUsage()) {
+    readUsage: ReadUsage = client => client.listProviderUsage(), readAccounts: ReadAccounts = async () => null) {
     this.store = store; this.policy = policy; this.connect = connect; this.now = now;
     this.processes = processes;
     this.publish = publish;
     this.readUsage = readUsage;
+    this.readAccounts = readAccounts;
   }
 
   private async save(state: State) {
@@ -378,7 +390,15 @@ export class Engine {
       const usage = await this.readUsage(client);
       this.usage = usage;
       this.checkedAt = new Date(this.now()).toISOString();
+      // With ZeroSub, each agent is measured on its own account, and an agent it can
+      // move to an account with room is left to it: pausing first would stop the CLI
+      // from reporting the limit ZeroSub fails over on. A failed read is "no ZeroSub".
+      const accounts = await this.readAccounts(usage, policy).catch(() => null);
+      this.accounts = accounts;
+      const usageOf = (agentId: string, provider: string) => accounts?.usageFor(agentId, provider) ?? usage;
+      const failsOver = (agentId: string, provider: string) => accounts?.failsOver(agentId, provider) ?? false;
       const byId = new Map(agents.map(a => [a.id, a]));
+      this.providers = new Map(agents.map(a => [a.id, a.provider]));
       const currentDaemon = await this.processes?.daemonIdentity?.();
       let daemonPid: number | null = null;
       const nativeRunning = async (id: string) => client.listProviderSubagents
@@ -417,6 +437,16 @@ export class Engine {
           await this.cancel(pause, "Session changed, was closed, or protection was turned off."); changed = true; continue;
         }
         if (pause.phase !== "waiting") continue;
+        if (!pause.demo && !pause.manualResume && accounts) {
+          if (pause.wasQuotaFailure && !pause.suspension && accounts.continuedElsewhere(pause.agentId)) {
+            // ZeroSub carried this Codex task on in another tab; continuing here too would run it twice.
+            await this.cancel(pause, "ZeroSub continued this task on another account, so Session Guard will not continue it here."); changed = true; continue;
+          }
+          if (pause.suspension && failsOver(pause.agentId, pause.provider)) {
+            // Let the turn reach the limit, so ZeroSub moves it to the account with room.
+            await this.cancel(pause, "Released for ZeroSub: another account has room, so it switches this session there at the limit."); changed = true; continue;
+          }
+        }
         if (pause.suspension) {
           if (!this.processes) throw new Error("Native worker protection is unavailable.");
           const workerEnded = await this.leftDaemon(pause.suspension);
@@ -435,7 +465,7 @@ export class Engine {
           if ((agent.activeTurn?.turnId ?? null) !== pause.turnId && !await nativeRunning(agent.id)) {
             await this.cancel(pause, "The suspended turn was stopped or changed outside Session Guard."); changed = true; continue;
           }
-          if (pause.demo || !policy.autoResume || this.now() < this.nextResumeAt || !resetReady(pause, usage, policy, this.now())) continue;
+          if (pause.demo || !policy.autoResume || this.now() < this.nextResumeAt || !resetReady(pause, usageOf(pause.agentId, pause.provider), policy, this.now())) continue;
           const latest = (await client.fetchAgent(pause.agentId))?.agent;
           if (!latest || latest.archivedAt || latest.status === "closed" || latest.provider !== pause.provider ||
             (latest.lastUserMessageAt ?? null) !== pause.lastUserMessageAt ||
@@ -459,7 +489,7 @@ export class Engine {
         }
         const canContinue = (candidate: Agent) => candidate.status === "idle" || (pause.closedOnRestart && candidate.status === "closed") || (pause.wasQuotaFailure && candidate.status === "error");
         if (!canContinue(agent) || agent.pendingPermissions?.length || !policy.autoResume ||
-          this.now() < this.nextResumeAt || !resetReady(pause, usage, policy, this.now())) continue;
+          this.now() < this.nextResumeAt || !resetReady(pause, usageOf(pause.agentId, pause.provider), policy, this.now())) continue;
         // Re-read just before sending: a person may have continued while usage was fetched.
         const latest = (await client.fetchAgent(pause.agentId))?.agent;
         if (!latest || !canContinue(latest) || latest.archivedAt || latest.pendingPermissions?.length ||
@@ -494,10 +524,12 @@ export class Engine {
           agent.labels?.internal === "true" || !protects(policy, state.overrides, agent.id) ||
           (policy.providerIds.length > 0 && !policy.providerIds.includes(agent.provider)) ||
           state.pauses.some(p => p.agentId === agent.id && isPending(p))) continue;
-        const provider = usage.providers.find(p => p.providerId === agent.provider);
+        const own = usageOf(agent.id, agent.provider);
+        const provider = own.providers.find(p => p.providerId === agent.provider);
         const window = sessionWindow(provider, policy);
         if (!window || (usedPct(window) ?? -1) < policy.thresholdPct) continue;
-        const fetchedAt = timestamp(provider?.fetchedAt ?? usage.fetchedAt);
+        if (failsOver(agent.id, agent.provider)) continue;
+        const fetchedAt = timestamp(provider?.fetchedAt ?? own.fetchedAt);
         const windowEnd = timestamp(window.resetsAt);
         if (windowEnd !== null && windowEnd <= this.now() && (fetchedAt === null || fetchedAt <= windowEnd)) continue;
         const hasBackground = nativeEnabled && agent.status !== "running" && await nativeRunning(agent.id);

package/server/guard/index.ts

@@ -35,13 +35,15 @@ import { agentGuardSummary, callerProtection } from "../../shared/guard/presenta
 import { withDaemon } from "../daemon.ts";
 import { freshestUsage } from "../store.ts";
 import type { Connect, GuardClient } from "./client.ts";
-import { Engine } from "./engine.ts";
+import { Engine, type ReadAccounts } from "./engine.ts";
 import { WorkspaceLabels } from "./labels.ts";
 import { LinuxProcessControl, type ProcessControl } from "./processes.ts";
 import { standaloneEnabled } from "./standalone.ts";
 import { guardDataDir, LockHeldError, Store } from "./store.ts";
 import { timelinePublisher } from "./timeline.ts";
 import { withRecordedUsage } from "./usage.ts";
+import { readZeroSub } from "./zerosub.ts";
+import { accountView } from "../../shared/guard/zerosub.ts";
 
 /** The install id this plugin's own RPCs are reached through. */
 const PLUGIN_ID = "smart-session";
@@ -64,6 +66,7 @@ const OFF_MESSAGE = "Session Guard is off on this host. Turn it on in Smart Sess
 export interface GuardDependencies {
   connect?: Connect;
   processes?: ProcessControl;
+  readAccounts?: ReadAccounts;
 }
 
 export function contributeGuard(server: PluginServerContext, options: GuardDependencies = {}): () => Promise<void> {
@@ -114,7 +117,12 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
   const store = new Store(guardDataDir());
   const readUsage = async (client: GuardClient): Promise<Usage> =>
     withRecordedUsage(await client.listProviderUsage(), await freshestUsage().catch(() => null));
-  const engine = new Engine(store, readPolicy, connect, Date.now, options.processes ?? new LinuxProcessControl(), publish, readUsage);
+  // With ZeroSub enabled, agents are measured on their own accounts (`shared/guard/zerosub.ts`).
+  const readAccounts = options.readAccounts ?? (async (usage: Usage, policy: Policy) => {
+    const snapshot = await readZeroSub();
+    return snapshot ? accountView(snapshot, usage, policy, Date.now()) : null;
+  });
+  const engine = new Engine(store, readPolicy, connect, Date.now, options.processes ?? new LinuxProcessControl(), publish, readUsage, readAccounts);
   const labels = new WorkspaceLabels(store, (work) => engine.exclusive(work), connect, readPolicy);
 
   let governor: Governor = "off";
@@ -264,8 +272,10 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
   const readState = async (): Promise<State> => (governor === "active" ? engine.exclusive(() => store.read()) : store.read());
   const readPolicyOrDefaults = () => readPolicy().catch(() => PolicySchema.parse({}));
   const emptyState = (): State => ({ version: 1, overrides: {}, pauses: [] });
-  const providerRows = (policy: Policy) =>
-    (governor === "active" ? (engine.usage?.providers ?? []) : []).map((provider) => {
+  const providerRows = (policy: Policy, agentId?: string) =>
+    (governor === "active" ? (engine.usage?.providers ?? []) : []).map((listed) => {
+      // An agent sees its own account's numbers, which under ZeroSub may not be the CLI login's.
+      const provider = (agentId !== undefined && engine.accounts?.usageFor(agentId, listed.providerId).providers.find((p) => p.providerId === listed.providerId)) || listed;
       const window = sessionWindow(provider, policy);
       return { providerId: provider.providerId, usedPct: window ? usedPct(window) : null, resetsAt: window?.resetsAt ?? null };
     });
@@ -301,6 +311,8 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
     const policy = await readPolicyOrDefaults();
     const state = await readState().catch(emptyState);
     const protection = callerProtection(governor === "active" && policy.enabled, policy.protectByDefault, state.overrides[agentId]);
+    const agentProvider = engine.providers.get(agentId);
+    const failsOver = governor === "active" && agentProvider !== undefined && (engine.accounts?.failsOver(agentId, agentProvider) ?? false);
     const pauses = state.pauses
       .filter((pause) => pause.agentId === agentId)
       .map((pause) => ({ id: pause.id, phase: pause.phase, provider: pause.provider, resetsAt: pause.anchorResetsAt }));
@@ -310,8 +322,9 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
       thresholdPct: policy.thresholdPct,
       autoResume: policy.autoResume,
       pauses,
-      providers: providerRows(policy),
-      summary: agentGuardSummary({ governor, protected: protection.protected, thresholdPct: policy.thresholdPct, autoResume: policy.autoResume, pauses }),
+      providers: providerRows(policy, agentId),
+      summary: agentGuardSummary({ governor, protected: protection.protected, thresholdPct: policy.thresholdPct, autoResume: policy.autoResume, pauses, failsOver }),
+      ...(failsOver ? { failsOver } : {}),
     };
   });
 

package/server/guard/zerosub.ts

@@ -0,0 +1,82 @@
+/**
+ * Finding and reading ZeroSub (`@kapybara/zerosub`) on this host, read-only.
+ *
+ * What the readings mean, and why the guard wants them, is in
+ * `shared/guard/zerosub.ts`. This file only answers "is ZeroSub enabled here" from
+ * Paseo's `config.json`, and reads its registry, usage readings and preferences. It
+ * never writes anything of ZeroSub's and never opens an account home, where the
+ * credentials are.
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { budgetAccount, parseZeroSub, type ZeroSubSnapshot } from "../../shared/guard/zerosub.ts";
+
+export const ZEROSUB_ID = "zerosub";
+export const ZEROSUB_PACKAGE = "@kapybara/zerosub";
+
+type ReadText = (path: string) => Promise<string>;
+const readText: ReadText = (path) => readFile(path, "utf8");
+
+const paseoHome = () => process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+
+async function readJson(read: ReadText, path: string): Promise<unknown> {
+  try {
+    return JSON.parse(await read(path)) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+const record = (value: unknown): Record<string, unknown> | null =>
+  typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+
+/**
+ * The install id ZeroSub is enabled under, or null. The id can be anything
+ * (`--id`), so the manifest and package name in its directory are checked too.
+ */
+export async function zerosubInstallId(home = paseoHome(), read: ReadText = readText): Promise<string | null> {
+  const plugins = record(record(await readJson(read, join(home, "config.json")))?.plugins);
+  for (const [id, value] of Object.entries(plugins ?? {})) {
+    const entry = record(value);
+    if (entry?.enabled !== true) continue;
+    if (id === ZEROSUB_ID) return id;
+    const path = typeof entry.path === "string" ? entry.path : null;
+    if (!path) continue;
+    if (record(await readJson(read, join(path, "paseo-plugin.json")))?.id === ZEROSUB_ID) return id;
+    if (record(await readJson(read, join(path, "package.json")))?.name === ZEROSUB_PACKAGE) return id;
+  }
+  return null;
+}
+
+/** ZeroSub's view of accounts, or null when it is not enabled or its registry is unusable. */
+export async function readZeroSub(home = paseoHome(), read: ReadText = readText): Promise<ZeroSubSnapshot | null> {
+  const id = await zerosubInstallId(home, read);
+  if (id === null) return null;
+  const dir = join(home, "zerosub");
+  const [state, usage, preferences] = await Promise.all([
+    readJson(read, join(dir, "state.json")),
+    readJson(read, join(dir, "usage.json")),
+    readJson(read, join(home, "plugin-settings", id, "preferences.json")),
+  ]);
+  return parseZeroSub(state, usage, preferences);
+}
+
+/**
+ * What `budget_status` should report for an agent under ZeroSub: which account, and,
+ * for an account ZeroSub added, that account's own windows in place of the recorder's
+ * (which measure the CLI login). Null without ZeroSub.
+ */
+export async function zerosubBudgetAccount(agentId: string, home = paseoHome(), read: ReadText = readText, now = Date.now()) {
+  const snapshot = await readZeroSub(home, read);
+  const account = snapshot ? budgetAccount(snapshot, agentId, now) : null;
+  if (!account) return null;
+  const windows = account.reading?.windows.map((window) => ({ ...window, burnPctPerHour: null, projectedFullAt: null })) ?? null;
+  return {
+    account: { kind: account.kind, label: account.label, otherAccountsWithRoom: account.otherAccountsWithRoom, autoSwitch: account.autoSwitch, readAt: account.reading?.fetchedAt ?? null },
+    // A managed account without a reading yet: say so with no windows rather than show the CLI login's.
+    windows: account.kind === "managed" ? (windows ?? []) : null,
+  };
+}

package/shared/guard/contracts.ts

@@ -41,6 +41,8 @@ export const agentStatusRpc = defineRpc({
     pauses: z.array(z.object({ id: z.string(), phase: PauseSchema.shape.phase, provider: z.string(), resetsAt: z.string().nullable() })),
     providers: z.array(ProviderSchema),
     summary: z.array(z.string()),
+    /** ZeroSub moves this session to another account with room at the limit, so Session Guard leaves it to it. */
+    failsOver: z.boolean().optional(),
   }),
 });
 export const setProtectionRpc = defineRpc({

package/shared/guard/presentation.ts

@@ -41,6 +41,8 @@ export function agentGuardSummary(status: {
   governor: "off" | "active" | "deferred" | "error";
   protected: boolean; thresholdPct: number; autoResume: boolean;
   pauses: readonly { phase: Pause["phase"]; resetsAt: string | null }[];
+  /** ZeroSub can move this session to another account with room (see `shared/guard/zerosub.ts`). */
+  failsOver?: boolean;
 }): string[] {
   if (status.governor === "deferred") return ["Session Guard: run by another plugin on this host (likely the standalone Session Guard); this session's protection is not visible from here."];
   if (status.governor === "error") return ["Session Guard: status unavailable."];
@@ -49,6 +51,9 @@ export function agentGuardSummary(status: {
   if (pending) {
     return [`Session Guard: this session is paused for the session limit (${pending.phase})${pending.resetsAt ? `; the window resets ${pending.resetsAt}` : ""}.`];
   }
+  if (status.failsOver) {
+    return ["Session Guard: on, but ZeroSub goes first. When this session's account reaches its limit, ZeroSub moves it to another account with room and continues it — no need to stop early or hand off. Session Guard pauses it only once no account has room."];
+  }
   return [`Session Guard: on. At ${status.thresholdPct}% of the session window Paseo pauses this session${status.autoResume
     ? " and continues it in this same conversation once the window resets — no need to stop early or hand off because of the session limit."
     : "; a person continues it after the reset."}`];

package/shared/guard/zerosub.ts

@@ -0,0 +1,276 @@
+/**
+ * Working alongside ZeroSub, which runs Claude and Codex agents on several
+ * subscription accounts and moves an agent to another account when the CLI reports a
+ * limit.
+ *
+ * Without this, Session Guard measures only the CLI login's usage (all Paseo and the
+ * recorder can read) and applies it to every agent of that provider. Under ZeroSub
+ * that pauses agents on accounts with room, and its interrupt or SIGSTOP stops the CLI
+ * from ever printing the limit notice ZeroSub fails over on. So, when ZeroSub is
+ * enabled, the guard reads each agent's account and that account's usage from
+ * ZeroSub's own files, and leaves an agent alone while ZeroSub can move it to another
+ * account with room.
+ *
+ * ZeroSub's files are an internal format, so everything here is parsed defensively:
+ * anything unexpected reads as "no ZeroSub view", which is exactly the guard's
+ * behaviour without ZeroSub. Only ids, flags, timestamps and percentages are kept —
+ * never emails, and never anything from a credential file (none is opened).
+ */
+import type { ProviderUsage, Usage, UsageWindow } from "./policy.ts";
+
+export type ZeroSubFamily = "claude" | "codex";
+
+export interface ZeroSubAccount {
+  readonly id: string;
+  readonly family: ZeroSubFamily;
+  readonly kind: "main" | "managed";
+  /** A name the person chose, or null when ZeroSub derived it from the email. */
+  readonly label: string | null;
+  readonly signedIn: boolean;
+  readonly disabled: boolean;
+  readonly limitedUntil: string | null;
+  readonly limitKind: "window" | "budget" | null;
+}
+
+export interface ZeroSubWindow {
+  readonly id: string;
+  readonly usedPct: number;
+  readonly resetsAt: string | null;
+  readonly minutes: number | null;
+}
+
+export interface ZeroSubReading {
+  readonly fetchedAt: string;
+  readonly cached: boolean;
+  readonly windows: readonly ZeroSubWindow[];
+}
+
+export interface ZeroSubSnapshot {
+  readonly accounts: readonly ZeroSubAccount[];
+  /** Which account each agent's live session was opened on. */
+  readonly sessions: Readonly<Record<string, string>>;
+  /** Agents whose Codex task carries on in another tab (ZeroSub continuation chains). */
+  readonly continuedElsewhere: ReadonlySet<string>;
+  readonly readings: Readonly<Record<string, ZeroSubReading>>;
+  /** ZeroSub's "Automatic switching" preference. */
+  readonly autoSwitch: boolean;
+}
+
+/** ZeroSub's ids for the CLI's own login (`server/state.ts` `MAIN_ACCOUNT_ID`). */
+const MAIN_ACCOUNT: Record<ZeroSubFamily, string> = { claude: "claude-main", codex: "codex-main" };
+
+/** ZeroSub reads usage at least every half hour for an account in use. Older is not "room". */
+export const FRESH_READING_MS = 30 * 60_000;
+
+const record = (value: unknown): Record<string, unknown> | null =>
+  typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+const text = (value: unknown): string | null => (typeof value === "string" && value !== "" ? value : null);
+const finite = (value: unknown): number | null => (typeof value === "number" && Number.isFinite(value) ? value : null);
+const family = (value: unknown): ZeroSubFamily | null => (value === "claude" || value === "codex" ? value : null);
+const time = (value: string | null | undefined): number | null => {
+  if (!value) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+};
+
+function parseAccount(value: unknown): ZeroSubAccount | null {
+  const raw = record(value);
+  const id = text(raw?.id);
+  const fam = family(raw?.family);
+  if (!raw || !id || !fam) return null;
+  const label = text(raw.label);
+  return {
+    id,
+    family: fam,
+    kind: raw.kind === "managed" ? "managed" : "main",
+    // A generated label is the email, or part of it: never repeat it.
+    label: raw.autoLabel === false && label !== null && !label.includes("@") ? label : null,
+    signedIn: raw.signedIn !== false,
+    disabled: raw.disabled === true,
+    limitedUntil: text(raw.limitedUntil),
+    limitKind: raw.limitKind === "window" || raw.limitKind === "budget" ? raw.limitKind : null,
+  };
+}
+
+function parseReading(value: unknown): ZeroSubReading | null {
+  const raw = record(value);
+  const fetchedAt = text(raw?.fetchedAt);
+  if (!raw || !fetchedAt || time(fetchedAt) === null || !Array.isArray(raw.windows)) return null;
+  const windows: ZeroSubWindow[] = [];
+  for (const entry of raw.windows) {
+    const window = record(entry);
+    const id = text(window?.id);
+    const usedPct = finite(window?.usedPercent);
+    if (!window || !id || usedPct === null) continue;
+    windows.push({ id, usedPct, resetsAt: text(window.resetsAt), minutes: finite(window.minutes) });
+  }
+  return { fetchedAt, cached: raw.cached === true, windows };
+}
+
+/**
+ * ZeroSub's registry (`state.json`), usage readings (`usage.json`) and preferences, as
+ * read from disk. Null when the registry is unusable; a missing usage file or
+ * preferences file only means "no readings" and "defaults".
+ */
+export function parseZeroSub(state: unknown, usage: unknown, preferences: unknown): ZeroSubSnapshot | null {
+  const raw = record(state);
+  if (!raw || !Array.isArray(raw.accounts)) return null;
+  const accounts = raw.accounts.map(parseAccount).filter((account): account is ZeroSubAccount => account !== null);
+  if (accounts.length === 0) return null;
+
+  const sessions: Record<string, string> = {};
+  for (const [agentId, entry] of Object.entries(record(raw.sessions) ?? {})) {
+    const accountId = text(record(entry)?.accountId);
+    if (accountId) sessions[agentId] = accountId;
+  }
+
+  // A Codex task that moved on to another tab: every member but the active one.
+  const continuedElsewhere = new Set<string>();
+  for (const entry of Object.values(record(raw.continuations) ?? {})) {
+    const chain = record(entry);
+    const active = text(chain?.activeAgentId);
+    if (!chain || !active) continue;
+    for (const member of Object.keys(record(chain.members) ?? {})) if (member !== active) continuedElsewhere.add(member);
+  }
+
+  const readings: Record<string, ZeroSubReading> = {};
+  for (const [accountId, entry] of Object.entries(record(usage) ?? {})) {
+    const reading = parseReading(entry);
+    if (reading) readings[accountId] = reading;
+  }
+
+  // Paseo stores plugin settings as `{ version, values }`; missing means ZeroSub's default (on).
+  const values = record(record(preferences)?.values);
+  return { accounts, sessions, continuedElsewhere, readings, autoSwitch: values?.autoSwitch !== false };
+}
+
+/** The ZeroSub family a Paseo provider belongs to, if ZeroSub manages it. */
+export function familyOf(provider: string): ZeroSubFamily | null {
+  return provider === "claude" || provider === "codex" ? provider : null;
+}
+
+/** The account an agent runs on: its live session's, else the CLI login, as ZeroSub decides. */
+export function accountOf(snapshot: ZeroSubSnapshot, agentId: string, provider: string): ZeroSubAccount | null {
+  const fam = familyOf(provider);
+  if (!fam) return null;
+  const id = snapshot.sessions[agentId] ?? MAIN_ACCOUNT[fam];
+  return snapshot.accounts.find((account) => account.id === id && account.family === fam) ?? null;
+}
+
+/**
+ * A ZeroSub window under the id Paseo uses for the same window, which is what the
+ * guard's `windowIds` and pause anchors name. Codex windows are told apart by length.
+ */
+export function paseoWindowId(fam: ZeroSubFamily, window: ZeroSubWindow): string {
+  if (fam === "claude") return window.id === "seven_day" ? "weekly" : window.id;
+  if (window.minutes !== null) return window.minutes <= 24 * 60 ? "session" : "weekly";
+  return window.id === "primary" ? "session" : window.id === "secondary" ? "weekly" : window.id;
+}
+
+const limited = (account: ZeroSubAccount, now: number) => {
+  const until = time(account.limitedUntil);
+  return until !== null && until > now;
+};
+
+/**
+ * One account's usage as a provider row the guard reads, or an unavailable row when
+ * there is no trustworthy reading. A limit the CLI reported is the freshest word on a
+ * window, so it shows as full until it lifts.
+ */
+export function accountUsage(snapshot: ZeroSubSnapshot, account: ZeroSubAccount, now: number): ProviderUsage {
+  const reading = snapshot.readings[account.id];
+  if (!reading || reading.windows.length === 0) return { providerId: account.family, status: "unavailable", fetchedAt: null, windows: [] };
+  const full = limited(account, now) && account.limitKind === "window";
+  const windows: UsageWindow[] = reading.windows.map((window) => ({
+    id: paseoWindowId(account.family, window),
+    usedPct: full ? Math.max(100, window.usedPct) : window.usedPct,
+    remainingPct: null,
+    resetsAt: window.resetsAt,
+  }));
+  return { providerId: account.family, status: "available", fetchedAt: reading.fetchedAt, windows };
+}
+
+/**
+ * Whether an account could take an agent right now: usable by ZeroSub's own rules
+ * (signed in, not set aside, no recorded limit) and, stricter than ZeroSub, with a
+ * fresh reading that shows room in every window. An account with no reading is not
+ * counted: deferring to a switch onto an account that may be just as full would only
+ * trade a pause for a failed turn.
+ */
+export function hasRoom(snapshot: ZeroSubSnapshot, account: ZeroSubAccount, thresholdPct: number, sessionWindowIds: readonly string[], now: number): boolean {
+  if (!account.signedIn || account.disabled || limited(account, now)) return false;
+  const reading = snapshot.readings[account.id];
+  const fetched = time(reading?.fetchedAt);
+  if (!reading || fetched === null || now - fetched > FRESH_READING_MS || reading.windows.length === 0) return false;
+  return reading.windows.every((window) => {
+    const limit = sessionWindowIds.includes(paseoWindowId(account.family, window)) ? thresholdPct : 100;
+    return window.usedPct < limit;
+  });
+}
+
+/** Other accounts of the agent's provider that ZeroSub could move it to now. */
+export function accountsWithRoom(snapshot: ZeroSubSnapshot, current: ZeroSubAccount, thresholdPct: number, sessionWindowIds: readonly string[], now: number): number {
+  return snapshot.accounts.filter((account) =>
+    account.family === current.family && account.id !== current.id && hasRoom(snapshot, account, thresholdPct, sessionWindowIds, now)).length;
+}
+
+/** The view Session Guard's engine asks, once per pass. */
+export interface AccountView {
+  /** Usage as the agent's own account sees it. */
+  usageFor(agentId: string, provider: string): Usage;
+  /** ZeroSub will move this agent to another account with room when its account hits the limit. */
+  failsOver(agentId: string, provider: string): boolean;
+  /** ZeroSub already carries this agent's Codex task on in another tab. */
+  continuedElsewhere(agentId: string): boolean;
+}
+
+export function accountView(
+  snapshot: ZeroSubSnapshot,
+  usage: Usage,
+  policy: { thresholdPct: number; windowIds: readonly string[] },
+  now: number,
+): AccountView {
+  return {
+    usageFor(agentId, provider) {
+      const account = accountOf(snapshot, agentId, provider);
+      // The CLI login is what Paseo and the recorder already measure, and measure more often.
+      if (!account || account.kind === "main") return usage;
+      const own = accountUsage(snapshot, account, now);
+      return { ...usage, providers: [...usage.providers.filter((p) => p.providerId !== provider), { ...own, providerId: provider }] };
+    },
+    failsOver(agentId, provider) {
+      if (!snapshot.autoSwitch) return false;
+      const account = accountOf(snapshot, agentId, provider);
+      return account !== null && accountsWithRoom(snapshot, account, policy.thresholdPct, policy.windowIds, now) > 0;
+    },
+    continuedElsewhere: (agentId) => snapshot.continuedElsewhere.has(agentId),
+  };
+}
+
+/** What `budget_status` says about the account an agent's numbers describe. */
+export interface BudgetAccount {
+  /** `main` is the CLI's own login, which the recorder measures; `managed` is one ZeroSub added. */
+  readonly kind: "main" | "managed";
+  readonly label: string | null;
+  /** Other accounts of the same provider ZeroSub could move the agent to now. */
+  readonly otherAccountsWithRoom: number;
+  readonly autoSwitch: boolean;
+  /** For a managed account: ZeroSub's reading of it, which replaces the recorder's numbers. */
+  readonly reading: { readonly fetchedAt: string; readonly windows: readonly { readonly id: string; readonly pct: number; readonly resetsAt: string | null }[] } | null;
+}
+
+/** The Claude account behind an agent's budget, as ZeroSub routes it. */
+export function budgetAccount(snapshot: ZeroSubSnapshot, agentId: string, now: number): BudgetAccount | null {
+  const account = accountOf(snapshot, agentId, "claude");
+  if (!account) return null;
+  const reading = account.kind === "managed" ? snapshot.readings[account.id] : undefined;
+  return {
+    kind: account.kind,
+    label: account.label,
+    otherAccountsWithRoom: accountsWithRoom(snapshot, account, 100, [], now),
+    autoSwitch: snapshot.autoSwitch,
+    reading: reading
+      ? { fetchedAt: reading.fetchedAt, windows: reading.windows.map((window) => ({ id: window.id, pct: window.usedPct, resetsAt: window.resetsAt })) }
+      : null,
+  };
+}

package/shared/smart-session.ts

@@ -48,9 +48,24 @@ export const RecorderStatusSchema = z.object({
  */
 export const budgetStatus = defineRpc({
   name: "smart-session.budget",
-  input: z.object({}),
+  /** The asking agent, so the answer can describe the account it runs on. Optional: panels omit it. */
+  input: z.object({ agentId: z.string().min(1).optional() }),
   output: z.object({
     windows: z.array(WindowStatusSchema),
+    /**
+     * Which Claude account `windows` describe, when ZeroSub runs agents on several. Absent
+     * without ZeroSub, or without an agent: then it is always the CLI's own login.
+     */
+    account: z
+      .object({
+        kind: z.enum(["main", "managed"]),
+        label: z.string().nullable(),
+        otherAccountsWithRoom: z.number(),
+        autoSwitch: z.boolean(),
+        /** When ZeroSub took the reading `windows` come from; null when they are the recorder's. */
+        readAt: z.string().nullable(),
+      })
+      .optional(),
     /** Finished session windows from the last 14 days, oldest first. */
     past: z.array(PastWindowSchema).optional(),
     recorder: RecorderStatusSchema,