paseo-smart-session 2.0.0 → 2.1.0

package/server/guard/store.ts

@@ -0,0 +1,113 @@
+import { mkdir, readFile, rename, open, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { StateSchema, type State } from "../../shared/guard/policy.ts";
+
+/**
+ * Where Session Guard keeps its pauses, session overrides and governor lock.
+ *
+ * Deliberately the standalone `paseo-session-guard` plugin's directory, not
+ * `plugin-data/smart-session/`. Both plugins may be installed on one host while people
+ * move over, and both would otherwise pause the same agent. Sharing this directory
+ * means they share `governor.lock`, so exactly one of them governs; and when the
+ * standalone plugin is removed, its per-session choices and confirmed waits are picked
+ * up here instead of being lost. The state shape is therefore frozen: the standalone
+ * plugin reads and rewrites the same file, and its schema would strip anything new.
+ */
+export function guardDataDir(): string {
+  return join(process.env.PASEO_HOME ?? join(homedir(), ".paseo"), "plugin-data", "session-guard");
+}
+
+/** A live process already governs this host. Not a failure: the caller defers to it. */
+export class LockHeldError extends Error {}
+
+export class Store {
+  readonly directory: string;
+  constructor(directory: string) { this.directory = directory; }
+  async read(): Promise<State> {
+    try {
+      return StateSchema.parse(JSON.parse(await readFile(join(this.directory, "state.json"), "utf8")));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, overrides: {}, pauses: [] };
+      throw new Error("Session Guard state could not be read. Restore state.json before continuing.");
+    }
+  }
+  async write(state: State): Promise<void> {
+    const parsed = StateSchema.parse(state);
+    // Keep pending work and a bounded history; never write transcripts or prompts.
+    const pending = parsed.pauses.filter(p => p.settledAt === null);
+    const history = parsed.pauses.filter(p => p.settledAt !== null).slice(-200);
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const temporary = join(this.directory, `state-${randomUUID()}.tmp`);
+    try {
+      const file = await open(temporary, "wx", 0o600);
+      try {
+        await file.writeFile(JSON.stringify({ ...parsed, pauses: [...history, ...pending] }, null, 2));
+        await file.sync(); // Confirmed schedules must reach disk before signals.
+      } finally { await file.close(); }
+      await rename(temporary, join(this.directory, "state.json"));
+      if (process.platform === "linux") {
+        const directory = await open(this.directory, "r");
+        try { await directory.sync(); } finally { await directory.close(); }
+      }
+    } finally { await unlink(temporary).catch(() => undefined); }
+  }
+  /** One governor per host, including installs under a second plugin ID. */
+  async lock(): Promise<() => Promise<void>> {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const path = join(this.directory, "governor.lock");
+    const identity = async (pid: number) => {
+      if (process.platform !== "linux") return null;
+      const boot = (await readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim();
+      const raw = await readFile(`/proc/${pid}/stat`, "utf8");
+      const birth = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/)[19];
+      return `${boot}:${birth}`;
+    };
+    const token = `${process.pid}:${randomUUID()}:${await identity(process.pid) ?? "portable"}`;
+    const alive = async (value: string) => {
+      const [pidText, , ...saved] = value.split(":"); const pid = Number(pidText);
+      if (!Number.isInteger(pid) || pid <= 0) throw new Error("Governor lock has an invalid owner.");
+      try {
+        process.kill(pid, 0);
+        return saved.length < 2 || process.platform !== "linux" || await identity(pid) === saved.join(":");
+      } catch (error) {
+        if (["ESRCH", "ENOENT"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+        throw error;
+      }
+    };
+    const claim = async () => {
+      const handle = await open(path, "wx", 0o600);
+      try { await handle.writeFile(token); } finally { await handle.close(); }
+    };
+    try { await claim(); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const previous = await readFile(path, "utf8");
+      if (await alive(previous)) throw new LockHeldError("Another Session Guard instance is already running.");
+      // Stale-lock recovery must itself be exclusive across simultaneous loads.
+      const recoveryPath = `${path}.recovery`;
+      const abandoned = await readFile(recoveryPath, "utf8").catch(error => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (abandoned !== null) {
+        // Older releases left an empty recovery file. Allow its writer time to
+        // finish; a nonempty owner is checked by boot and process birth identity.
+        const expired = abandoned === "" ? Date.now() - (await stat(recoveryPath)).mtimeMs > 30_000 : !await alive(abandoned);
+        if (!expired) throw new LockHeldError("Governor recovery is already running.");
+        if (await readFile(recoveryPath, "utf8") !== abandoned) throw new Error("Governor recovery changed.");
+        await unlink(recoveryPath);
+      }
+      const recovery = await open(recoveryPath, "wx", 0o600);
+      await recovery.writeFile(token);
+      try {
+        if (await readFile(path, "utf8") !== previous) throw new Error("Governor lock changed; reload Session Guard.");
+        await unlink(path);
+        await claim();
+      } finally { await recovery.close(); await unlink(`${path}.recovery`).catch(() => undefined); }
+    }
+    return async () => {
+      if (await readFile(path, "utf8").catch(() => null) === token) await unlink(path);
+    };
+  }
+}

package/server/guard/timeline.ts

@@ -0,0 +1,24 @@
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { Notification } from "../../shared/guard/timeline.ts";
+
+export type PublishTimeline = (agentId: string, notification: Notification, reconcile: boolean) => Promise<void>;
+export function timelinePublisher(api: () => Promise<PluginHandlerContext["paseo"]>): PublishTimeline {
+  return async (agentId, notification, reconcile) => {
+    const timeline = (await api()).agents.ref(agentId).timeline;
+    if (reconcile) {
+      // Lost acknowledgements are checked against durable history before retry.
+      // Only IDs/timestamps are inspected; content is never logged or retained.
+      let cursor: NonNullable<Parameters<typeof timeline.refetch>[0]>["cursor"];
+      for (let page = 0; page < 32; page++) {
+        const result = await timeline.refetch({ direction: cursor ? "before" : "tail", ...(cursor ? { cursor } : {}), limit: 100, projection: "canonical" });
+        if (result.error || result.staleCursor) throw new Error("Timeline receipt could not be checked.");
+        if (result.entries.some(entry => entry.item.type === "plugin" && entry.item.id === notification.id)) return;
+        if (!result.hasOlder || result.entries.some(entry => Date.parse(entry.timestamp) < Date.parse(notification.data.at))) break;
+        if (!result.startCursor) throw new Error("Timeline receipt cursor is unavailable.");
+        cursor = result.startCursor;
+        if (page === 31) throw new Error("Timeline receipt check exceeded its page budget.");
+      }
+    }
+    await timeline.append({ type: "plugin", id: notification.id, kind: "quota-pause", version: 1, data: notification.data });
+  };
+}

package/server/guard/usage.ts

@@ -0,0 +1,57 @@
+/**
+ * Session Guard's usage reading, sharpened with Smart Session's recorder.
+ *
+ * The guard needs every provider's session window, which only Paseo's
+ * `provider.usage.list` reports. For Claude, though, Paseo serves a cache up to five
+ * minutes old and cannot be made to refresh (RESEARCH.md §7a), while the recorder in
+ * this same process asks Anthropic directly every three minutes. Whichever reading is
+ * newer wins, so a pause and — more usefully — its release follow the fresher number
+ * instead of waiting out Paseo's cache.
+ *
+ * Only a reading that says when the provider produced it is used: `resetReady` trusts
+ * `fetchedAt` to prove a report is newer than the pause, and an observation time is not
+ * that.
+ */
+
+import { canonicalWindowId, effectiveAt, type UsageSample } from "../../shared/usage.ts";
+import type { ProviderUsage, Usage, UsageWindow } from "../../shared/guard/policy.ts";
+
+/** The provider the recorder measures. It records nothing for any other. */
+const RECORDED_PROVIDER = "claude";
+
+export function withRecordedUsage(paseo: Usage, recorded: UsageSample | null): Usage {
+  if (recorded === null || recorded.fetchedAt === null) return paseo;
+  const recordedMs = Date.parse(effectiveAt(recorded));
+  if (!Number.isFinite(recordedMs)) return paseo;
+
+  const index = paseo.providers.findIndex((provider) => provider.providerId === RECORDED_PROVIDER);
+  const current = index === -1 ? undefined : paseo.providers[index];
+  if (current?.status === "available") {
+    const paseoMs = Date.parse(current.fetchedAt ?? paseo.fetchedAt);
+    if (Number.isFinite(paseoMs) && paseoMs >= recordedMs) return paseo;
+  }
+
+  // Keep Paseo's window ids, which are what the policy's `windowIds` name, and fill
+  // them from the recorder; the recorder's own canonical ids cover any it lacks.
+  const used = new Set<string>();
+  const windows: UsageWindow[] = [];
+  for (const window of current?.status === "available" ? current.windows : []) {
+    const id = canonicalWindowId(window.id);
+    const reading = recorded.windows[id];
+    if (reading === undefined) {
+      windows.push(window);
+      continue;
+    }
+    used.add(id);
+    windows.push({ id: window.id, usedPct: reading.pct, remainingPct: null, resetsAt: reading.resetsAt ?? window.resetsAt ?? null });
+  }
+  for (const [id, reading] of Object.entries(recorded.windows)) {
+    if (!used.has(id)) windows.push({ id, usedPct: reading.pct, remainingPct: null, resetsAt: reading.resetsAt });
+  }
+
+  const merged: ProviderUsage = { providerId: RECORDED_PROVIDER, status: "available", fetchedAt: new Date(recordedMs).toISOString(), windows };
+  const providers = [...paseo.providers];
+  if (index === -1) providers.push(merged);
+  else providers[index] = merged;
+  return { ...paseo, providers };
+}

package/server/recorder.ts

@@ -22,6 +22,7 @@ import {
   appendUsage,
   clearCaches,
   newestUsage,
+  noteAcceptedReading,
   noteNewestUsage,
   type ContextSample,
 } from "./store.ts";
@@ -86,6 +87,7 @@ async function record(sample: UsageSample): Promise<boolean> {
   const newest = await newestUsage();
   const verdict = acceptReading(newest, sample);
   if (!verdict.ok) return false;
+  noteAcceptedReading(sample);
   if (!isWorthRecording(newest, sample)) return false;
   await appendUsage(sample);
   noteNewestUsage(sample);

package/server/store.ts

@@ -12,7 +12,7 @@ import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-import type { UsageSample } from "../shared/usage.ts";
+import { effectiveAt, type UsageSample } from "../shared/usage.ts";
 
 const DATA_DIRECTORY = "smart-session";
 const LEGACY_DATA_DIRECTORY = "super-session";
@@ -195,7 +195,31 @@ export function noteNewestUsage(sample: UsageSample): void {
   newestCache = { value: sample };
 }
 
+/**
+ * The newest reading that passed the acceptance gate, whether or not it was written.
+ *
+ * Most readings are refused by `isWorthRecording` only because nothing moved, so the
+ * newest *line* can be minutes older than the newest *fact*. Session Guard wants the
+ * fact — a fresh report below its threshold is what confirms a reset.
+ */
+let latestAccepted: UsageSample | null = null;
+
+export function noteAcceptedReading(sample: UsageSample): void {
+  if (latestAccepted === null || Date.parse(effectiveAt(sample)) >= Date.parse(effectiveAt(latestAccepted))) {
+    latestAccepted = sample;
+  }
+}
+
+/** The freshest Claude plan-usage reading this process knows of, recorded or not. */
+export async function freshestUsage(): Promise<UsageSample | null> {
+  const newest = await newestUsage();
+  if (latestAccepted === null) return newest;
+  if (newest === null) return latestAccepted;
+  return Date.parse(effectiveAt(latestAccepted)) >= Date.parse(effectiveAt(newest)) ? latestAccepted : newest;
+}
+
 /** Drops in-memory state so a reload starts clean. */
 export function clearCaches(): void {
   newestCache = null;
+  latestAccepted = null;
 }

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;
+}