paseo-smart-session 2.0.0 → 2.2.0

package/shared/forecast.ts

@@ -0,0 +1,233 @@
+/**
+ * Turning a usage reading into the moment it matters.
+ *
+ * Plain functions over the budget and context RPC outputs, shared by the overview,
+ * the pill and the checks, so every view says the same thing about one window: when
+ * it resets, whether it runs out first at this pace, and how much is left per hour.
+ */
+
+import { formatClock, formatDuration, windowLabel } from "./format.ts";
+
+export type Tone = "default" | "warning" | "danger";
+
+const HOUR = 3_600_000;
+const FIVE_HOURS = 5 * HOUR;
+const WEEK = 7 * 24 * HOUR;
+
+/** A window's nominal length, or null for a cap whose length is not known. */
+export function windowLength(id: string): number | null {
+  if (id === "five_hour") return FIVE_HOURS;
+  if (id === "seven_day" || id.startsWith("weekly")) return WEEK;
+  return null;
+}
+
+export interface WindowReading {
+  readonly id: string;
+  readonly pct: number;
+  readonly resetsAt: string | null;
+  /** Percentage points per hour over the recent past; null when it cannot be measured. */
+  readonly burnPctPerHour: number | null;
+}
+
+export interface WindowForecast {
+  readonly id: string;
+  readonly label: string;
+  readonly pct: number;
+  readonly resetsAt: string | null;
+  /** The window's start, when its length is known. */
+  readonly startAt: string | null;
+  /** How far through the window we are, 0–1: where an even pace would put the meter. */
+  readonly elapsed: number | null;
+  /** The rate the forecast uses: the last half hour for the session, the window's average for a week. */
+  readonly ratePerHour: number | null;
+  /** Where the window ends up at the reset at that rate, uncapped. */
+  readonly atResetPct: number | null;
+  /** When it reaches 100% at that rate, if that comes before the reset. */
+  readonly runsOutAt: string | null;
+  /** How long before the reset it runs out. */
+  readonly shortMs: number | null;
+  /** Percentage points per hour that would last exactly until the reset. */
+  readonly budgetPerHour: number | null;
+  readonly state: "full" | "short" | "ok" | "idle" | "unknown";
+  readonly tone: Tone;
+}
+
+/** Rates below this are a window nobody is using right now. */
+const IDLE_RATE = 0.2;
+
+export function forecastWindow(window: WindowReading, now = Date.now()): WindowForecast {
+  const length = windowLength(window.id);
+  const reset = window.resetsAt === null ? NaN : Date.parse(window.resetsAt);
+  const known = Number.isFinite(reset) && reset > now;
+  const start = known && length !== null ? reset - length : null;
+  const elapsed = start === null || length === null ? null : Math.min(1, Math.max(0, (now - start) / length));
+  const hoursLeft = known ? (reset - now) / HOUR : null;
+  const base = {
+    id: window.id,
+    label: windowLabel(window.id),
+    pct: window.pct,
+    resetsAt: known ? new Date(reset).toISOString() : window.resetsAt,
+    startAt: start === null ? null : new Date(start).toISOString(),
+    elapsed,
+  };
+  const budgetPerHour = hoursLeft === null || hoursLeft <= 0 ? null : Math.max(0, 100 - window.pct) / hoursLeft;
+  const none = { ratePerHour: null, atResetPct: null, runsOutAt: null, shortMs: null, budgetPerHour };
+
+  if (window.pct >= 99.5) return { ...base, ...none, state: "full", tone: "danger" };
+  if (hoursLeft === null) return { ...base, ...none, state: "unknown", tone: window.pct >= 90 ? "warning" : "default" };
+
+  // A week is bursty: half an hour of work extrapolated over four days says nothing.
+  // Its pace is the window's own average so far.
+  const elapsedHours = elapsed === null || length === null ? null : (elapsed * length) / HOUR;
+  const rate = length !== null && length > FIVE_HOURS
+    ? (elapsedHours !== null && elapsedHours >= 1 ? window.pct / elapsedHours : null)
+    : window.burnPctPerHour;
+  if (rate === null || !Number.isFinite(rate) || rate < IDLE_RATE) {
+    return { ...base, ...none, ratePerHour: rate === null ? null : Math.max(0, rate), state: "idle", tone: window.pct >= 90 ? "warning" : "default" };
+  }
+  const atResetPct = window.pct + rate * hoursLeft;
+  if (atResetPct < 100) {
+    return { ...base, ratePerHour: rate, atResetPct, runsOutAt: null, shortMs: null, budgetPerHour, state: "ok", tone: window.pct >= 90 ? "warning" : "default" };
+  }
+  const runsOut = now + ((100 - window.pct) / rate) * HOUR;
+  const shortMs = reset - runsOut;
+  const soon = runsOut - now <= 30 * 60_000 || window.pct >= 95;
+  return {
+    ...base, ratePerHour: rate, atResetPct, runsOutAt: new Date(runsOut).toISOString(), shortMs, budgetPerHour,
+    state: "short", tone: soon ? "danger" : "warning",
+  };
+}
+
+const rounded = (value: number) => (value >= 10 ? Math.round(value) : Math.round(value * 10) / 10);
+const until = (iso: string, now: number) => formatDuration(Date.parse(iso) - now);
+
+/** A clock within the next day, else a weekday and clock: "9:21 PM", "Sat 11:00 PM". */
+export function formatMoment(iso: string, now = Date.now(), hour12?: boolean): string {
+  const at = Date.parse(iso);
+  const clock = formatClock(iso, hour12);
+  const sameDay = new Date(at).toDateString() === new Date(now).toDateString();
+  if (sameDay || (at > now && at - now < 12 * HOUR)) return clock;
+  try {
+    return `${new Intl.DateTimeFormat(undefined, { weekday: "short" }).format(new Date(at))} ${clock}`;
+  } catch {
+    return clock;
+  }
+}
+
+/** "Resets 9:21 PM · in 1h 57m". */
+export function resetLine(f: WindowForecast, now = Date.now(), hour12?: boolean): string {
+  if (f.resetsAt === null) return "Reset time not reported";
+  const at = Date.parse(f.resetsAt);
+  if (!Number.isFinite(at)) return "Reset time not reported";
+  // Past its reset but no newer reading yet: name the moment rather than "due".
+  if (at <= now) return `Reset was ${formatMoment(f.resetsAt, now, hour12)}`;
+  return `Resets ${formatMoment(f.resetsAt, now, hour12)} · in ${until(f.resetsAt, now)}`;
+}
+
+/** The short pace phrase on a meter row: "runs out ~8:47 PM", "on pace for ~88%". */
+export function paceLine(f: WindowForecast, now = Date.now(), hour12?: boolean): string {
+  switch (f.state) {
+    case "full": return "Limit reached";
+    case "short": return `Runs out ~${formatMoment(f.runsOutAt!, now, hour12)} at ${rounded(f.ratePerHour!)}%/h`;
+    case "ok": return `On pace for ~${Math.round(f.atResetPct!)}% by the reset`;
+    case "idle": return f.ratePerHour === null ? "No pace yet" : "Not in use right now";
+    default: return "";
+  }
+}
+
+/** When a window runs short: the pace that would still last until the reset. */
+export function budgetLine(f: WindowForecast): string | null {
+  if (f.budgetPerHour === null || f.state !== "short") return null;
+  return `${rounded(f.budgetPerHour)}%/h would last until the reset`;
+}
+
+/** The overview's status headline and the sentence under it. */
+export function headline(f: WindowForecast | null, now = Date.now(), hour12?: boolean): { title: string; detail: string; tone: Tone } {
+  if (f === null) return { title: "No plan usage recorded yet", detail: "The recorder samples every minute while Paseo runs.", tone: "default" };
+  const name = f.id === "five_hour" ? "Session" : f.label;
+  const pct = `${Math.round(f.pct)}% used`;
+  switch (f.state) {
+    case "full": {
+      const at = f.resetsAt === null ? NaN : Date.parse(f.resetsAt);
+      const detail = !Number.isFinite(at) ? "Waiting for the provider to report the reset"
+        : at <= now ? `${resetLine(f, now, hour12)} · waiting for the provider to report the new window`
+          : `Back at the ${formatMoment(f.resetsAt!, now, hour12)} reset · in ${until(f.resetsAt!, now)}`;
+      return { title: `${name} limit reached`, detail, tone: "danger" };
+    }
+    case "short":
+      return {
+        title: `${name} runs out around ${formatMoment(f.runsOutAt!, now, hour12)}`,
+        detail: `${formatDuration(f.shortMs!)} before the ${formatMoment(f.resetsAt!, now, hour12)} reset · ${pct} · ${rounded(f.ratePerHour!)}%/h`,
+        tone: f.tone,
+      };
+    case "ok":
+      return { title: `${name} lasts until the ${formatMoment(f.resetsAt!, now, hour12)} reset`, detail: `${pct} · on pace for ~${Math.round(f.atResetPct!)}%`, tone: f.tone };
+    case "idle":
+      return {
+        title: `${name} at ${Math.round(f.pct)}%`,
+        detail: f.resetsAt === null ? "Nothing used in the last half hour" : `Nothing used in the last half hour · ${resetLine(f, now, hour12).replace(/^R/, "r")}`,
+        tone: f.tone,
+      };
+    default:
+      return { title: `${name} at ${Math.round(f.pct)}%`, detail: "The provider has not reported a reset time", tone: f.tone };
+  }
+}
+
+/** The window the overview leads with: the session, else whichever is fullest. */
+export function leadWindow(windows: readonly WindowForecast[]): WindowForecast | null {
+  return windows.find((window) => window.id === "five_hour") ?? [...windows].sort((a, b) => b.pct - a.pct)[0] ?? null;
+}
+
+export interface ContextReading {
+  readonly usedTokens: number;
+  readonly maxTokens: number;
+  readonly compactAtPct: number;
+  readonly growthTokensPerHour?: number | null;
+}
+
+export interface ContextOutlook {
+  readonly pct: number;
+  readonly compactAt: number;
+  /** Tokens at the compact line. */
+  readonly compactTokens: number;
+  readonly past: boolean;
+  /** Time until the compact line at the measured growth; null when not growing or already past. */
+  readonly untilCompactMs: number | null;
+  readonly tone: Tone;
+}
+
+export function contextOutlook(reading: ContextReading): ContextOutlook {
+  const pct = reading.maxTokens > 0 ? (reading.usedTokens / reading.maxTokens) * 100 : 0;
+  const compactTokens = Math.round((reading.compactAtPct / 100) * reading.maxTokens);
+  const past = pct >= reading.compactAtPct;
+  const growth = reading.growthTokensPerHour ?? null;
+  const untilCompactMs = past || growth === null || growth <= 0 ? null : ((compactTokens - reading.usedTokens) / growth) * HOUR;
+  return { pct, compactAt: reading.compactAtPct, compactTokens, past, untilCompactMs, tone: pct >= 90 ? "danger" : past ? "warning" : "default" };
+}
+
+/**
+ * The context ring: a faint full track, an arc for the share of the window used, and a
+ * tick across the ring at the compact line. Inline SVG in the surface's own colour, so
+ * the host `Icon` can draw it anywhere a Lucide glyph fits. Quantized to 1/48 so a
+ * ticking view rarely redraws.
+ */
+export function contextRing(fraction: number, mark: number | null, track = 0.28): string {
+  const steps = 48;
+  const f = Math.round(Math.min(1, Math.max(0, fraction)) * steps) / steps;
+  const r = 8.5;
+  const c = 12;
+  const point = (t: number, radius: number) => [(c + radius * Math.sin(t * 2 * Math.PI)).toFixed(2), (c - radius * Math.cos(t * 2 * Math.PI)).toFixed(2)];
+  let arc = "";
+  if (f >= 1) arc = `<circle cx="${c}" cy="${c}" r="${r}"/>`;
+  else if (f > 0) {
+    const [x, y] = point(f, r);
+    arc = `<path d="M${c} ${c - r}A${r} ${r} 0 ${f > 0.5 ? 1 : 0} 1 ${x} ${y}"/>`;
+  }
+  let tick = "";
+  if (mark !== null && mark > 0 && mark < 1) {
+    const [x1, y1] = point(mark, r - 3.6);
+    const [x2, y2] = point(mark, r + 3.2);
+    tick = `<path d="M${x1} ${y1}L${x2} ${y2}" stroke-width="1.8"/>`;
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round"><circle cx="${c}" cy="${c}" r="${r}" stroke-opacity="${track}"/>${arc}${tick}</svg>`;
+}

package/shared/format.ts

@@ -21,6 +21,42 @@ export function formatRelative(iso: string | null, now = Date.now()): string {
   return ms >= now ? `in ${formatDuration(ms - now)}` : `${formatDuration(now - ms)} ago`;
 }
 
+let cachedHour12: boolean | null = null;
+
+/** Whether this device writes times as "8:50 PM" rather than "20:50". */
+export function uses12HourClock(): boolean {
+  if (cachedHour12 !== null) return cachedHour12;
+  try {
+    const parts = new Intl.DateTimeFormat(undefined, { hour: "numeric" }).formatToParts(new Date(2020, 0, 1, 13, 0, 0));
+    cachedHour12 = parts.some((part) => part.type === "dayPeriod");
+  } catch {
+    cachedHour12 = false;
+  }
+  return cachedHour12;
+}
+
+/** Local wall-clock time in the device's own convention: "20:50" or "8:50 PM". */
+export function formatClock(iso: string | null, hour12: boolean = uses12HourClock()): string {
+  if (iso === null) return "—";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "—";
+  const hours = date.getHours();
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  if (!hour12) return `${String(hours).padStart(2, "0")}:${minutes}`;
+  // A non-breaking space, so "AM" never wraps onto a line of its own.
+  return `${hours % 12 === 0 ? 12 : hours % 12}:${minutes}\u00a0${hours < 12 ? "AM" : "PM"}`;
+}
+
+/** "Oct 22" — a short local date. */
+export function formatDay(iso: string): string {
+  const date = new Date(iso);
+  try {
+    return new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric" }).format(date);
+  } catch {
+    return iso.slice(5, 10);
+  }
+}
+
 /** "261.7k" — token counts, which are always large and never need units. */
 export function formatTokens(count: number): string {
   if (count < 1000) return String(count);
@@ -28,9 +64,19 @@ export function formatTokens(count: number): string {
   return `${(count / 1_000_000).toFixed(2)}M`;
 }
 
+/** "1M", "200k", "88.6M" — a window size or a total, without trailing zeros. */
+export function formatCompactTokens(count: number): string {
+  if (count >= 1_000_000) {
+    const value = count / 1_000_000;
+    return `${value >= 10 ? Math.round(value) : Number(value.toFixed(1))}M`;
+  }
+  if (count >= 1000) return `${Math.round(count / 1000)}k`;
+  return String(Math.round(count));
+}
+
 /** A window id turned into something worth putting on a row. */
 export function windowLabel(id: string): string {
-  if (id === "five_hour") return "Session (5h)";
+  if (id === "five_hour") return "Session · 5h";
   if (id === "seven_day") return "Week";
   const scoped = /^weekly_(model|surface):(.+)$/.exec(id);
   if (scoped !== null) {

package/shared/governor.ts

@@ -10,6 +10,7 @@
 
 import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
+import { ThresholdsSchema } from "./smart-session.ts";
 
 export const CompactionStateSchema = z.enum(["pending", "sending", "sent", "failed", "cancelled"]);
 
@@ -93,6 +94,8 @@ export const EnrolmentStateSchema = z.object({
   enabled: z.boolean(),
   /** Only agents with a state file or an explicit answer. Anyone absent is off. */
   agents: z.array(AgentEnrolmentSchema),
+  /** The compact bands, so a pill can mark where its session will be asked. Optional for older daemons. */
+  thresholds: ThresholdsSchema.optional(),
 });
 export type EnrolmentState = z.infer<typeof EnrolmentStateSchema>;
 

package/shared/guard/contracts.ts

@@ -0,0 +1,65 @@
+import { defineRpc, defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { PauseSchema, PolicySchema } from "./policy.ts";
+
+/** Host-scoped, so every client of this daemon sees one Session Guard policy. */
+export const guardPreferences = defineSettings({ id: "session-guard", scope: "host", version: 1, schema: PolicySchema });
+
+/**
+ * Who is running Session Guard on this host.
+ *
+ * - `off`: the feature is disabled here, and this plugin holds no lock.
+ * - `active`: this plugin is the host's one governor.
+ * - `deferred`: the standalone `paseo-session-guard` plugin is enabled, or another live
+ *   process holds the governor lock. Nothing is paused from here until that changes.
+ * - `error`: the saved state or the lock could not be read.
+ */
+export const GovernorSchema = z.enum(["off", "active", "deferred", "error"]);
+export type Governor = z.infer<typeof GovernorSchema>;
+
+const ProviderSchema = z.object({ providerId: z.string(), usedPct: z.number().nullable(), resetsAt: z.string().nullable() });
+
+export const statusRpc = defineRpc({
+  name: "smart-session.guard.status", input: z.object({}),
+  output: z.object({
+    governor: GovernorSchema,
+    /** Whether the standalone plugin is configured and enabled; null when unknown or not checked. */
+    standalone: z.boolean().nullable(),
+    checkedAt: z.string().nullable(), error: z.string().nullable(),
+    pauses: z.array(PauseSchema), overrides: z.record(z.string(), z.boolean()),
+    policy: PolicySchema,
+    providers: z.array(ProviderSchema),
+  }),
+});
+/** One agent's view, for the agent itself: its own protection and pauses, nobody else's. */
+export const agentStatusRpc = defineRpc({
+  name: "smart-session.guard.agent", input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({
+    governor: GovernorSchema,
+    enabled: z.boolean(), protected: z.boolean(), override: z.boolean().nullable(),
+    thresholdPct: z.number(), autoResume: z.boolean(),
+    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()),
+  }),
+});
+export const setProtectionRpc = defineRpc({
+  name: "smart-session.guard.protection", input: z.object({ agentId: z.string().min(1), enabled: z.boolean().nullable() }),
+  output: z.object({ ok: z.boolean() }),
+});
+export const cancelResumeRpc = defineRpc({
+  name: "smart-session.guard.cancel", input: z.object({ agentId: z.string().min(1) }), output: z.object({ ok: z.boolean() }),
+});
+export const resumeNowRpc = defineRpc({
+  name: "smart-session.guard.resume-now", input: z.object({ agentId: z.string().min(1), pauseId: z.string().min(1) }),
+  output: z.object({ ok: z.boolean() }),
+});
+export const dismissPauseRpc = defineRpc({
+  name: "smart-session.guard.dismiss-pause", input: z.object({ agentId: z.string().min(1), pauseId: z.string().min(1) }),
+  output: z.object({ ok: z.boolean() }),
+});
+export const demoPauseRpc = defineRpc({
+  name: "smart-session.guard.demo-pause", input: z.object({ agentId: z.string().min(1) }), output: z.object({ ok: z.boolean() }),
+});
+// Obtains the host-owned IPC API; network clients cannot impersonate plugins.
+export const runtimeRpc = defineRpc({ name: "smart-session.guard.runtime", input: z.object({}), output: z.object({ ok: z.boolean() }) });

package/shared/guard/policy.ts

@@ -0,0 +1,128 @@
+/**
+ * Session Guard: pausing work at a provider's session limit and continuing it after
+ * the window resets.
+ *
+ * This module, and the rest of `shared/guard/`, `server/guard/` and `client/guard/`,
+ * was folded in from the standalone `paseo-session-guard` plugin. The pause record and
+ * state file are deliberately unchanged (see `server/guard/store.ts`): during the
+ * transition both plugins can be installed on one host, and sharing one state file and
+ * one governor lock is what guarantees a session is never paused twice.
+ */
+import { z } from "zod";
+import { NotificationSchema } from "./timeline.ts";
+
+export const PolicySchema = z.object({
+  /**
+   * Off by default, unlike the standalone plugin. Pausing a running agent is a much
+   * bigger thing to do unasked than drawing a chart, and an existing Smart Session
+   * install must not start freezing processes on upgrade.
+   */
+  enabled: z.boolean().default(false),
+  protectByDefault: z.boolean().default(true),
+  thresholdPct: z.number().min(1).max(100).default(100),
+  pollSeconds: z.number().int().min(5).max(300).default(15),
+  resetGraceSeconds: z.number().int().min(0).max(600).default(30),
+  resumeSpacingSeconds: z.number().int().min(0).max(300).default(5),
+  autoResume: z.boolean().default(true),
+  includeNativeSubagents: z.boolean().default(true),
+  workspaceLabels: z.boolean().default(true),
+  providerIds: z.array(z.string().min(1)).default([]),
+  windowIds: z.array(z.string().min(1)).min(1).default(["five_hour", "session"]),
+  continuation: z.string().trim().min(1).max(8000).default(
+    "Your previous turn was paused because the provider's session usage limit was reached. " +
+    "The usage window has now reset. Continue the unfinished task from where you left off, " +
+    "using this conversation and the current workspace state. Check any interrupted operation " +
+    "before retrying it. If the task is already complete, do not repeat it.",
+  ),
+});
+export type Policy = z.infer<typeof PolicySchema>;
+
+export const PauseSchema = z.object({
+  id: z.string(), agentId: z.string(), workspaceId: z.string().optional(), provider: z.string(), title: z.string().nullable(),
+  windowId: z.string(), anchorResetsAt: z.string().nullable(),
+  pausedAt: z.string(), lastUserMessageAt: z.string().nullable(), turnId: z.string().nullable(),
+  phase: z.enum(["pausing", "waiting", "resuming", "resumed", "cancelled", "attention"]),
+  note: z.string().nullable(), settledAt: z.string().nullable(),
+  wasQuotaFailure: z.boolean().default(false),
+  resumedInPlace: z.boolean().optional(),
+  manualResume: z.boolean().optional(),
+  dismissed: z.boolean().optional(),
+  restartRecovery: z.boolean().optional(),
+  daemonIdentity: z.string().optional(),
+  closedOnRestart: z.boolean().optional(),
+  releasedForUnload: z.boolean().optional(),
+  demo: z.boolean().optional(),
+  stoppedByUser: z.boolean().optional(),
+  notifications: z.array(NotificationSchema).optional(),
+  suspension: z.object({
+    rootPid: z.number().int().positive(),
+    processes: z.array(z.object({ pid: z.number().int().positive(), startTime: z.string() })),
+  }).optional(),
+});
+export type Pause = z.infer<typeof PauseSchema>;
+export const StateSchema = z.object({
+  version: z.literal(1),
+  overrides: z.record(z.string(), z.boolean()),
+  pauses: z.array(PauseSchema),
+  labelledWorkspaces: z.array(z.string()).optional(),
+  workspaceLabelName: z.string().optional(),
+});
+export type State = z.infer<typeof StateSchema>;
+export const isPending = (pause: Pause) => ["pausing", "waiting", "resuming", "attention"].includes(pause.phase);
+export const protects = (policy: Policy, overrides: State["overrides"], id: string) => overrides[id] ?? policy.protectByDefault;
+
+export interface Agent {
+  id: string; provider: string; status: string; title?: string | null;
+  workspaceId?: string; lastUserMessageAt?: string | null; archivedAt?: string | null;
+  activeTurn?: { turnId: string } | null;
+  pendingPermissions?: readonly unknown[];
+  labels?: Record<string, string>;
+  lastError?: string;
+}
+export interface UsageWindow {
+  id: string; usedPct?: number | null; remainingPct?: number | null; resetsAt?: string | null;
+}
+export interface ProviderUsage {
+  providerId: string; status: string; fetchedAt?: string | null; windows: readonly UsageWindow[];
+}
+export interface Usage {
+  fetchedAt: string; providers: readonly ProviderUsage[];
+}
+
+export function timestamp(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+export function usedPct(window: UsageWindow): number | null {
+  if (typeof window.usedPct === "number" && Number.isFinite(window.usedPct)) return window.usedPct;
+  if (typeof window.remainingPct === "number" && Number.isFinite(window.remainingPct)) return 100 - window.remainingPct;
+  return null;
+}
+export function sessionWindow(provider: ProviderUsage | undefined, policy: Policy): UsageWindow | undefined {
+  if (provider?.status !== "available") return undefined;
+  return policy.windowIds.map(id => provider.windows.find(window => window.id === id)).find(Boolean);
+}
+
+// Reused from paseo-defer's scheduler: upstream re-reads of one window differ
+// by milliseconds. Only a materially later reset is a rollover.
+export const SAME_WINDOW_MS = 60_000;
+export function resetReady(pause: Pause, usage: Usage, policy: Policy, now: number): boolean {
+  const provider = usage.providers.find(p => p.providerId === pause.provider);
+  if (provider?.status !== "available") return false;
+  const window = provider.windows.find(w => w.id === pause.windowId);
+  if (!window) return false;
+  const pct = usedPct(window);
+  if (pct === null || pct >= policy.thresholdPct) return false;
+  // A later reset with an old cached percentage must never release a pause.
+  const fetched = timestamp(provider.fetchedAt ?? usage.fetchedAt);
+  const paused = timestamp(pause.pausedAt)!;
+  if (fetched === null || fetched <= paused || fetched > now + SAME_WINDOW_MS) return false;
+  const anchor = timestamp(pause.anchorResetsAt);
+  const current = timestamp(window.resetsAt);
+  const grace = policy.resetGraceSeconds * 1000;
+  if (anchor === null) return fetched >= paused + grace;
+  // Millisecond jitter is the same window; a real rollover moves it hours.
+  if (current !== null && current - anchor > SAME_WINDOW_MS) return fetched >= paused + grace;
+  return now >= anchor + grace && fetched >= anchor + grace;
+}

package/shared/guard/presentation.ts

@@ -0,0 +1,85 @@
+import { isPending, timestamp, type Pause, type Policy } from "./policy.ts";
+
+export function pausedSessions(pauses: readonly Pause[], query = "") {
+  const needle = query.trim().toLocaleLowerCase();
+  return pauses.filter(isPending).filter(p => !needle ||
+    `${p.title ?? "Untitled session"} ${p.provider} ${p.agentId} ${p.suspension ? "native subagents" : "interrupted turn"}`.toLocaleLowerCase().includes(needle))
+    .sort((a, b) => {
+      if ((a.phase === "attention") !== (b.phase === "attention")) return a.phase === "attention" ? -1 : 1;
+      return (timestamp(a.anchorResetsAt) ?? Infinity) - (timestamp(b.anchorResetsAt) ?? Infinity) || a.pausedAt.localeCompare(b.pausedAt);
+    });
+}
+export function pausePresentation(pause: Pause, policy: Policy, now = Date.now()) {
+  const reset = timestamp(pause.anchorResetsAt);
+  const resetLabel = pause.demo ? "Waiting for your test action" : reset === null ? "Reset time unavailable" : reset <= 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"
+    : !policy.autoResume ? "Automatic resume off" : "Will resume automatically after reset";
+  return {
+    title: pause.title?.trim() || "Untitled session", state, resetLabel,
+    coverage: pause.phase === "attention" ? "Check session state" : pause.suspension ? "Includes native subagents" : pause.restartRecovery ? "Saved conversation · waiting after restart" : "Interrupted turn",
+    actionLabel: pause.suspension ? "Release and turn off" : "Cancel continuation",
+    actionHint: pause.suspension ? "Resume these workers now and exclude this session from protection."
+      : "Leave this session for you to continue manually.",
+  };
+}
+
+/** The host master switch always outranks a session's saved preference. */
+export function callerProtection(enabled: boolean, protectByDefault: boolean, override: boolean | undefined) {
+  return { enabled, protected: enabled && (override ?? protectByDefault), override: override ?? null };
+}
+
+/**
+ * What an agent is told about Session Guard, in the words it reads.
+ *
+ * Read-only by design: nothing here lets an agent opt itself out or resume a pause,
+ * so it says what will happen rather than offering a way round it.
+ */
+export function agentGuardSummary(status: {
+  governor: "off" | "active" | "deferred" | "error";
+  protected: boolean; thresholdPct: number; autoResume: boolean;
+  pauses: readonly { phase: Pause["phase"]; resetsAt: string | null }[];
+}): 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."];
+  if (status.governor === "off" || !status.protected) return ["Session Guard: off for this session. Reaching the session limit will not pause it here; the provider will simply refuse requests until reset."];
+  const pending = status.pauses.find(pause => ["pausing", "waiting", "resuming", "attention"].includes(pause.phase));
+  if (pending) {
+    return [`Session Guard: this session is paused for the session limit (${pending.phase})${pending.resetsAt ? `; the window resets ${pending.resetsAt}` : ""}.`];
+  }
+  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."}`];
+}
+
+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.
+ */
+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 === "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." };
+  }
+  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." };
+}
+
+/**
+ * Who a pause in the shared state belongs to, when it is not this plugin.
+ *
+ * Both plugins read one state file, so a list here can show pauses only the other
+ * plugin can act on. Null means this plugin governs and can act on them.
+ */
+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.";
+}

