paseo-smart-session 2.0.0 → 2.2.0

package/client/settings.tsx

@@ -0,0 +1,105 @@
+import { useRpc, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection, SettingsSwitch, useToast } from "@getpaseo/plugin/client/ui";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useState } from "react";
+import { ActivityIndicator, ScrollView, Text, View } from "react-native";
+
+import { formatCompactTokens } from "../shared/format";
+import { enrolmentState } from "../shared/governor";
+import { getSettings, installStatus, setSettings } from "../shared/smart-session";
+import { withCompactThreshold } from "../shared/thresholds";
+import { errorText } from "./kit";
+import { refreshPills } from "./pill-store";
+
+/** A whole number from 1 to 99, or null. */
+function percent(value: string): number | null {
+  const parsed = Number(value.trim());
+  return Number.isInteger(parsed) && parsed >= 1 && parsed <= 99 ? parsed : null;
+}
+
+/**
+ * Settings → Plugins → Smart Session → Smart Compact. Everything that tunes when a
+ * session is asked to compact itself; the overview keeps only the on/off switch.
+ */
+export function SmartCompactSettings({ theme, layout }: PluginSurfaceProps) {
+  const c = theme.colors;
+  const toast = useToast();
+  const queryClient = useQueryClient();
+  const read = useRpc(getSettings);
+  const write = useRpc(setSettings);
+  const readEnrolment = useRpc(enrolmentState);
+  const readInstall = useRpc(installStatus);
+  const query = useQuery({ queryKey: ["smart-session", "settings"], queryFn: () => read({}), refetchInterval: 60_000 });
+  const install = useQuery({ queryKey: ["smart-session", "install"], queryFn: () => readInstall({}), refetchInterval: 5 * 60_000 });
+  const [saving, setSaving] = useState(false);
+  const [draft, setDraft] = useState<{ large: string; small: string } | null>(null);
+  const [inputKey, setInputKey] = useState(0);
+  const settings = query.data?.settings;
+  useEffect(() => { setDraft(null); }, [settings?.thresholds.large.compact, settings?.thresholds.small.compact]);
+
+  if (query.isError && settings === undefined) return <View style={{ padding: 16, gap: 12 }}>
+    <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{errorText(query.error)}</Text>
+    <SettingsCard><SettingsAction label="Load the settings again" actionLabel="Retry" onPress={() => void query.refetch()} /></SettingsCard>
+  </View>;
+  if (settings === undefined) return <ActivityIndicator accessibilityLabel="Loading Smart Compact settings" color={c.foregroundMuted} style={{ padding: 24 }} />;
+
+  async function save(patch: Parameters<typeof write>[0], message: string) {
+    setSaving(true);
+    try {
+      await write(patch);
+      await refreshPills(() => readEnrolment({}));
+      await queryClient.invalidateQueries({ queryKey: ["smart-session"] });
+      toast.show(message);
+    } catch (error) {
+      toast.error(errorText(error));
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  const large = draft === null ? settings.thresholds.large.compact : percent(draft.large);
+  const small = draft === null ? settings.thresholds.small.compact : percent(draft.small);
+  const changed = draft !== null && large !== null && small !== null && (large !== settings.thresholds.large.compact || small !== settings.thresholds.small.compact);
+  const off = !settings.enabled || saving;
+  const report = install.data?.report;
+  const hooksHint = report === undefined ? "Keeps this plugin's context and compaction hooks in ~/.claude/settings.json."
+    : report.error !== null ? report.error
+      : report.pluginDir === null || report.hooks.length === 0 ? "Not registered, so nothing will ask a session to compact itself."
+        : `Registered: ${report.hooks.join(", ")}. Only entries that point at this plugin are touched.`;
+  const from = formatCompactTokens(settings.thresholds.largeWindowFrom);
+
+  return <ScrollView style={{ flex: 1 }} contentContainerStyle={{ paddingVertical: 8, gap: 24 }}>
+    <SettingsSection title="Smart Compact" info="A session is never compacted unless it agrees. At the end of a turn past its line, it is asked whether to compact; it can compact, put it off with a reason, or keep working.">
+      <SettingsCard>
+        <SettingsSwitch label="Smart Compact" hint={settings.enabled ? "On. Context notices, and the question at the compact line." : "Off. Nothing is asked and nothing is compacted."}
+          value={settings.enabled} disabled={saving} onValueChange={(enabled) => void save({ enabled }, enabled ? "Smart Compact on" : "Smart Compact off")} />
+        <SettingsSwitch label="Enrol sessions automatically" hint="A session that saves its task state with the checkpoint tool is enrolled by that alone. Off, enrol each one from its pill."
+          value={settings.autoEnrol} disabled={off} onValueChange={(autoEnrol) => void save({ autoEnrol }, autoEnrol ? "Sessions enrol themselves" : "Sessions are enrolled one at a time")} />
+        <SettingsSwitch label="Context pill on every session" hint="A ring above the message box with the session's context and its compact line. Press it to enrol or remove the session."
+          value={settings.showPill} disabled={off} onValueChange={(showPill) => void save({ showPill }, showPill ? "Pill shown on every session" : "Pill hidden")} />
+      </SettingsCard>
+    </SettingsSection>
+    <SettingsSection title="When to ask" info="What wears a session down is its absolute size, not its share of the window, so large windows are asked much earlier. Earlier context notices move down with the line.">
+      <SettingsCard>
+        <SettingsInput key={`large-${inputKey}`} label={`Windows of ${from} or more (%)`} hint={`Asked at ${large ?? "—"}%, about ${large === null ? "—" : formatCompactTokens((large / 100) * 1_000_000)} tokens of a 1M window. Default 30.`}
+          initialValue={String(settings.thresholds.large.compact)} disabled={off} error={draft !== null && large === null ? "Enter a whole number from 1 to 99." : null}
+          onChangeText={(value) => setDraft((previous) => ({ large: value, small: previous?.small ?? String(settings.thresholds.small.compact) }))} />
+        <SettingsInput key={`small-${inputKey}`} label={`Smaller windows (%)`} hint={`Asked at ${small ?? "—"}% of a window under ${from}. Default 85.`}
+          initialValue={String(settings.thresholds.small.compact)} disabled={off} error={draft !== null && small === null ? "Enter a whole number from 1 to 99." : null}
+          onChangeText={(value) => setDraft((previous) => ({ small: value, large: previous?.large ?? String(settings.thresholds.large.compact) }))} />
+        {draft !== null ? <>
+          <SettingsAction label="Apply the new lines" hint={changed ? `Large ${large}% · small ${small}%` : "Nothing to apply yet"} actionLabel="Save" disabled={!changed || off}
+            onPress={() => void save({ thresholds: { ...settings.thresholds, large: withCompactThreshold(settings.thresholds.large, large!), small: withCompactThreshold(settings.thresholds.small, small!) } }, `Smart Compact asks at ${large}% and ${small}%`)} />
+          <SettingsAction label="Keep the saved lines" actionLabel="Discard" disabled={saving} onPress={() => { setDraft(null); setInputKey((k) => k + 1); }} />
+        </> : null}
+      </SettingsCard>
+    </SettingsSection>
+    <SettingsSection title="Claude Code">
+      <SettingsCard>
+        <SettingsSwitch label="Register the hooks" hint={hooksHint} value={settings.installHooks} disabled={off}
+          onValueChange={(installHooks) => void save({ installHooks }, installHooks ? "Hooks registered with Claude Code" : "Hooks removed from Claude Code")} />
+        {report?.mcp === "unavailable" ? <SettingsRow label="MCP server not registered" hint="The claude command was not reachable from the daemon." /> : null}
+      </SettingsCard>
+    </SettingsSection>
+  </ScrollView>;
+}

package/client/theme.ts

@@ -0,0 +1,56 @@
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import type { ViewStyle } from "react-native";
+import type { Tone } from "../shared/forecast";
+
+/**
+ * Theme-aware depth and tint, shared with the rest of the plugin family
+ * (Follow-up's client/theme.ts). Only host tokens are used: the helpers derive
+ * alphas from them rather than introducing colours of their own.
+ */
+export type Theme = PluginHostProps["theme"];
+export type Colors = Theme["colors"];
+
+function channels(color: string | undefined): number[] | null {
+  if (typeof color !== "string") return null;
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+  if (hex) return (hex[1].length === 3 ? [...hex[1]].map((d) => d + d) : hex[1].match(/../g)!).map((d) => parseInt(d, 16));
+  const fn = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(color);
+  return fn ? fn.slice(1, 4).map(Number) : null;
+}
+
+/** Light when the page ground is bright; unknown colours count as dark, Paseo's default. */
+export function isLight(colors: Colors): boolean {
+  const rgb = channels(colors.surface0);
+  if (!rgb) return false;
+  const [r, g, b] = rgb.map((v) => { const c = v / 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.4;
+}
+
+export function withAlpha(color: string, alpha: number): string {
+  const rgb = channels(color);
+  return rgb ? `rgba(${rgb.join(", ")}, ${alpha})` : color;
+}
+
+/** A tag fill in the same hue as its text: 12% on light grounds, 16% on dark ones. */
+export function tint(color: string, colors: Colors): string {
+  return withAlpha(color, isLight(colors) ? 0.12 : 0.16);
+}
+
+/** Card depth: a hairline ring plus a soft lift in light themes, a single faint ring in dark ones. */
+export function raised(colors: Colors): ViewStyle {
+  return isLight(colors)
+    ? ({ boxShadow: "0px 0px 0px 1px rgba(0, 0, 0, 0.07), 0px 1px 2px -1px rgba(0, 0, 0, 0.06), 0px 2px 6px 0px rgba(0, 0, 0, 0.04)" } as ViewStyle)
+    : ({ boxShadow: "0px 0px 0px 1px rgba(255, 255, 255, 0.08)" } as ViewStyle);
+}
+
+/** State colours: amber when a limit is near, red when it bites, green only for a resumed/finished outcome. */
+export function toneColor(colors: Colors, tone: Tone | "success" | "muted"): string {
+  switch (tone) {
+    case "success": return colors.statusSuccess;
+    case "danger": return colors.statusDanger;
+    case "warning": return colors.statusWarning;
+    default: return colors.foregroundMuted;
+  }
+}
+
+export const tabular = { fontVariant: ["tabular-nums" as const] };

package/docs/navigation-verification.md

@@ -1,11 +1,11 @@
 # Navigation verification
 
-Verified the actual plugin in an isolated Paseo 0.12.0 daemon with synthetic workspace and provider data, using the app web runtime at 1440×1000 and 390×844.
+Verified in an isolated Paseo 0.15 daemon with synthetic workspaces, usage history and sessions, using the app's web runtime at 1440×900 and 390×844, light and dark.
 
-- Sidebar main view → Display settings → Overview opens the plugin surfaces directly.
-- Compact settings have no horizontal overflow and preserve accessible native switches.
-- Existing saved sidebar preferences retain their values. Button-bearing plugins expose independent positive enable_ preferences; hiding a button does not stop its feature.
-- Graphite and Transfer header hiding/restoration were exercised through the UI; Transfer settings remained reachable from Command-K while its sidebar was hidden. Follow-up's choice survived a full page reload.
-- Button lifecycle regressions cover registrations discovered while hidden, retaining the latest descriptor, duplicate prevention, restoration and teardown.
+- The sidebar row **Smart Session** opens the overview screen; its header reads **Smart Session**, not a raw id. The row trails the session window's use, or how many sessions are paused.
+- **Paused sessions** is its own screen with its own title, opened from the overview, the Session Guard pill's menu, a pause card or Command Center.
+- Smart Compact, Session Guard and Display settings live in **Settings → Plugins → Smart Session** and open from the overview's gear, the feature cards and Command Center.
+- **Display** hides the sidebar row or the composer pills; hiding either never turns a feature off, and Command Center still opens the overview.
+- Compact settings have no horizontal overflow and keep accessible native switches.
 
 Screenshots: [desktop](screenshots/display-settings-desktop.png), [compact](screenshots/display-settings-mobile.png). Screenshots contain synthetic data. No main daemon restart or real-agent messages were used.

package/docs/session-guard.md

@@ -0,0 +1,88 @@
+# Session Guard
+
+Session Guard pauses agents at their provider's session limit and continues the same conversations after the window resets, even while the Paseo app is closed. It began as the standalone [paseo-session-guard](https://github.com/tomgrin10/paseo-session-guard) plugin and now ships inside Smart Session. See the [README](../README.md) for installation.
+
+## Turning it on
+
+Session Guard is **off by default**. Turn it on with the **Session Guard** switch on the Smart Session overview, or in **Settings → Plugins → Smart Session → Session Guard**. Off, it holds no lock, writes nothing and draws no pill.
+
+### Moving from the standalone plugin
+
+Smart Session never runs Session Guard while the standalone plugin is configured **and enabled** on the host, even when it could. Released versions of the standalone plugin resume every suspended session in the shared state when they are disabled or removed, whichever plugin paused it, so two enabled copies cannot share a host safely. Both keep their state in `$PASEO_HOME/plugin-data/session-guard/` and take the same `governor.lock` there, so a disabled copy that is still shutting down is waited out too.
+
+- While the standalone plugin is enabled, Smart Session's Session Guard pauses nothing. Its settings, the paused-sessions list and the overview say so, its pill stays hidden, and pauses in the list are marked as the standalone plugin's, with no controls.
+- **Disable or uninstall Session Guard** (**Settings → Plugins**, `paseo plugin disable paseo-session-guard` or `paseo plugin remove paseo-session-guard`). Smart Session takes over on its next check, about 15 seconds later. Per-session choices and waiting pauses carry over, because they are the same file. The standalone plugin releases native workers when it stops; if the quota is still full, Smart Session normally pauses that work again on its first check.
+- Smart Session's settings start from defaults: the standalone plugin's settings belong to that installation and are deleted with it. Re-apply any custom threshold, timing or continuation message.
+- If the standalone plugin is enabled again while Smart Session is protecting the host, Smart Session releases the sessions it suspended, keeps their confirmed waits, gives up the lock and stops. The standalone plugin does not retry its lock, so reload it to let it take over, or disable it again to hand back to Smart Session. Between enabling it and Smart Session's next check (up to the check interval) both are loaded; avoid disabling it again within that window.
+
+Turning Session Guard off releases suspended workers immediately. A message continuation that is still waiting keeps the lock until you cancel it or turn Session Guard back on. With nothing left waiting, Smart Session releases the lock.
+
+## Use
+
+Every live session with a workspace gets a **Session Guard** composer pill while the feature is on. Open its menu to:
+
+- **Turn off for this session** / **Protect this session**: persist an explicit session override.
+- **Use host default**: remove that override.
+- **Cancel automatic continuation**: leave an interrupted turn for you to continue manually. For suspended native workers, **Release and turn off for this session** resumes them immediately and opts the session out, preventing the next check from pausing it again.
+- **Session Guard settings**: configure the host policy and see paused sessions.
+- **All paused sessions**: open the host-wide overview.
+
+The **Paused sessions** screen gathers every Session Guard pause on the selected host, each led by the time its window resets and a countdown, with the session title, provider and whether native subagents are frozen or the turn was interrupted. Uncertain stops are grouped under **Needs attention**. Open a session or manage its pause directly; search appears when the list is busy. Open it from the Smart Session overview (the **2 paused** line under the headline, or the Session Guard card), the pill's menu, Command Center, settings, or a pause card. While anything is paused, the Smart Session sidebar row shows the count. A waiting session's composer pill begins **Paused**. Its workspace also gets an amber **Paused** label in the left sidebar. The label persists through restarts and stays until the last paused session in that workspace is released. Turn it off with **Label paused workspaces** in settings; other workspace labels stay intact.
+
+Confirmed pauses write a **Paused for session limit** timeline entry: the reset time with a live countdown, the provider and how much of the window was used, and whether native subagents are covered. When the pause ends, the entry folds into one line ("Paused at 7:57 PM · resumed 9:41 PM"), so the chat keeps the history without a stale card. Resume, release, and uncertain-stop entries make the recovery history clear. Existing confirmed waits are backfilled when upgrading. Timeline events use the host-owned plugin IPC identity, stay outside model messages, and never start a new turn. Delivery is journaled and retried; a lost acknowledgement is checked against timeline IDs before another append. Timeline delivery failures do not undo pauses and are shown in the overview/settings.
+
+Choose **Dismiss pause** on an active pause or restart-recovery timeline item to release it **without sending a message**. This cancels its scheduled continuation, turns protection off for that session, clears its active pause from the overview and workspace label when applicable, and collapses the original card to a short acknowledgement. Existing suspended workers are released and may continue their current work. The dismissal is saved before release so it survives restarts; partial release retries without sending. Historical cards cannot dismiss a newer pause. **Resume now** remains available when you want Guard to continue interrupted work immediately.
+
+Settings are also available in **Settings → Plugins → Smart Session → Session Guard** and Command Center. The default can be changed from **Protect all sessions** to **Opt in per session**. Explicit overrides survive that change. Native subagents inherit their parent session's protection and opt-out. Paseo-created child sessions have their own protection and pill, like every other session.
+
+| Setting | Default | Range / meaning |
+|---|---|---|
+| Enabled | No | Off releases suspended workers; message continuations stay on hold |
+| Default protection | All sessions | Can switch to opt in |
+| Automatic continuation | Yes | Off lets you continue manually |
+| Include native subagents | Yes | Linux Claude/Codex process-tree suspension; off uses foreground interruption |
+| Pause threshold | 100% | 1–100% |
+| Check interval | 15 seconds | 5–300 seconds |
+| Grace after reset | 30 seconds | 0–600 seconds |
+| Continuation spacing | 5 seconds | 0–300 seconds; delivered on scheduler checks |
+| Providers | All reporting session usage | Optional comma-separated provider IDs |
+| Session windows | `five_hour, session` | IDs in preference order |
+| Continuation message | Resume unfinished work from conversation and workspace | Editable, 1–8,000 characters |
+
+With native coverage enabled on Linux, the plugin suspends the session's Claude or Codex provider process and its nested workers/tools using `SIGSTOP`. This preserves the current parent turn and native subagents, including background work under an idle parent. After a confirmed reset, `SIGCONT` resumes that same process tree; no new message is needed. A quota rejection already in flight can still finish the original turn after resumption; that matching failed turn gets one recovery message after reset.
+
+Other providers, and Claude/Codex with native coverage turned off, use foreground interruption followed by one continuation message in the existing conversation. The plugin never compacts, clears context, switches models, or creates replacement agents. Interrupted tools may need recovery; the default continuation asks the agent to inspect their state before retrying.
+
+Native coverage currently requires **Linux**, access to `/proc`, and a uniquely identified provider child of the connected local daemon. Ownership is checked using the daemon PID and its injected `PASEO_AGENT_ID`; each signal rechecks the process birth identity to avoid PID reuse. Other sessions, the daemon, the plugin, and workers already stopped by a person are excluded. Ambiguous ownership is reported in settings and retried, without claiming native protection succeeded. Turn off native coverage on an unsupported host to use foreground protection. Native work running in external services outside the provider's process tree cannot be suspended.
+
+Suspension does not undo an API request or external action already sent. Network calls can time out while paused, and tools can retain locks. Resumption preserves local process state, but a provider's ordinary network/tool error still requires normal recovery; Session Guard automatically recovers only matching quota failures. Outstanding permission prompts remain for the person to answer.
+
+The pill's icon carries its state: a shield when protected, a muted crossed-out shield when off, an amber pause while paused, and a red warning when the session needs a look. A confirmed pause timeline entry offers **Resume now** while that exact pause is still waiting. This resumes owned native workers in place, or sends one manual continuation for an interrupted turn, and opts that session out so a still-full quota cannot immediately pause it again. Restore protection from the pill when ready. Resuming does not restore provider capacity: requests can still be rejected before reset. Historical entries cannot resume a newer pause, and unconfirmed message delivery is left for inspection without a blind retry.
+
+A disposable, empty session labelled `session_guard_demo=true` can exercise the real native pause/release path through the `smart-session.guard.demo-pause` RPC (`node probe.mjs rpc smart-session.guard.demo-pause '{"agentId":"…"}'`). It must have no user messages, active turn, or pending permissions. Its timeline explicitly says **Session Guard demo paused**, makes no quota claim, and waits for your action even when capacity resets. The demo never sends a task or changes provider quota reports.
+
+## Timing and persistence
+
+The governor reads `provider.usage.list` through Paseo's own daemon client. For Claude it also uses Smart Session's recorder, which asks Anthropic directly every three minutes: whichever reading the provider produced more recently wins, so a reset is usually confirmed before Paseo's cache refreshes. Claude's `five_hour` and Codex's `session` windows work by default; any other provider reporting a matching window also qualifies. A percentage of remaining capacity is converted when a used percentage is absent. Weekly usage alone does not pause work under the defaults.
+
+Paseo caches upstream quota reports (the current service defaults to five minutes). The check interval cannot force an upstream refresh: for providers other than Claude, pause detection and reset confirmation follow the reports Paseo actually exposes. A quota rejection can also register interrupted work if the session window is reported at the threshold. Ordinary errors and sessions stopped by a person do not register continuations.
+
+Reset requires a **newer usage observation below the threshold**, plus the configured grace. Millisecond differences in reset timestamps are treated as the same window, using Defer's 60-second tolerance. If the reset time is missing, fresh below-threshold usage after the grace period releases the pause. If usage is unavailable, work waits and checks retry automatically.
+
+Confirmed pauses and session overrides persist in `$PASEO_HOME/plugin-data/session-guard/state.json`; host settings use Paseo's versioned settings API. Native process identities are journaled before signals. A plugin crash/restart preserves confirmed suspension; recovery releases an unconfirmed partial freeze, and safely retries an interrupted process release. Graceful plugin unload releases suspended workers immediately and preserves the confirmed wait on disk. A full daemon or VM restart ends the old workers, but keeps the paused session in the overview, its original reset schedule, and the same conversation. Once fresh provider usage confirms the reset, Session Guard sends one continuation to that conversation. Its timeline explains the recovery; Resume now remains available. New user messages, an explicit stop, closed sessions, and opt-outs cancel automatic recovery. In-memory native subagents cannot survive a full restart; the parent conversation resumes its unfinished task. Foreground message continuations also survive reloads and daemon restarts. Confirmed state writes are flushed to disk before actions. Governor ownership uses the VM boot and process birth identity, so a reboot or reused PID does not retain a stale lock. Only one governor can own this data path, whether it is Smart Session, the standalone plugin, or either installed twice under different IDs. Gracefully closed snapshots reopen only when the saved daemon identity changes; closing a session in the same daemon cancels its continuation.
+
+A new user message, another running turn, closing/archiving/removing the agent, a provider change, or opting out cancels the old continuation and releases owned suspended workers. Pending permissions are left for the person to answer. Message continuations are sent only into idle sessions, or a quota-error session that the plugin registered. Rechecks immediately precede interruption, suspension, and delivery; Paseo 0.10.1 has no conditional atomic “send only if this turn is unchanged” operation, so a simultaneous user action can still race that final recheck.
+
+If a reload or connection loss interrupts an unconfirmed stop/send, the pill reads **Check session**. Delivery acceptance may be ambiguous, so the plugin leaves that session for manual inspection instead of retrying a message that might already have arrived. Confirmed waiting work continues automatically.
+
+## Daemon authentication
+
+For password-protected daemons, Smart Session reads `PASEO_PASSWORD`, then `PASEO_PASSWORD_FILE`, then `~/paseo-hub/secrets/daemon-password`. It never logs or stores the password. Provider usage comes through Paseo; provider credentials are not read directly.
+
+## Client API limits
+
+Workspace labels support text and color. Session Guard uses the short amber label **Paused**; a vector pause icon in that label needs Paseo client support. The normal desktop/mobile composer Send action cannot currently be intercepted by a plugin. Automatic “send after reset or unpause?” confirmation is not implemented in this version; adding it requires a Paseo composer send hook. Existing pause, resume, timeline, and workspace-label behavior does not depend on such a hook.
+
+## Agents
+
+Inside Paseo, the `budget_status` tool adds one line about the calling session: whether Session Guard will pause it at the limit and continue it afterwards, or whether it is paused now. It covers only the caller, never other sessions or continuation text, and it cannot turn protection off or resume a pause.

package/index.client.tsx

@@ -1,48 +1,65 @@
 import { withButtonVisibility } from "./client/button-visibility";
 import { contributeDisplay } from "./client/display";
-import { withNavigation } from "./client/navigation";
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 
+import { observeAgents } from "./client/agents";
+import { contributeChat } from "./client/chat";
+import { contributeGuardClient } from "./client/guard/index";
+import { createLive } from "./client/live";
+import { OVERVIEW_SCREEN, SMART_COMPACT_SETTINGS, makeOverview } from "./client/overview";
 import { contributeClient, refreshPills } from "./client/pill";
-import { SmartSessionSurface } from "./client/surface";
+import { SmartCompactSettings } from "./client/settings";
 import { enrolmentState } from "./shared/governor";
-import { getSettings, setSettings } from "./shared/smart-session";
+import { budgetStatus, getSettings, setSettings } from "./shared/smart-session";
 
 export default function contribute(host: PluginClientContext) {
   const visibility = withButtonVisibility(host);
   const client = visibility.client;
-  client.addSurface("overview", withNavigation(SmartSessionSurface, client, "overview"));
-  const removeDisplay = contributeDisplay(client, {
-    id: "smart-session",
-    title: "Smart Session",
-    icon: "Gauge",
-    surface: "overview",
-  });
+  const live = createLive();
+  const removers = [
+    client.addScreen({ id: OVERVIEW_SCREEN, title: "Smart Session", Component: makeOverview(client, live) }),
+    client.addSettingsScreen({ id: SMART_COMPACT_SETTINGS, title: "Smart Compact", icon: "FoldVertical", Component: SmartCompactSettings }),
+    contributeDisplay(client, live),
+    client.addCommandCenterItem({
+      id: "smart-session-open",
+      title: "Smart Session: plan usage and context",
+      icon: "Gauge",
+      keywords: ["usage", "budget", "limit", "forecast", "context", "tokens", "compact", "smart session"],
+      context: "global",
+      onSelect({ openScreen }) {
+        openScreen({ screenId: OVERVIEW_SCREEN });
+      },
+    }),
+    client.addCommandCenterItem({
+      id: "smart-session-pill",
+      title: "Show or hide the context pill",
+      icon: "ToggleLeft",
+      keywords: ["pill", "compact", "smart", "context", "ring", "enrol"],
+      context: "global",
+      async onSelect({ rpc }) {
+        const { settings } = await rpc(getSettings, {});
+        await rpc(setSettings, { showPill: !settings.showPill });
+        await refreshPills(() => rpc(enrolmentState, {}));
+      },
+    }),
+    contributeChat(client),
+  ];
 
-  client.addCommandCenterItem({
-    id: "smart-session-open",
-    title: "Show plan usage and agent context",
-    icon: "Gauge",
-    keywords: ["usage", "budget", "limit", "context", "tokens", "compact"],
-    context: "global",
-    onSelect({ openSurface }) {
-      openSurface("overview");
-    },
-  });
+  // The sidebar row shows the session window between overview visits.
+  const readBudget = () => client.rpc(budgetStatus, {}).then((budget) => live.setBudget(budget)).catch(() => undefined);
+  void readBudget();
+  const budgetTimer = setInterval(() => void readBudget(), 2 * 60_000);
 
-  client.addCommandCenterItem({
-    id: "smart-session-pill",
-    title: "Show or hide the smart-compact pill",
-    icon: "ToggleLeft",
-    keywords: ["pill", "compact", "smart", "governor", "enrol"],
-    context: "global",
-    async onSelect({ rpc }) {
-      const { settings } = await rpc(getSettings, {});
-      await rpc(setSettings, { showPill: !settings.showPill });
-      await refreshPills(() => rpc(enrolmentState, {}));
-    },
-  });
-
-  const removeClient = contributeClient(client);
-  return () => { visibility.dispose(); removeDisplay(); return removeClient(); };
+  // One agent observation for every pill in this bundle.
+  const agents = observeAgents(client);
+  const removeClient = contributeClient(client, agents);
+  const removeGuard = contributeGuardClient(client, agents, live);
+  return () => {
+    clearInterval(budgetTimer);
+    removeGuard();
+    removeClient();
+    for (const remove of removers.splice(0)) void remove();
+    visibility.dispose();
+    return agents.dispose();
+  };
 }

package/index.server.ts

@@ -1,3 +1,4 @@
+import { contributeGuard } from "./server/guard/index.ts";
 import { contributeSessionMcp } from "./server/session-mcp.ts";
 import { displayPreferences } from "./shared/display";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
@@ -6,7 +7,7 @@ import { readAgents, withDaemon } from "./server/daemon.ts";
 import { contextGrowth, projectFull } from "./server/growth.ts";
 import { install } from "./server/install.ts";
 import { summarizeSpend } from "./server/spend.ts";
-import { countEnrolled, listEnrolment, readSettings, setEnrolled, writeSettings } from "./server/settings.ts";
+import { countEnrolled, listEnrolment, readSettings, setEnrolled, stateWrittenAt, writeSettings } from "./server/settings.ts";
 import { dataDir, newestUsage, readUsage } from "./server/store.ts";
 import {
   budgetStatus,
@@ -24,8 +25,8 @@ import {
   requestCompaction,
   setEnrolment,
 } from "./shared/governor.ts";
-import { burnRatePctPerHour, projectedExhaustion, segmentBlocks } from "./shared/blocks.ts";
-import { lifecycle } from "./shared/lifecycle.ts";
+import { burnRatePctPerHour, projectedExhaustion, segmentBlocks, thinPoints } from "./shared/blocks.ts";
+import { lifecycle, runTeardowns } from "./shared/lifecycle.ts";
 import { profileFor } from "./shared/thresholds.ts";
 import { effectiveAt } from "./shared/usage.ts";
 
@@ -42,6 +43,8 @@ import "./server/install-on-load.ts";
 export default function contribute(server: PluginServerContext) {
   const removeSessionMcp = contributeSessionMcp(server);
   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 () => {
     try {
       const since = Date.now() - 14 * 24 * 60 * 60 * 1000;
@@ -49,8 +52,9 @@ export default function contribute(server: PluginServerContext) {
       const newest = await newestUsage();
 
       // One row per window, taken from its currently open block.
-      const open = new Map<string, ReturnType<typeof segmentBlocks>[number]>();
-      for (const block of segmentBlocks(samples)) open.set(block.windowId, block);
+      const blocks = segmentBlocks(samples);
+      const open = new Map<string, (typeof blocks)[number]>();
+      for (const block of blocks) open.set(block.windowId, block);
 
       const windows = [...open.values()]
         .map((block) => ({
@@ -59,12 +63,19 @@ export default function contribute(server: PluginServerContext) {
           resetsAt: block.resetsAt,
           burnPctPerHour: burnRatePctPerHour(block),
           projectedFullAt: projectedExhaustion(block),
+          startAt: block.startAt,
+          history: thinPoints(block.points, 96),
         }))
         .sort((a, b) => b.pct - a.pct);
+      const current = open.get("five_hour");
+      const past = blocks
+        .filter((block) => block.windowId === "five_hour" && block !== current)
+        .map((block) => ({ startAt: block.startAt, resetsAt: block.resetsAt, firstSeenAt: block.firstSeenAt, peakPct: block.peakPct }));
 
       const newestInstant = newest === null ? null : effectiveAt(newest);
       return {
         windows,
+        past,
         recorder: {
           newestAt: newestInstant,
           ageSeconds:
@@ -113,6 +124,7 @@ export default function contribute(server: PluginServerContext) {
           growthTokensPerHour: growth.get(row.id) ?? null,
           projectedFullAt: projectFull(row.usedTokens!, row.maxTokens!, growth.get(row.id) ?? null, thresholds),
           compactAtPct: profileFor(row.maxTokens!, thresholds).compact,
+          stateWrittenAt: stateWrittenAt(row.id),
         }))
         .sort((a, b) => b.usedPct - a.usedPct);
       return { agents, error: null };
@@ -183,7 +195,7 @@ export default function contribute(server: PluginServerContext) {
 
   server.handle(enrolmentState, async () => {
     const settings = await readSettings();
-    return { showPill: settings.showPill, enabled: settings.enabled, agents: await listEnrolment() };
+    return { showPill: settings.showPill, enabled: settings.enabled, agents: await listEnrolment(), thresholds: settings.thresholds };
   });
 
   server.handle(setEnrolment, async ({ agentId, enrolled }) => ({
@@ -192,9 +204,5 @@ export default function contribute(server: PluginServerContext) {
 
   // The recorder and governor register their timers in this shared lifecycle.
   // Paseo waits for this cleanup before stopping the plugin subprocess.
-  return async () => {
-    removeSessionMcp();
-    const teardowns = lifecycle.teardowns.splice(0);
-    for (const teardown of teardowns) await teardown();
-  };
+  return () => runTeardowns([removeSessionMcp, removeGuard, ...lifecycle.teardowns.splice(0)]);
 }

package/mcp.mjs

@@ -254,6 +254,23 @@ function describeRelative(iso) {
   return ms >= 0 ? `in ${text}` : `${text} ago`;
 }
 
+/**
+ * Session Guard's word on this session, for `budget_status`.
+ *
+ * Read-only, and only for the session asking: the plugin resolves it from
+ * `PASEO_AGENT_ID`, never from anything the model passes. A failure here costs the
+ * extra line, not the budget answer.
+ */
+async function guardSummary() {
+  if (AGENT_ID === null) return [];
+  try {
+    const result = await callPlugin("smart-session.guard.agent", { agentId: AGENT_ID });
+    return Array.isArray(result?.summary) ? result.summary.filter((line) => typeof line === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
 const TOOLS = {
   context_status: {
     description:
@@ -301,15 +318,16 @@ const TOOLS = {
 
   budget_status: {
     description:
-      "How much of the Claude plan's rolling 5-hour and weekly limits is already consumed, how fast, and when each window resets. Call this before spawning several subagents, before a long autonomous run, or when deciding whether to use a more expensive model.",
+      "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", {});
       if (result.error) return `Could not read plan usage: ${result.error}`;
+      const guard = await guardSummary();
       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.";
+      if (interesting.length === 0) return ["No plan-usage reading recorded yet.", ...guard].join("\n");
 
       const lines = interesting.map((window) => {
         const name = window.id === "five_hour" ? "Session (5h)" : window.id === "seven_day" ? "Week" : window.id;
@@ -328,6 +346,7 @@ const TOOLS = {
           `(Newest reading is ${Math.round(HOURS(recorder.ageSeconds * 1000) * 10) / 10}h old — treat these as a floor, not a current number.)`,
         );
       }
+      lines.push(...guard);
       return lines.join("\n");
     },
   },
@@ -435,7 +454,7 @@ const TOOLS = {
       const agentId = requireAgent();
       const settings = readSettings();
       if (!settings.enabled) {
-        return "Smart Compact is switched off for this Paseo install, so nothing would deliver this request. Compact by hand if you need to, or ask the user to turn Smart Compact on in the Smart Session surface.";
+        return "Smart Compact is switched off for this Paseo install, so nothing would deliver this request. Compact by hand if you need to, or ask the user to turn Smart Compact on in the Smart Session screen or Settings → Plugins → Smart Session.";
       }
 
       // Default to this session's own state file: the whole point is that the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {
@@ -20,6 +20,7 @@
   ],
   "files": [
     "paseo-plugin.json",
+    "assets/",
     "index.client.tsx",
     "index.server.ts",
     "client/",

package/paseo-plugin.json

@@ -1,5 +1,16 @@
 {
   "id": "smart-session",
+  "name": "Smart Session",
+  "icon": "assets/icon.png",
+  "description": "See when your plan runs out at this pace, how full each session's context is, and let agents checkpoint and compact themselves. Session Guard pauses work at the session limit and continues it after the reset.",
+  "media": [
+    "docs/media/smart-session-hero.png",
+    "docs/media/smart-session-flow.gif",
+    "docs/media/smart-session-pill.png",
+    "docs/media/smart-session-chat.png",
+    "docs/media/smart-session-guard.png",
+    "docs/media/smart-session-mobile.png"
+  ],
   "requirements": {
     "paseo": ">=0.14.0"
   }

package/server/guard/client.ts

@@ -0,0 +1,27 @@
+import type { Agent, Usage } from "../../shared/guard/policy.ts";
+import type { ListedPlugin } from "./standalone.ts";
+
+/**
+ * The slice of Paseo's daemon client that Session Guard uses, typed.
+ *
+ * It is the same short-lived client `server/daemon.ts` opens for the recorder; this
+ * is only a narrower, typed view of it. The optional members arrived in later daemon
+ * versions, and the engine checks for them before relying on them.
+ */
+export interface GuardClient {
+  fetchAgents(options?: { filter?: { includeArchived?: boolean }; page?: { limit: number; cursor?: string } }): Promise<{
+    entries: readonly { agent: Agent }[];
+    pageInfo?: { hasMore: boolean; nextCursor?: string | null };
+  }>;
+  fetchAgent(agentId: string): Promise<{ agent: Agent } | null>;
+  listProviderUsage(): Promise<Usage>;
+  setWorkspaceLabel?(options: { workspaceId: string; label: { name: string; color: "amber" }; assigned: boolean }): Promise<unknown>;
+  invokePluginRpc?(pluginId: string, method: string, input: unknown): Promise<unknown>;
+  getDaemonStatus?(): Promise<{ pid: number }>;
+  listPlugins?(): Promise<readonly ListedPlugin[]>;
+  listProviderSubagents?(agentId: string): Promise<{ subagents: readonly { status: string }[] }>;
+  cancelAgent(agentId: string): Promise<void>;
+  sendMessage(agentId: string, text: string, options?: { messageId: string; activeTurnBehavior: "steer" }): Promise<unknown>;
+}
+
+export type Connect = <T>(work: (client: GuardClient) => Promise<T>) => Promise<T>;