paseo-smart-session 3.0.0 → 3.2.0

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": "3.0.0",
+  "version": "3.2.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {

package/paseo-plugin.json

@@ -9,6 +9,7 @@
     "docs/media/smart-session-pill.png",
     "docs/media/smart-session-chat.png",
     "docs/media/smart-session-guard.png",
+    "docs/media/smart-session-settings.png",
     "docs/media/smart-session-mobile.png"
   ],
   "requirements": {

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";
@@ -50,20 +52,21 @@ const PLUGIN_ID = "smart-session";
 const DEFERRED_RETRY_SECONDS = 15;
 
 const STANDALONE_MESSAGE =
-  "The standalone Session Guard plugin is enabled on this host, so Smart Session leaves session protection to it and pauses nothing. " +
+  "The standalone Session Guard plugin is enabled on this host, so Smart Session leaves pausing at the limit to it. " +
   "Disable or uninstall Session Guard to hand over; its per-session choices and waiting pauses carry over.";
 const HANDED_BACK_MESSAGE =
-  "The standalone Session Guard plugin was enabled while Smart Session was protecting this host, so Smart Session released its paused sessions and stopped. " +
+  "The standalone Session Guard plugin was enabled while Smart Session was pausing at the limit here, so Smart Session released its paused sessions and stopped. " +
   "Disable or uninstall Session Guard to hand back to Smart Session, or reload Session Guard to let it take over.";
 const LOCK_HELD_MESSAGE =
-  "Another process is already running Session Guard on this host, most likely a second Smart Session install. Nothing is paused from here until it stops.";
-const UNCHECKED_MESSAGE = "Session Guard could not check which plugins are installed, so it is not pausing anything yet. It will retry.";
-const OFF_MESSAGE = "Session Guard is off on this host. Turn it on in Smart Session's Session Guard settings.";
+  "Another process already pauses sessions at the limit on this host, most likely a second Smart Session install. Nothing is paused from here until it stops.";
+const OFF_MESSAGE = "Pause at the limit is off on this host. Turn it on in Smart Session settings.";
+const UNCHECKED_MESSAGE = "Smart Session could not check which plugins are installed, so it is not pausing anything yet. It will retry.";
 
 /** The daemon connection and process control, replaceable only by tests. */
 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";
@@ -126,7 +134,7 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
       release = await store.lock();
     } catch (error) {
       governor = error instanceof LockHeldError ? "deferred" : "error";
-      lockError = governor === "deferred" ? LOCK_HELD_MESSAGE : "Session Guard could not take its lock. Check its saved state and try again.";
+      lockError = governor === "deferred" ? LOCK_HELD_MESSAGE : "Pause at the limit could not take its lock. Check its saved state and try again.";
       return;
     }
     try {
@@ -135,7 +143,7 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
       lockError = null;
     } catch {
       governor = "error";
-      lockError = "Session Guard could not read its saved state. Restore state.json before continuing.";
+      lockError = "Pause at the limit could not read its saved state (session-guard/state.json). Restore it before continuing.";
       const unlock = release;
       release = null;
       await unlock?.();
@@ -189,7 +197,7 @@ export function contributeGuard(server: PluginServerContext, options: GuardDepen
       policy = await readPolicy();
       settingsError = null;
     } catch {
-      settingsError = "Session Guard settings are invalid. Reset them in Session Guard settings.";
+      settingsError = "The Pause at the limit settings are invalid. Reset them in Smart Session settings.";
     }
     if (!policy?.enabled && governor !== "active") {
       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

@@ -15,7 +15,7 @@ export function pausePresentation(pause: Pause, policy: Policy, now = Date.now()
     ? "Reset due · waiting for fresh usage"
     : `Reset ${new Date(reset).toLocaleString([], { dateStyle: "short", timeStyle: "short" })}`;
   const state = pause.phase === "attention" ? "Needs attention" : pause.phase === "pausing" ? "Pausing"
-    : pause.phase === "resuming" ? "Resuming" : pause.demo ? "Demo · resume when ready" : !policy.enabled ? "Guard off · continuation on hold"
+    : pause.phase === "resuming" ? "Resuming" : pause.demo ? "Demo · resume when ready" : !policy.enabled ? "Protection off · continuation on hold"
     : !policy.autoResume ? "Automatic resume off" : "Will resume automatically after reset";
   return {
     title: pause.title?.trim() || "Untitled session", state, resetLabel,
@@ -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."}`];
@@ -57,17 +62,20 @@ export function agentGuardSummary(status: {
 type GovernorView = { governor: "off" | "active" | "deferred" | "error"; standalone: boolean | null; error: string | null };
 
 /**
- * Why this plugin is not pausing anything, for the top of each Session Guard view.
- * Null while it is the host's governor.
+ * Why this plugin is not pausing anything, for the Protection part of each view.
+ * Null while it is the host's governor. The standalone plugin keeps its own name:
+ * it is a different plugin the person installed, not a part of this one.
  */
 export function governorNotice(status: GovernorView): { title: string; hint: string } | null {
   if (status.governor === "active") return null;
-  if (status.governor === "off") return { title: "Session Guard is off", hint: "Nothing is paused from Smart Session. Turn it on in Session Guard settings to pause sessions at the provider's session limit." };
+  if (status.governor === "off") return { title: "Pause at the limit is off", hint: "Nothing pauses at the session limit. Turn it on in Smart Session settings." };
   if (status.governor === "deferred" && status.standalone !== false) {
-    return { title: "The standalone Session Guard plugin is in charge", hint: status.error ?? "Disable or uninstall Session Guard to hand over; its per-session choices and waiting pauses carry over." };
+    // One calm line; the server's longer story only adds what needs a look.
+    const stuck = status.error?.includes("could not be released") ? " Some paused sessions could not be released; check them." : "";
+    return { title: "The standalone Session Guard plugin handles pausing here", hint: `Disable or uninstall it to hand back; its per-session choices and waiting pauses carry over.${stuck}` };
   }
-  if (status.governor === "deferred") return { title: "Another process is running Session Guard", hint: status.error ?? "Nothing is paused from here until it stops." };
-  return { title: "Session Guard is not running", hint: status.error ?? "It will retry automatically." };
+  if (status.governor === "deferred") return { title: "Another process handles pausing here", hint: status.error ?? "Nothing is paused from here until it stops." };
+  return { title: "Pause at the limit isn't running", hint: status.error ?? "It will retry automatically." };
 }
 
 /**
@@ -78,8 +86,60 @@ export function governorNotice(status: GovernorView): { title: string; hint: str
  */
 export function pauseOwnerNote(status: GovernorView): string | null {
   if (status.governor === "active") return null;
-  if (status.governor === "off") return "Saved by the standalone Session Guard plugin. Smart Session takes it over once Session Guard is on here and the standalone plugin is disabled or uninstalled.";
-  if (status.governor === "deferred" && status.standalone !== false) return "Managed by the standalone Session Guard plugin; change it there.";
-  if (status.governor === "deferred") return "Managed by another Session Guard process; it can be changed only from there.";
-  return "Session Guard is not running here, so this pause cannot be changed until it recovers.";
+  if (status.governor === "off") return "Saved by the standalone Session Guard plugin. Smart Session takes it over once Pause at the limit is on here and that plugin is disabled or uninstalled.";
+  if (status.governor === "deferred" && status.standalone !== false) return "Handled by the standalone Session Guard plugin; change it there.";
+  if (status.governor === "deferred") return "Handled by another process on this host; change it there.";
+  return "Pause at the limit isn't running here, so this pause can't be changed until it recovers.";
 }
+
+/**
+ * A paused session's composer pill: the loud state, so the label is the moment it
+ * comes back. A clock rather than a countdown, so the label changes once instead of
+ * every minute (each change is a registration update).
+ */
+export function pausePill(pause: Pause, policy: Policy, now = Date.now(), clock: (iso: string) => string = (iso) => new Date(iso).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })) {
+  const reset = timestamp(pause.anchorResetsAt);
+  // The title is also the phone sheet's title: one short sentence, the detail is in the sheet.
+  if (pause.phase === "attention") return { label: "Check session", title: "Paused, then something changed · check it", tone: "danger" as const };
+  if (pause.phase === "pausing") return { label: "Pausing…", title: "Pausing at the session limit", tone: "warning" as const };
+  if (pause.phase === "resuming") return { label: "Resuming…", title: "The window reset · continuing now", tone: "warning" as const };
+  if (pause.demo) return { label: "Paused · test", title: "Test pause · waits for you", tone: "warning" as const };
+  if (!policy.enabled) return { label: "Paused · on hold", title: "Paused · on hold while Pause at the limit is off", tone: "warning" as const };
+  if (reset === null) return { label: "Paused", title: "Paused at the limit · reset time not reported yet", tone: "warning" as const };
+  const at = clock(pause.anchorResetsAt!);
+  if (reset <= now) return { label: "Paused · reset due", title: `Paused at the limit · reset was ${at}`, tone: "warning" as const };
+  return policy.autoResume
+    ? { label: `Resumes ${at}`, title: `Paused at the limit · resumes ${at}`, tone: "warning" as const }
+    : { label: `Paused · resets ${at}`, title: `Paused at the limit · resets ${at}, continue by hand`, tone: "warning" as const };
+}
+
+/**
+ * The lead for a set of pending pauses: when they come back, or that one needs a
+ * look. Null when nothing is paused. `shared` is the one reset they all wait for,
+ * when they share it, so rows only repeat a time that differs.
+ */
+export function pausedLead(pending: readonly Pause[], autoResume: boolean, now: number, clock: (ms: number) => string): { title: string; tone: "warning" | "danger"; shared: number | null; next: number | null } | null {
+  if (pending.length === 0) return null;
+  const waiting = pending.filter((p) => p.phase !== "attention");
+  const stuck = pending.length - waiting.length;
+  const resets = waiting.map((p) => timestamp(p.anchorResetsAt)).filter((v): v is number => v !== null && v > now).sort((a, b) => a - b);
+  const shared = resets.length === waiting.length && resets.length > 0 && resets[resets.length - 1]! - resets[0]! < 60_000 ? resets[0]! : null;
+  const n = (count: number, one: string, many: string) => `${count} ${count === 1 ? one : many}`;
+  const tone = stuck > 0 ? "danger" as const : "warning" as const;
+  const next = resets[0] ?? null;
+  if (waiting.length === 0) return { title: `${n(stuck, "paused session needs", "paused sessions need")} a look`, tone, shared, next };
+  const look = stuck > 0 ? ` · ${stuck} ${stuck === 1 ? "needs" : "need"} a look` : "";
+  if (shared !== null) return { title: (autoResume ? `${n(waiting.length, "session resumes", "sessions resume")} at ${clock(shared)}` : `${n(waiting.length, "session waits", "sessions wait")} for the ${clock(shared)} reset`) + look, tone, shared, next };
+  if (next !== null) return { title: `${n(waiting.length, "session", "sessions")} paused · next ${autoResume ? "resumes" : "reset"} at ${clock(next)}${look}`, tone, shared, next };
+  return { title: `${n(waiting.length, "session waits", "sessions wait")} for a fresh reading${look}`, tone, shared, next };
+}
+
+/**
+ * The one action set for a waiting pause, wherever it shows: the chat card, the
+ * pill's popover and the overview's list. Same words, same order, same hint.
+ */
+export const PAUSE_ACTIONS = {
+  resume: { label: "Resume now", busy: "Resuming…", icon: "Play", hint: "Continues before the reset and stops this session pausing at the limit. The provider may still refuse work until the reset." },
+  dismiss: { label: "Dismiss pause", busy: "Dismissing…", hint: "Lets the session go without sending a message and stops it pausing at the limit." },
+  note: "Resume now stops this session pausing at the limit · Dismiss sends nothing",
+} as const;

package/shared/guard/timeline.ts

@@ -17,15 +17,15 @@ export function timelinePresentation(data: TimelineData) {
   if (data.event === "released" && data.dismissed) return { title: "Pause dismissed", icon: "ShieldOff", tone: "muted" as const,
     detail: "No message was sent. Protection is off for this session." + (data.native ? " Existing workers were released; their current work may continue." : "") };
   if (data.event === "resumed") return { title: "Session resumed", icon: "Play", tone: "success" as const,
-    detail: data.manualResume ? "Resumed by you. Protection is off for this session; restore it from the composer pill when ready."
+    detail: data.manualResume ? "Resumed by you. Pause at the limit is off for this session; turn it back on from the composer pill."
       : data.native ? "Session and native subagents resumed after the quota reset." : "A continuation was sent after the quota reset." };
   if (data.event === "released") return { title: data.native ? "Session released" : "Automatic resume cancelled", icon: "ShieldOff", tone: "muted" as const,
     detail: data.note ?? (data.native ? "Suspended workers were released." : "Continue this session manually when ready.") };
   if (data.event === "attention") return { title: "Pause needs attention", icon: "TriangleAlert", tone: "danger" as const,
     detail: data.note ?? "Check this session before continuing manually." };
   if (data.event === "recovery") return { title: "Waiting after Paseo restart", icon: "Pause", tone: "warning" as const,
-    detail: `The original workers ended, but this pause is saved. ${data.autoResume ? "Session Guard will continue this conversation after the quota resets." : "Automatic resume is off; continue manually when ready."} Your workspace and conversation remain in place.` };
-  if (data.demo) return { title: "Session Guard demo paused", icon: "Pause", tone: "warning" as const,
+    detail: `The original workers ended, but this pause is saved. ${data.autoResume ? "Smart Session continues this conversation after the window resets." : "Automatic resume is off; continue by hand when ready."} Your workspace and conversation remain in place.` };
+  if (data.demo) return { title: "Test pause", icon: "Pause", tone: "warning" as const,
     detail: "This empty test session is suspended so you can try Resume now. No provider quota was changed, and no task was sent. It will wait for you to resume it." };
   const reset = data.resetAt ? Date.parse(data.resetAt) : NaN;
   const resetLabel = Number.isFinite(reset) ? `Expected reset ${new Date(reset).toLocaleString([], { dateStyle: "short", timeStyle: "short" })}.` : "The provider has not reported a reset time yet.";

package/shared/guard/timing.ts

@@ -0,0 +1,37 @@
+import { PolicySchema, type Policy } from "./policy.ts";
+
+/** The limit-timing fields, as typed. Nothing is saved until every one parses. */
+export type Timing = { thresholdPct: string; pollSeconds: string; resetGraceSeconds: string; resumeSpacingSeconds: string; continuation: string; providerIds: string; windowIds: string };
+const NUMERIC = ["thresholdPct", "pollSeconds", "resetGraceSeconds", "resumeSpacingSeconds"] as const;
+const LISTS = ["providerIds", "windowIds"] as const;
+
+export function timingOf(policy: Policy): Timing {
+  return {
+    thresholdPct: String(policy.thresholdPct), pollSeconds: String(policy.pollSeconds), resetGraceSeconds: String(policy.resetGraceSeconds),
+    resumeSpacingSeconds: String(policy.resumeSpacingSeconds), continuation: policy.continuation, providerIds: policy.providerIds.join(", "), windowIds: policy.windowIds.join(", "),
+  };
+}
+const list = (value: string) => [...new Set(value.split(",").map((s) => s.trim()).filter(Boolean))];
+
+/** Each field checked on its own, so the message sits under the field it is about. */
+export function checkTiming(draft: Timing): { values: Partial<Policy>; errors: Partial<Record<keyof Timing, string>> } {
+  const values: Record<string, unknown> = {};
+  const errors: Partial<Record<keyof Timing, string>> = {};
+  const range: Record<(typeof NUMERIC)[number], string> = {
+    thresholdPct: "Enter a number from 1 to 100.", pollSeconds: "Enter whole seconds from 5 to 300.",
+    resetGraceSeconds: "Enter whole seconds from 0 to 600.", resumeSpacingSeconds: "Enter whole seconds from 0 to 300.",
+  };
+  for (const key of NUMERIC) {
+    const raw = draft[key].trim();
+    const parsed = PolicySchema.shape[key].safeParse(raw === "" ? NaN : Number(raw));
+    if (parsed.success) values[key] = parsed.data; else errors[key] = range[key];
+  }
+  const continuation = PolicySchema.shape.continuation.safeParse(draft.continuation);
+  if (continuation.success) values.continuation = continuation.data; else errors.continuation = "Write a message of 1 to 8,000 characters.";
+  for (const key of LISTS) {
+    const parsed = PolicySchema.shape[key].safeParse(list(draft[key]));
+    if (parsed.success) values[key] = parsed.data; else errors[key] = "Name at least one window, e.g. five_hour.";
+  }
+  return { values: values as Partial<Policy>, errors };
+}
+