package/shared/guard/timeline.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+export const TimelineDataSchema = z.object({
+  pauseId: z.string(), event: z.enum(["paused", "resumed", "released", "attention", "recovery"]),
+  at: z.string(), provider: z.string(), native: z.boolean(), autoResume: z.boolean(),
+  resetAt: z.string().nullable(), usedPct: z.number().nullable(), note: z.string().nullable(),
+  manualResume: z.boolean().optional(), demo: z.boolean().optional(), dismissed: z.boolean().optional(),
+});
+export type TimelineData = z.infer<typeof TimelineDataSchema>;
+export const NotificationSchema = z.object({
+  id: z.string(), data: TimelineDataSchema, delivery: z.enum(["pending", "sending", "sent"]),
+});
+export type Notification = z.infer<typeof NotificationSchema>;
+
+export function timelinePresentation(data: TimelineData) {
+  const provider = data.provider === "claude" ? "Claude" : data.provider === "codex" ? "Codex" : data.provider;
+  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."
+      : 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: "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.";
+  return { title: "Paused for session limit", icon: "Pause", tone: "warning" as const,
+    detail: `${provider}${data.usedPct === null ? "" : ` · ${data.usedPct}% used`}. ${data.native ? "This session and its native subagents are paused." : "The active turn was interrupted."} ${resetLabel} ${data.autoResume ? "Automatic resume was scheduled after reset confirmation." : "Automatic resume was off; continue manually when ready."}` };
+}

package/shared/lifecycle.ts

@@ -15,3 +15,21 @@ export type Teardown = () => void | Promise<void>;
  * exits and the plugin wedges at "Stopping" for the life of the daemon.
  */
 export const lifecycle: { teardowns: Teardown[] } = { teardowns: [] };
+
+/**
+ * Runs every teardown even when one fails, then reports the first failure.
+ *
+ * One feature's cleanup throwing must not leave another's timer running: the
+ * subprocess would never exit and Paseo's stop step would hang.
+ */
+export async function runTeardowns(teardowns: readonly Teardown[]): Promise<void> {
+  let failure: unknown = null;
+  for (const teardown of teardowns) {
+    try {
+      await teardown();
+    } catch (error) {
+      failure ??= error;
+    }
+  }
+  if (failure !== null) throw failure;
+}