paseo-smart-session 2.0.0 → 2.1.0

package/README.md

@@ -5,188 +5,84 @@
 [![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.14.0-8A63D2?style=for-the-badge)](https://paseo.sh)
 [![License](https://img.shields.io/github/license/tomgrin10/paseo-smart-session?style=for-the-badge&color=2563eb)](LICENSE)
 
-Give Paseo agents a safe way to manage long-running work.
-
-Smart Session lets an agent see how full its context is, save durable task state, and compact itself when it is ready. It also records session and plan-usage statistics, so you can understand where tokens are going and when limits reset.
+Let agents manage their own long-running work. Smart Session shows an agent how full its context is, lets it save durable task state, and lets it compact itself at a safe stopping point. It also keeps a history of context, plan usage and token spend.
 
 ![A Smart Session compaction handoff: the requested compact preserves the task state, then the resumed session is told to re-read its state file and continue](docs/screenshots/smart-compact-handoff.png)
 
 ## Install
 
-Install from npm using the latest Paseo release:
-
 ```sh
 paseo plugin install paseo-smart-session
 ```
 
-```sh
-paseo plugin ls                    # confirm it is running
-paseo plugin update smart-session
-paseo plugin remove smart-session
-```
-
-On first load, Smart Session registers its Claude Code hooks. Its MCP server is attached by Paseo when an interactive session opens. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.
-
-## What it does
-
-### Lets agents compact themselves
-
-An agent can check how much context it has used, checkpoint the work that must survive a reset, and request compaction when it reaches a safe stopping point. The agent also decides whether another turn should start afterwards and can write the exact follow-up message. A completed task can compact and stop; work in progress can resume from its saved state.
-
-The saved state captures the goal, the current step, decisions already made, and approaches that have already failed. That prevents a resumed agent from redoing work or asking a person how to continue.
-
-Smart Session never chooses to compact an agent by itself. It can let an agent know that context is filling, but the agent decides whether to checkpoint, compact, or defer.
-
-### Shows session and plan usage
-
-Smart Session keeps a local history of:
-
-- Context-window usage for each agent session
-- Claude plan usage, burn rate, and reset times
-- Token spend by model, workspace, and main agent versus subagent
-- Compaction requests and their before/after context sizes
+On first load it registers its Claude Code hooks, touching only entries that point at its own scripts. Paseo attaches its MCP server when an interactive session opens.
 
-That history remains useful after an individual session ends or a provider cache changes.
+## Use
 
-## How an agent uses it
-
-Smart Session exposes these MCP tools to Paseo agents:
+Agents get these tools:
 
 | Tool | What it does |
 | --- | --- |
-| `context_status` | Shows current context usage, filling rate, and relevant thresholds. |
-| `checkpoint` | Writes durable task state for the current session. |
-| `request_compaction` | Queues compaction and chooses whether and how to continue afterwards. |
-| `defer_compaction` | Defers a compaction request and records why. |
-| `budget_status` | Shows plan usage, burn rate, and reset times. |
-
-The usual flow is:
-
-```text
-context_status → checkpoint → request_compaction → stop, or re-read state and continue
-```
-
-`request_compaction` refuses when the state file is missing or stale. The agent can checkpoint and request again in the same turn.
-
-## Smart Compact
-
-Smart Compact is the session-control feature. As a session fills, hooks can provide context notices at useful thresholds. When the compact threshold is reached at the end of a turn, the agent is asked whether it wants to compact.
+| `context_status` | Current context usage, fill rate and thresholds |
+| `checkpoint` | Save durable task state for this session |
+| `request_compaction` | Queue `/compact`, and choose whether and how to continue afterwards |
+| `defer_compaction` | Put off a compaction and record why |
+| `budget_status` | Plan usage, burn rate and reset times, and whether Session Guard will pause this session |
 
-There is no forced compaction. An agent can compact immediately, defer with a reason, or keep working. A request is delivered only when the agent is idle and its state file is current.
+The usual flow is `context_status → checkpoint → request_compaction`, then stop or re-read the state and continue. Saved state holds the goal, current step, decisions made and approaches that failed, so a resumed agent neither redoes work nor asks how to continue.
 
-Every request sends the `/compact` command. The agent can also set:
+The composer pill shows whether a session is enrolled in **Smart Compact**.
 
-- `continue_after_compaction: false` to finish without starting another turn.
-- `continue_after_compaction: true` to start another turn after compaction.
-- `continue_message` to choose the exact follow-up; when omitted, the default tells the agent to re-read the state file and continue from its **Current step**.
+## How Smart Compact works
 
-Omitting the new options preserves the earlier behavior: Smart Session continues with the default state-aware prompt. The durable state wins if it disagrees with the automatic summary. A `/compact` entered by a person never receives a plugin continuation.
+As a session fills, hooks send context notices. At the compact threshold, the agent is asked at the end of its turn whether it wants to compact. Nothing is forced: the agent can compact, defer with a reason, or keep working. A request is delivered only when the agent is idle and its state file is current; `request_compaction` refuses a missing or stale one.
 
-### The composer pill
+After compaction, the agent chooses to stop (`continue_after_compaction: false`), continue with the default prompt to re-read its state, or continue with its own `continue_message`. A `/compact` typed by a person never gets a plugin continuation.
 
-The composer pill shows whether the current session is enrolled:
-
-| State | Meaning |
-| --- | --- |
-| **Smart Compact on** | The session can receive context notices and request compaction. |
-| **Smart Compact off** | The session is not enrolled. |
-
-If Smart Compact is disabled globally, the pill is not shown.
-
-## Settings
-
-| Setting | Default | Description |
+| Setting | Default | |
 | --- | --- | --- |
-| **Smart Compact** | On | Enables context notices and agent-requested compaction. |
-| **Large-window compact threshold** | 30% | Sets when Smart Compact asks on context windows of 400k tokens or more. |
-| **Small-window compact threshold** | 85% | Sets when Smart Compact asks on smaller context windows. |
-| **Enrol sessions automatically** | On | Enrols a session after it writes task state. |
-| **Show the pill on every agent** | On | Shows the Smart Compact control in the composer. |
-| **Register the hooks with Claude Code** | On | Keeps the context and compaction hooks installed. |
+| Smart Compact | On | Context notices and agent-requested compaction |
+| Large-window compact threshold | 30% | Context windows of 400k tokens or more |
+| Small-window compact threshold | 85% | Smaller context windows |
+| Enrol sessions automatically | On | Enrol a session once it writes task state |
+| Show the pill on every agent | On | Composer pill visibility |
+| Register the hooks with Claude Code | On | Keep the context and compaction hooks installed |
 
-The remaining settings apply only while Smart Compact is enabled. Thresholds accept whole percentages from 1% to 99%; lowering one also moves its earlier notice bands down when needed.
+## Session Guard
 
-## Usage history and state
+Session Guard pauses agents at the provider's session limit and continues the same conversations after the reset, even with the app closed. It is the [Session Guard](https://github.com/tomgrin10/paseo-session-guard) plugin folded into Smart Session, and it is **off by default**: turn it on from the overview or **Settings → Plugins → Smart Session → Session Guard**.
 
-Smart Session stores its data under:
+On Linux, Claude and Codex sessions pause in place together with their native subagents; elsewhere the turn is interrupted and one continuation is sent after the reset. Each session gets a pill to opt out or release it, and each pause gets a timeline card with **Resume now** and **Dismiss pause**. For Claude, a reset is confirmed from whichever is fresher, Paseo's cached usage or Smart Session's own recorder.
 
-```text
-$PASEO_HOME/plugin-data/smart-session/
-```
+While the standalone plugin is enabled, Smart Session leaves session protection to it, so a session is never paused twice. Disable or uninstall Session Guard to hand over; per-session choices and waiting pauses in `$PASEO_HOME/plugin-data/session-guard/` carry over. See the [Session Guard guide](docs/session-guard.md) for settings and limits.
 
-| File | Contains |
-| --- | --- |
-| `usage-YYYY-MM.jsonl` | Plan-usage observations and reset times. |
-| `context-YYYY-MM.jsonl` | Context-window usage changes. |
-| `compactions.json` | Compaction requests, continuation choices, and context sizes. |
-| `spend-index.json` | Hourly token spend by model, workspace, and agent type. |
-| `state/<agentId>.md` | Durable task state for one agent. |
-| `settings.json`, `enrolment.json` | Plugin settings and per-session enrolment. |
-
-Usage and context observations are append-only. A damaged line is skipped rather than putting the rest of the history at risk. Existing compaction rows are read as “continue with the default prompt,” so upgrading requires no data migration.
-
-## Password-protected daemons
-
-When the Paseo daemon requires a password, Smart Session resolves it in this order:
+## Data and access
 
-1. `PASEO_PASSWORD`
-2. The file named by `PASEO_PASSWORD_FILE`
-3. `~/paseo-hub/secrets/daemon-password`
+Everything lives in `$PASEO_HOME/plugin-data/smart-session/`: monthly usage and context logs, compaction records, an hourly spend index by model, workspace and agent type, and one `state/<agentId>.md` per agent. Logs are append-only, and a damaged line is skipped rather than risking the rest.
 
-The secret is used only to connect to the daemon. It is never written or logged.
+Paseo plugins run trusted, unsandboxed code on the daemon host. Smart Session reads local Claude Code usage data and talks only to the local daemon. For password-protected daemons it reads `PASEO_PASSWORD`, then `PASEO_PASSWORD_FILE`, then `~/paseo-hub/secrets/daemon-password`, and never writes or logs it.
 
 ## Development
 
 ```sh
-git clone https://github.com/tomgrin10/paseo-smart-session.git
-cd paseo-smart-session
 npm ci
 npm run verify
-paseo plugin install "$PWD"
+paseo plugin install .
+paseo plugin reload smart-session   # after changes
 ```
 
-After editing:
-
-```sh
-npm run verify
-paseo plugin reload smart-session
-```
-
-Reloading the plugin is enough. Do not restart the Paseo daemon: that interrupts every running agent.
-
-## Data and privacy
-
-Smart Session reads local Claude Code usage information and communicates with the local Paseo daemon. Its usage history, settings, and task state stay under `$PASEO_HOME`. Apart from narrowly maintaining its own Claude Code hook entries, it does not modify user configuration. MCP attachment is local to each Paseo session.
-
 ## License
 
 [MIT](LICENSE) © 2026 Tom Gringauz.
 
-## Navigation and display
-
-Open this plugin from Command-K or its sidebar entry. **Overview** and **Display settings** link the main view and settings directly, without opening the Plugins settings page. Hiding a sidebar entry keeps Command-K available.
-
-Display settings can also hide this plugin's workspace header or composer buttons independently. Hidden buttons stay hidden for newly opened workspaces; restoring them retains the latest button status.
-
-## Paseo 0.14 agent integration
-
-The Smart Session MCP attaches automatically when an interactive Claude or Codex session opens, including resume, refresh and import. Normal plugin startup no longer registers a global Claude MCP. Existing global entries are preserved; usage history and checkpoints remain in place. The bridge also respects a custom daemon listen address.
-
-Requires Paseo **0.14.0 or newer**. Agent tools are scoped to interactive Claude
-and Codex sessions; history-only opens receive none. They become available on
-the next idle session open after install or reload. The agent label
-`plugin-tools/enabled: "false"` opts a session out. Existing plugin data and
-settings are retained.
-
 ## Other plugins
 
 - [Defer](https://github.com/tomgrin10/paseo-defer) — Schedule messages for later delivery.
+- [Follow-up](https://github.com/tomgrin10/paseo-follow-up) — Track workspace PRs, remaining tasks and completion.
 - [Graphite](https://github.com/tomgrin10/paseo-graphite) — Graphite stacks and PR status.
-- [Vitals](https://github.com/tomgrin10/paseo-vitals) — Host, agent, and Docker health.
+- [Send to Paseo](https://github.com/tomgrin10/send-to-paseo) — Send GitHub and Graphite PRs to Paseo from Chrome.
 - [Session Guard](https://github.com/tomgrin10/paseo-session-guard) — Pause at session limits and continue after reset.
-- [Transfer](https://github.com/tomgrin10/paseo-transfer) — Copy or move workspaces between hosts.
 - [Transcript Search](https://github.com/tomgrin10/paseo-transcript-search) — Search conversations across connected hosts.
-- [Send to Paseo](https://github.com/tomgrin10/send-to-paseo) — Send GitHub and Graphite PRs to Paseo from Chrome.
-- [Dispatch](https://github.com/tomgrin10/paseo-dispatch) — Route tasks to existing workspaces (development preview).
-
-- [Follow-up](https://github.com/tomgrin10/paseo-follow-up) — Track workspace PRs, remaining tasks and completion.
+- [Transfer](https://github.com/tomgrin10/paseo-transfer) — Copy or move workspaces between hosts.
+- [Vitals](https://github.com/tomgrin10/paseo-vitals) — Host, process, agent and Docker monitoring.
+- [Workspace Switcher](https://github.com/tomgrin10/paseo-switcher) — Arc-style Ctrl+Tab between recent workspaces.

package/assets/LICENSE.lucide

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256"><title>Smart Session</title><rect width="256" height="256" rx="52" fill="#1c2229"/><svg x="52" y="52" xmlns="http://www.w3.org/2000/svg" width="152" height="152" viewBox="0 0 24 24" fill="none" stroke="#f3f0e8" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-gauge" aria-hidden="true"><path d="m12 14 4-4"></path><path d="M3.34 19a10 10 0 1 1 17.32 0"></path></svg></svg>

package/client/agents.ts

@@ -0,0 +1,178 @@
+/**
+ * The one agent directory this client bundle keeps, shared by every composer pill.
+ *
+ * Both the Smart Compact pill and the Session Guard pill need to know which agents
+ * exist and which workspace each sits in, since a pill registration bakes in its
+ * workspace. Following the host's agents twice would open two observations of the
+ * same directory; this opens one and lets each pill read it.
+ *
+ * It must be an *owned* observation, `agents.list({ subscribe: {}, signal })`: bare
+ * `agents.subscribe()` only listens to observations this API instance already holds,
+ * so on its own it never discovers a new agent (RESEARCH.md §5.1). A 0.8 runtime
+ * returns no observation and emits its updates through that local listener instead,
+ * so the listener stays attached until an owned observation replaces it.
+ */
+
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+
+export interface DirectoryAgent {
+  readonly workspaceId: string;
+  /** Closed or archived: still listed, but no longer a session anyone is working in. */
+  readonly closed: boolean;
+}
+
+export interface AgentDirectory {
+  current(): ReadonlyMap<string, DirectoryAgent>;
+  /** Called after every change; read `current()` for the new state. */
+  subscribe(listener: () => void): () => void;
+  /** Releases the observation. Safe to call more than once. */
+  dispose(): Promise<void>;
+}
+
+/** The lean shapes this needs from the agent directory, which carries far more. */
+interface ListedAgent {
+  readonly id?: string;
+  readonly workspaceId?: string | null;
+  readonly status?: string;
+  readonly archivedAt?: 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>;
+  };
+}
+
+function entryOf(agent: ListedAgent | undefined): [string, DirectoryAgent] | null {
+  if (typeof agent?.id !== "string" || typeof agent.workspaceId !== "string" || agent.workspaceId === "") return null;
+  return [agent.id, { workspaceId: agent.workspaceId, closed: agent.status === "closed" || !!agent.archivedAt }];
+}
+
+function same(a: DirectoryAgent | undefined, b: DirectoryAgent): boolean {
+  return a !== undefined && a.workspaceId === b.workspaceId && a.closed === b.closed;
+}
+
+export function observeAgents(client: PluginClientContext): AgentDirectory {
+  const agents = new Map<string, DirectoryAgent>();
+  const listeners = new Set<() => void>();
+  const lifetime = new AbortController();
+  let stopped = false;
+  let unsubscribeOwnedObservation: (() => void) | null = null;
+  let releaseObservation: (() => Promise<void>) | null = null;
+
+  const notify = () => {
+    for (const listener of [...listeners]) listener();
+  };
+
+  function upsert(agent: ListedAgent | undefined): boolean {
+    const entry = entryOf(agent);
+    if (entry === null || same(agents.get(entry[0]), entry[1])) return false;
+    agents.set(entry[0], entry[1]);
+    return true;
+  }
+
+  function apply(update: AgentUpdate): void {
+    if (stopped) return;
+    if (update.kind === "remove") {
+      if (typeof update.agentId === "string" && agents.delete(update.agentId)) notify();
+      return;
+    }
+    if (upsert(update.agent)) notify();
+  }
+
+  /** The legacy listener is live while the snapshot is in flight, so bootstrap is additive. */
+  function add(entries: AgentListing["entries"]): void {
+    let changed = false;
+    for (const entry of entries ?? []) changed = upsert(entry.agent) || changed;
+    if (changed) notify();
+  }
+
+  /** A restored observation replaces its directory snapshot, including removals. */
+  function replace(entries: AgentListing["entries"]): void {
+    const present = new Set<string>();
+    let changed = false;
+    for (const entry of entries ?? []) {
+      const parsed = entryOf(entry.agent);
+      if (parsed === null) continue;
+      present.add(parsed[0]);
+      changed = upsert(entry.agent) || changed;
+    }
+    for (const agentId of [...agents.keys()]) {
+      if (!present.has(agentId)) {
+        agents.delete(agentId);
+        changed = true;
+      }
+    }
+    if (changed) notify();
+  }
+
+  let unsubscribeLegacy: (() => void) | null = client.paseo.agents.subscribe((update) => apply(update as AgentUpdate));
+
+  void (async () => {
+    try {
+      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;
+      }
+      releaseObservation = release;
+      add(listing.entries);
+      if (listing.subscription) {
+        unsubscribeOwnedObservation = listing.subscription.subscribe({
+          snapshot(snapshot) {
+            if (!stopped) replace(snapshot.entries);
+          },
+          update(message) {
+            if (message.type === "agent_update" && message.payload) apply(message.payload);
+          },
+        });
+        unsubscribeLegacy?.();
+        unsubscribeLegacy = null;
+      }
+    } catch {
+      const release = releaseObservation;
+      releaseObservation = null;
+      await release?.().catch(() => undefined);
+      // Not fatal to the rest of the client contribution; a reload can retry.
+    }
+  })();
+
+  return {
+    current: () => agents,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async dispose() {
+      stopped = true;
+      lifetime.abort();
+      unsubscribeLegacy?.();
+      unsubscribeLegacy = null;
+      unsubscribeOwnedObservation?.();
+      unsubscribeOwnedObservation = null;
+      listeners.clear();
+      agents.clear();
+      const release = releaseObservation;
+      releaseObservation = null;
+      await release?.().catch(() => undefined);
+    },
+  };
+}

package/client/guard/index.tsx

@@ -0,0 +1,50 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { ScrollView } from "react-native";
+
+import { TimelineDataSchema } from "../../shared/guard/timeline.ts";
+import type { AgentDirectory } from "../agents.ts";
+import { withNavigation } from "../navigation.tsx";
+import { PausedSessions } from "./paused.tsx";
+import { guardPillIcons } from "./pill-icons.tsx";
+import { contributePills } from "./pills.ts";
+import { GuardSettings } from "./settings.tsx";
+import { GUARD_SURFACES } from "./surfaces.ts";
+import { GuardTimelineItem } from "./timeline.tsx";
+
+/** Session Guard's client half: its settings, paused-sessions list, timeline cards and pill. */
+export function contributeGuardClient(client: PluginClientContext, agents: AgentDirectory, home: string) {
+  const openPaused = () => client.openSurface(GUARD_SURFACES.paused);
+  const openSettings = () => client.openSurface(GUARD_SURFACES.settings);
+  const Settings = withNavigation((props) => (
+    <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16 }}>
+      <GuardSettings {...props} openOverview={openPaused} />
+    </ScrollView>
+  ), client, home, "session-guard");
+  const Paused = withNavigation((props) => <PausedSessions {...props} openSettings={openSettings} />, client, home, "session-guard");
+
+  const removers = [
+    client.addSurface(GUARD_SURFACES.settings, Settings),
+    client.addSurface(GUARD_SURFACES.paused, Paused),
+    client.addSettingsScreen({ id: "session-guard", title: "Session Guard", icon: "ShieldCheck", Component: Settings }),
+    client.addCommandCenterItem({
+      id: "session-guard-settings", title: "Session Guard: settings", icon: "ShieldCheck",
+      keywords: ["quota", "limit", "reset", "pause", "resume", "protection", "session guard"], context: "global",
+      onSelect({ openSurface }) { openSurface(GUARD_SURFACES.settings); },
+    }),
+    client.addCommandCenterItem({
+      id: "session-guard-paused", title: "Session Guard: paused sessions", icon: "Pause",
+      keywords: ["quota", "waiting", "reset", "resume", "subagents", "session guard"], context: "global",
+      onSelect({ openSurface }) { openSurface(GUARD_SURFACES.paused); },
+    }),
+    // The kind and version the standalone plugin wrote, so a pause it recorded and this
+    // plugin later delivers renders the same card.
+    client.addTimelineRenderer({
+      kind: "quota-pause", version: 1, schema: TimelineDataSchema,
+      Component: (props) => <GuardTimelineItem {...props} openOverview={openPaused} />,
+    }),
+    contributePills(client, agents, guardPillIcons),
+  ];
+  return () => {
+    for (const remove of removers.splice(0)) remove();
+  };
+}

package/client/guard/paused.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useRef, useState } from "react";
+import { ActivityIndicator, Text, View } from "react-native";
+import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection } from "@getpaseo/plugin/client/ui";
+import { cancelResumeRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import { governorNotice, pauseOwnerNote, pausedSessions, pausePresentation } from "../../shared/guard/presentation.ts";
+
+export function PausedSessions({ theme, host, layout, navigation, openSettings }: PluginSurfaceProps & { openSettings(): void }) {
+  const read = useRpc(statusRpc);
+  const cancel = useRpc(cancelResumeRpc);
+  const [status, setStatus] = useState<Awaited<ReturnType<typeof read>> | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
+  const refresh = useRef<() => Promise<void>>(async () => {});
+  useEffect(() => {
+    let stopped = false, fetching = false;
+    const fetch = async () => {
+      if (fetching || stopped) return;
+      fetching = true;
+      try { const next = await read({}); if (!stopped) { setStatus(next); setLoadError(null); } }
+      catch { if (!stopped) setLoadError("Could not refresh paused sessions. Showing the last report; retrying automatically."); }
+      finally { fetching = false; }
+    };
+    refresh.current = fetch;
+    void fetch(); const timer = setInterval(() => void fetch(), 5000);
+    return () => { stopped = true; clearInterval(timer); };
+  }, [read]);
+  const release = async (agentId: string) => {
+    if (busy) return;
+    setBusy(agentId);
+    try { await cancel({ agentId }); await refresh.current(); setActionError(null); }
+    catch { setActionError("Could not change this pause. Refresh the list and try again."); }
+    finally { setBusy(null); }
+  };
+  const all = status ? pausedSessions(status.pauses) : [];
+  const visible = status ? pausedSessions(status.pauses, query) : [];
+  const attention = visible.filter(p => p.phase === "attention");
+  const waiting = visible.filter(p => p.phase !== "attention");
+  const muted = { color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 20 };
+  // Both plugins share one state file: when this one is not governing, the list is
+  // the other plugin's (or a leftover), and its controls would only fail.
+  const notice = status ? governorNotice(status) : null;
+  const owner = status ? pauseOwnerNote(status) : null;
+  const row = (pause: typeof all[number]) => {
+    const presentation = pausePresentation(pause, status!.policy);
+    const hint = `${pause.provider} · ${pause.agentId.slice(0, 8)} · ${presentation.coverage}\n${presentation.resetLabel}\n${owner ?? presentation.state}${pause.note ? `\n${pause.note}` : ""}`;
+    return <View key={pause.id}>
+      {navigation ? <SettingsAction label={presentation.title} hint={hint} actionLabel="Open session" onPress={() => navigation.openAgent({ agentId: pause.agentId, serverId: host.id })} />
+        : <SettingsRow label={presentation.title} hint={hint} />}
+      {owner === null && <SettingsAction label={busy === pause.agentId ? "Updating this pause…" : "Manual control"} hint={presentation.actionHint} actionLabel={presentation.actionLabel} disabled={busy !== null} onPress={() => void release(pause.agentId)} />}
+    </View>;
+  };
+  return <ScrollView contentContainerStyle={{ padding: layout.compact ? 16 : 24, paddingBottom: 40 }}>
+    <View style={{ width: "100%", maxWidth: 760, alignSelf: "center", gap: 24 }}>
+      <View style={{ gap: 8 }}>
+        <Text accessibilityRole="header" style={{ color: theme.colors.foreground, fontSize: 22, fontWeight: "600" }}>Paused sessions</Text>
+        <Text style={muted}>All Session Guard pauses on {host.label}. Native subagents are included with their parent session.</Text>
+      </View>
+      {!status && !loadError && <ActivityIndicator accessibilityLabel="Loading paused sessions" color={theme.colors.foregroundMuted} />}
+      {notice && <SettingsCard><SettingsAction label={notice.title} hint={notice.hint} actionLabel="Settings" onPress={openSettings} /></SettingsCard>}
+      {status && !notice && <SettingsCard><SettingsAction label={`${all.length} ${all.length === 1 ? "session" : "sessions"} in Session Guard${all.some(p => p.phase === "attention") ? " · attention needed" : ""}`} hint={status.checkedAt ? `Last checked ${new Date(status.checkedAt).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })} · refreshes automatically` : "Waiting for the first usage check"} actionLabel="Refresh" onPress={() => void refresh.current()} /></SettingsCard>}
+      {(all.length > 5 || query !== "") && <SettingsCard><SettingsInput label="Find a paused session" placeholder="Title or provider" initialValue="" onChangeText={setQuery} /></SettingsCard>}
+      {status && all.length === 0 && !notice && <SettingsCard><SettingsRow label="No sessions are paused" hint="When a protected session reaches its limit, it appears here and receives a timeline entry." /></SettingsCard>}
+      {status && all.length > 0 && visible.length === 0 && <SettingsCard><SettingsRow label="No matching paused sessions" hint="Try another title or provider." /></SettingsCard>}
+      {owner && visible.length > 0 && <SettingsSection title={`Not managed by Smart Session (${visible.length})`}><SettingsCard>{visible.map(row)}</SettingsCard></SettingsSection>}
+      {!owner && attention.length > 0 && <SettingsSection title={`Needs attention (${attention.length})`}><SettingsCard>{attention.map(row)}</SettingsCard></SettingsSection>}
+      {!owner && waiting.length > 0 && <SettingsSection title={`Waiting for reset (${waiting.length})`}><SettingsCard>{waiting.map(row)}</SettingsCard></SettingsSection>}
+      <SettingsCard><SettingsAction label="Protection and timing" hint="Configure the default, native subagents, and automatic resume." actionLabel="Settings" onPress={openSettings} /></SettingsCard>
+      {loadError && <Text accessibilityRole="alert" style={{ ...muted, color: theme.colors.statusDanger }}>{status ? loadError : "Could not load paused sessions. Retrying automatically."}</Text>}
+      {actionError && <Text accessibilityRole="alert" style={{ ...muted, color: theme.colors.statusDanger }}>{actionError}</Text>}
+      {status?.error && !notice && <Text accessibilityRole="alert" style={{ ...muted, color: theme.colors.statusDanger }}>{status.error}</Text>}
+    </View>
+  </ScrollView>;
+}

package/client/guard/pill-icons.tsx

@@ -0,0 +1,26 @@
+import type { PluginButtonIcon, PluginButtonIconProps } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+
+// Like Smart Compact, keep the host's pill chrome and color the icon slot.
+function GuardOnIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="ShieldCheck" size={size} color={theme.colors.statusSuccess} />;
+}
+
+function GuardOffIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="ShieldOff" size={size} color={theme.colors.foregroundMuted} />;
+}
+
+function GuardPausedIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="Pause" size={size} color={theme.colors.statusWarning} />;
+}
+
+function GuardAttentionIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="TriangleAlert" size={size} color={theme.colors.statusDanger} />;
+}
+
+export const guardPillIcons: Readonly<Record<string, PluginButtonIcon>> = {
+  ShieldCheck: GuardOnIcon,
+  ShieldOff: GuardOffIcon,
+  Pause: GuardPausedIcon,
+  TriangleAlert: GuardAttentionIcon,
+};