paseo-smart-session 1.2.6 → 2.1.0

package/client/pill.tsx

@@ -24,6 +24,7 @@ import { Text, View } from "react-native";
 
 import { smartCompactLabel } from "../shared/format";
 import { enrolmentState, setEnrolment, type EnrolmentState } from "../shared/governor";
+import type { AgentDirectory } from "./agents";
 
 /** How often the client re-reads enrolment, for changes made somewhere else. */
 const REFRESH_MS = 20_000;
@@ -197,29 +198,6 @@ function AutoCompactIcon({
   return <Icon name="FoldVertical" size={size} color={color} />;
 }
 
-/** The lean shapes this needs from the agent directory, which carries far more. */
-interface ListedAgent {
-  readonly id?: string;
-  readonly workspaceId?: string | null;
-}
-
-interface AgentUpdate {
-  readonly kind: "remove" | "upsert";
-  readonly agentId?: string;
-  readonly agent?: ListedAgent;
-}
-
-interface AgentListing {
-  readonly entries?: readonly { readonly agent?: ListedAgent }[];
-  readonly subscription?: {
-    subscribe(observer: {
-      snapshot(listing: AgentListing): void;
-      update(message: { readonly type?: string; readonly payload?: AgentUpdate }): void;
-    }): () => void;
-    release(): Promise<void>;
-  };
-}
-
 /**
  * The published 0.8 descriptor API returns this handle. The 0.8.0-beta.1 npm
  * package and app still return the legacy remover function, so registrations
@@ -242,13 +220,9 @@ function updatePill(handle: PillHandle, title: string): void {
   if (typeof handle !== "function") handle.update({ title });
 }
 
-export function contributeClient(client: PluginClientContext) {
+export function contributeClient(client: PluginClientContext, agents: AgentDirectory) {
   /** Every agent this app knows of, and its pill registration while one is up. */
   const tracked = new Map<string, { workspaceId: string; handle: PillHandle | null }>();
-  const lifetime = new AbortController();
-  let stopped = false;
-  let unsubscribeOwnedObservation: (() => void) | null = null;
-  let releaseAgentObservation: (() => Promise<void>) | null = null;
 
   function register(agentId: string, entry: { workspaceId: string; handle: PillHandle | null }): void {
     const toggle = async () => {
@@ -321,114 +295,28 @@ export function contributeClient(client: PluginClientContext) {
     tracked.delete(agentId);
   }
 
-  function applyAgentUpdate(update: AgentUpdate): void {
-    if (update.kind === "remove") {
-      if (typeof update.agentId === "string") forget(update.agentId);
-      return;
-    }
-    const agent = update.agent;
-    if (
-      typeof agent?.id !== "string" ||
-      typeof agent.workspaceId !== "string" ||
-      agent.workspaceId === ""
-    ) return;
-    track(agent.id, agent.workspaceId);
-  }
-
-  function trackAgents(entries: AgentListing["entries"]): Set<string> {
-    const present = new Set<string>();
-    for (const entry of entries ?? []) {
-      const agent = entry.agent;
-      if (
-        typeof agent?.id !== "string" ||
-        typeof agent.workspaceId !== "string" ||
-        agent.workspaceId === ""
-      ) continue;
-      present.add(agent.id);
-      track(agent.id, agent.workspaceId);
-    }
-    return present;
-  }
-
-  /** A restored observation replaces its directory snapshot, including removals. */
-  function replaceAgents(entries: AgentListing["entries"]): void {
-    const present = trackAgents(entries);
-    for (const agentId of [...tracked.keys()]) {
-      if (!present.has(agentId)) forget(agentId);
+  /** Follows the shared directory: new agents gain a pill, moved or removed ones lose theirs. */
+  function followDirectory(): void {
+    const current = agents.current();
+    for (const [agentId, entry] of [...tracked]) {
+      if (current.get(agentId)?.workspaceId !== entry.workspaceId) forget(agentId);
     }
+    for (const [agentId, agent] of current) track(agentId, agent.workspaceId);
   }
 
   const refresh = () => refreshPills(() => client.rpc(enrolmentState, {}));
 
   const unsubscribeStore = subscribe(sync);
-
-  // v0.8 returns only the listing and emits its subscribed updates through this
-  // local listener. Keep it attached until a newer runtime gives us the owned
-  // observation whose snapshots can reconcile the whole directory on reconnect.
-  let unsubscribeLegacyAgents: (() => void) | null = client.paseo.agents.subscribe((update) => {
-    applyAgentUpdate(update as AgentUpdate);
-  });
-
-  // The subscription only carries agents that report in from now on, and an idle
-  // one may not do that for hours.
-  void (async () => {
-    try {
-      // `agents.subscribe()` listens only to observations already owned by
-      // this API instance. A plain list stopped receiving newly created agents
-      // in Paseo 0.9, which made both plugin pills disappear on new sessions.
-      const listAgents = client.paseo.agents.list as unknown as (options: {
-        subscribe: Record<string, never>;
-        signal: AbortSignal;
-      }) => Promise<AgentListing>;
-      const listing = await listAgents({ subscribe: {}, signal: lifetime.signal });
-      const release = listing.subscription
-        ? () => listing.subscription!.release()
-        : null;
-      if (stopped) {
-        await release?.();
-        return;
-      }
-      releaseAgentObservation = release;
-      // The legacy listener was already live while this snapshot was in flight,
-      // so bootstrap must be additive or it can erase a just-created agent.
-      trackAgents(listing.entries);
-      if (listing.subscription) {
-        unsubscribeOwnedObservation = listing.subscription.subscribe({
-          snapshot(snapshot) {
-            if (!stopped) replaceAgents(snapshot.entries);
-          },
-          update(message) {
-            if (!stopped && message.type === "agent_update" && message.payload) {
-              applyAgentUpdate(message.payload);
-            }
-          },
-        });
-        unsubscribeLegacyAgents?.();
-        unsubscribeLegacyAgents = null;
-      }
-    } catch {
-      const release = releaseAgentObservation;
-      releaseAgentObservation = null;
-      await release?.().catch(() => undefined);
-      // Not fatal to the rest of the client contribution; a reload can retry.
-    }
-  })();
+  const unsubscribeAgents = agents.subscribe(followDirectory);
+  followDirectory();
 
   void refresh().catch(() => undefined);
   const timer = setInterval(() => void refresh().catch(() => undefined), REFRESH_MS);
 
-  return async () => {
-    stopped = true;
-    lifetime.abort();
+  return () => {
     clearInterval(timer);
-    unsubscribeLegacyAgents?.();
-    unsubscribeLegacyAgents = null;
-    unsubscribeOwnedObservation?.();
-    unsubscribeOwnedObservation = null;
+    unsubscribeAgents();
     unsubscribeStore();
     for (const agentId of [...tracked.keys()]) forget(agentId);
-    const release = releaseAgentObservation;
-    releaseAgentObservation = null;
-    await release?.().catch(() => undefined);
   };
 }

package/client/sidebar-visibility.ts

@@ -0,0 +1,21 @@
+/** Own one sidebar registration; late reads cannot register after teardown. */
+export function sidebarVisibility(register: () => (() => void) | void) {
+  let disposed = false;
+  let remove: (() => void) | undefined;
+  return {
+    set(visible: boolean) {
+      if (disposed) return;
+      if (visible && !remove) remove = register() ?? (() => {});
+      if (!visible && remove) {
+        remove();
+        remove = undefined;
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      remove?.();
+      remove = undefined;
+    },
+  };
+}

package/client/surface.tsx

@@ -1,4 +1,4 @@
-import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client";
+import { type PluginSurfaceProps, useRpc, useSettings } from "@getpaseo/plugin/client";
 import { Icon, useToast } from "@getpaseo/plugin/client/react-native";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import React, { useEffect, useState } from "react";
@@ -17,6 +17,11 @@ import {
   spendSummary,
 } from "../shared/smart-session";
 import { withCompactThreshold } from "../shared/thresholds";
+import { guardPreferences, statusRpc as guardStatus } from "../shared/guard/contracts";
+import { isPending } from "../shared/guard/policy";
+import { governorNotice, pauseOwnerNote, pausedSessions, pausePresentation } from "../shared/guard/presentation";
+import { refreshGuardPills } from "./guard/pills";
+import { GUARD_SURFACES } from "./guard/surfaces";
 
 type Theme = PluginSurfaceProps["theme"];
 
@@ -236,7 +241,85 @@ function CompactThreshold({
   );
 }
 
-export function SmartSessionSurface({ theme, layout }: PluginSurfaceProps) {
+/** A quiet text link, for the places this section points to rather than controls. */
+function Link({ theme, label, onPress }: { theme: Theme; label: string; onPress: () => void }) {
+  return (
+    <Pressable accessibilityRole="link" onPress={onPress} style={({ pressed }) => ({ minHeight: 32, justifyContent: "center", opacity: pressed ? 0.6 : 1 })}>
+      <Text style={{ color: theme.colors.foreground, fontSize: 12, textDecorationLine: "underline" }}>{label}</Text>
+    </Pressable>
+  );
+}
+
+/**
+ * Session Guard, in brief: whether it is on, who is running it, and what is paused.
+ *
+ * The full controls live on its own settings screen; this is the switch and the
+ * answer to "is anything waiting for a reset", next to the plan limits that cause it.
+ */
+function SessionGuardSection({ theme, openSurface }: { theme: Theme; openSurface?: (id: string) => void }) {
+  const settings = useSettings(guardPreferences);
+  const readStatus = useRpc(guardStatus);
+  const toast = useToast();
+  const statusQuery = useQuery({ queryKey: ["smart-session", "guard"], queryFn: () => readStatus({}), refetchInterval: 15_000 });
+  const status = statusQuery.data;
+  const values = settings.status === "ready" ? settings.values : undefined;
+  // A change made here or on another client moves the pills without waiting out their poll.
+  useEffect(() => {
+    if (values !== undefined) refreshGuardPills();
+  }, [values]);
+  if (settings.status !== "ready") return null;
+  const policy = settings.values;
+  const waiting = status === undefined ? [] : pausedSessions(status.pauses);
+
+  function toggle() {
+    if (settings.status !== "ready") return;
+    const next = !settings.values.enabled;
+    void settings.save({ ...settings.values, enabled: next }, settings.revision).then((saved) => {
+      if (!saved) return toast.error("Session Guard could not be changed. Try again.");
+      toast.show(next ? "Session Guard on" : "Session Guard off");
+      void statusQuery.refetch();
+    });
+  }
+
+  const owned = status?.governor === "active";
+  const owner = status === undefined ? null : pauseOwnerNote(status);
+  const notice = status === undefined ? null : governorNotice(status);
+  const count = `${waiting.length} paused session${waiting.length === 1 ? "" : "s"}`;
+  const detail = !policy.enabled
+    ? waiting.length > 0 && owned
+      ? `Off. ${count} still ${waiting.length === 1 ? "waits" : "wait"} for the reset; cancel ${waiting.length === 1 ? "it" : "them"} from Paused sessions, or turn this back on.`
+      : waiting.length > 0
+        ? `Off. ${count} below ${waiting.length === 1 ? "was" : "were"} saved by the standalone Session Guard plugin and ${waiting.length === 1 ? "is" : "are"} not managed here.`
+        : `Off. Turn on to pause sessions at ${policy.thresholdPct}% of the provider's session window and continue them in the same conversation after it resets.`
+    : !owned && notice !== null && status?.governor !== "off"
+      ? `On, but not pausing anything here. ${notice.hint}`
+      : `On. ${policy.protectByDefault ? "Every session" : "Each session you opt in"} pauses at ${policy.thresholdPct}% of the session window${
+          policy.includeNativeSubagents ? ", native subagents included," : ""
+        } and ${policy.autoResume ? "continues by itself" : "waits for you"} after the reset.`;
+
+  return (
+    <Section theme={theme} title="Session Guard">
+      <Toggle theme={theme} on={policy.enabled} label="Session Guard" detail={detail} onPress={toggle} disabled={settings.saving} />
+      {waiting.map((pause) => {
+        const presentation = pausePresentation(pause, status!.policy);
+        return (
+          <View key={pause.id} style={{ paddingVertical: 6, gap: 2 }}>
+            <Text style={{ color: pause.phase === "attention" ? theme.colors.statusDanger : theme.colors.foreground }}>{presentation.title}</Text>
+            <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>{`${owner ?? presentation.state} · ${presentation.resetLabel}`}</Text>
+          </View>
+        );
+      })}
+      {openSurface === undefined ? null : (
+        <View style={{ flexDirection: "row", gap: 16, flexWrap: "wrap", marginTop: 4 }}>
+          {status?.pauses.some(isPending) ? <Link theme={theme} label="Paused sessions" onPress={() => openSurface(GUARD_SURFACES.paused)} /> : null}
+          <Link theme={theme} label="Session Guard settings" onPress={() => openSurface(GUARD_SURFACES.settings)} />
+        </View>
+      )}
+    </Section>
+  );
+}
+
+export function SmartSessionSurface({ theme, layout, openSurface }: PluginSurfaceProps & { openSurface?: (id: string) => void }) {
   const budget = useRpc(budgetStatus);
   const context = useRpc(contextStatus);
   const spend = useRpc(spendSummary);
@@ -536,7 +619,7 @@ export function SmartSessionSurface({ theme, layout }: PluginSurfaceProps) {
                     : install.pluginDir === null
                       ? "Not registered. Nothing will ask a session to compact itself."
                       : `Registered: ${install.hooks.join(", ")}. Only entries pointing at this plugin are touched; the MCP server is ${
-                          install.mcp === "unavailable" ? "not registered — the claude CLI was not reachable" : "registered"
+                          install.mcp === "session" ? "attached when a Paseo session opens" : install.mcp === "unavailable" ? "not registered — the claude CLI was not reachable" : "registered"
                         }.`
               }
               onPress={toggleInstallHooks}
@@ -555,6 +638,8 @@ export function SmartSessionSurface({ theme, layout }: PluginSurfaceProps) {
         </Section>
       )}
 
+      <SessionGuardSection theme={theme} openSurface={openSurface} />
+
       {recorder === undefined ? null : (
         <Section theme={theme} title="Recorder">
           <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>

package/docs/navigation-verification.md

@@ -0,0 +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.
+
+- 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.
+
+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** sidebar view gathers every Session Guard pause on the selected host. It shows session titles and identifiers, providers, native coverage, expected reset times, and automatic/manual resume state. Uncertain stops are grouped under **Needs attention**. Open a session or manage its pause directly; search appears when the list is busy. You can also open the overview through Command Center, settings, or a timeline entry. 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, including quota/reset details and whether native subagents are covered. 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.
+
+Like Smart Compact, the pill uses a state-colored icon: green when protected, muted when off, amber when paused, and red when inspection is needed. 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,13 +1,20 @@
+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 { contributeGuardClient } from "./client/guard/index";
 import { contributeClient, refreshPills } from "./client/pill";
 import { SmartSessionSurface } from "./client/surface";
 import { enrolmentState } from "./shared/governor";
 import { getSettings, setSettings } from "./shared/smart-session";
 
-export default function contribute(client: PluginClientContext) {
-  client.addSurface("overview", SmartSessionSurface);
-  client.addSidebarItem({
+export default function contribute(host: PluginClientContext) {
+  const visibility = withButtonVisibility(host);
+  const client = visibility.client;
+  client.addSurface("overview", withNavigation((props) => <SmartSessionSurface {...props} openSurface={client.openSurface} />, client, "overview"));
+  const removeDisplay = contributeDisplay(client, {
     id: "smart-session",
     title: "Smart Session",
     icon: "Gauge",
@@ -38,5 +45,9 @@ export default function contribute(client: PluginClientContext) {
     },
   });
 
-  return contributeClient(client);
+  // One agent observation for every pill in this bundle.
+  const agents = observeAgents(client);
+  const removeClient = contributeClient(client, agents);
+  const removeGuard = contributeGuardClient(client, agents, "overview");
+  return () => { removeGuard(); removeClient(); visibility.dispose(); removeDisplay(); return agents.dispose(); };
 }

package/index.server.ts

@@ -1,3 +1,6 @@
+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";
 
 import { readAgents, withDaemon } from "./server/daemon.ts";
@@ -23,7 +26,7 @@ import {
   setEnrolment,
 } from "./shared/governor.ts";
 import { burnRatePctPerHour, projectedExhaustion, segmentBlocks } from "./shared/blocks.ts";
-import { lifecycle } from "./shared/lifecycle.ts";
+import { lifecycle, runTeardowns } from "./shared/lifecycle.ts";
 import { profileFor } from "./shared/thresholds.ts";
 import { effectiveAt } from "./shared/usage.ts";
 
@@ -38,6 +41,10 @@ import { queue } from "./server/governor.ts";
 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;
@@ -188,8 +195,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 () => {
-    const teardowns = lifecycle.teardowns.splice(0);
-    for (const teardown of teardowns) await teardown();
-  };
+  return () => runTeardowns([removeSessionMcp, removeGuard, ...lifecycle.teardowns.splice(0)]);
 }

package/mcp.mjs

@@ -134,11 +134,21 @@ function findPaseoCli() {
   return null;
 }
 
+function daemonUrl() {
+  if (process.env.PASEO_DAEMON_URL) return process.env.PASEO_DAEMON_URL;
+  const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+  try {
+    const config = JSON.parse(readFileSync(join(home, "config.json"), "utf8"));
+    if (typeof config.daemon?.listen === "string") return `ws://${config.daemon.listen}/ws`;
+  } catch { /* Use the documented default when configuration is absent. */ }
+  return "ws://127.0.0.1:6767/ws";
+}
+
 async function callPlugin(method, input) {
   const { DaemonClient } = await loadDaemonClient();
   const password = await resolveDaemonPassword();
   const client = new DaemonClient({
-    url: process.env.PASEO_DAEMON_URL ?? "ws://127.0.0.1:6767/ws",
+    url: daemonUrl(),
     clientId: "smart-session-mcp",
     clientType: "cli",
     reconnect: { enabled: false },
@@ -244,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:
@@ -291,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;
@@ -318,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");
     },
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "1.2.6",
+  "version": "2.1.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/",
@@ -33,13 +34,13 @@
     "typecheck": "tsc --noEmit",
     "test": "node --test --experimental-strip-types *.test.ts",
     "check": "node check-bundles.mjs && node check-gitinstall.mjs && node check-teardown.mjs && node check-mcp-resolve.mjs",
-    "verify": "npm run typecheck && npm run test && npm run check"
+    "verify": "npm run typecheck && npm run test && npm run check && node --test button-visibility.test.mjs"
   },
   "devDependencies": {
     "@babel/parser": "^8.0.4",
-    "@getpaseo/client": "0.8.0-beta.1",
-    "@getpaseo/plugin": "0.8.0-beta.1",
-    "@getpaseo/protocol": "0.8.0-beta.1",
+    "@getpaseo/client": "0.14.0",
+    "@getpaseo/plugin": "0.14.0",
+    "@getpaseo/protocol": "0.14.0",
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^22.10.2",
     "@types/react": "~19.2.0",

package/paseo-plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "smart-session",
+  "icon": "assets/icon.png",
   "requirements": {
-    "paseo": ">=0.8.0"
+    "paseo": ">=0.14.0"
   }
 }