paseo-smart-session 1.2.6 → 2.1.0

package/README.md

@@ -2,176 +2,87 @@
 
 [![npm version](https://img.shields.io/npm/v/paseo-smart-session?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-smart-session)
 [![npm downloads](https://img.shields.io/npm/dm/paseo-smart-session?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-smart-session)
-[![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.8.0-8A63D2?style=for-the-badge)](https://paseo.sh)
+[![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)
 
-## 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
-
-That history remains useful after an individual session ends or a provider cache changes.
-
 ## Install
 
-Install from npm on Paseo 0.9.0 or newer:
-
 ```sh
-paseo plugin install npm:paseo-smart-session@1.2.6
+paseo plugin install paseo-smart-session
 ```
 
-Paseo 0.8 can install the same plugin from Git:
+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.
 
-```sh
-paseo plugin add tomgrin10/paseo-smart-session --ref v1.2.6
-```
-
-```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 and MCP server. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.
-
-## How an agent uses it
+## Use
 
-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
+| `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 |
 
-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.
+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.
 
-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 composer pill shows whether a session is enrolled in **Smart Compact**.
 
-Every request sends the `/compact` command. The agent can also set:
+## How Smart Compact works
 
-- `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**.
+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.
 
-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.
+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
-
-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/
-```
-
-| 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. |
+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.
 
-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.
+## Data and access
 
-## Password-protected daemons
+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.
 
-When the Paseo daemon requires a password, Smart Session resolves it in this order:
+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.
 
-1. `PASEO_PASSWORD`
-2. The file named by `PASEO_PASSWORD_FILE`
-3. `~/paseo-hub/secrets/daemon-password`
-
-The secret is used only to connect to the daemon. It is never written or logged.
-
-## Develop locally
+## 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 and MCP entries, it does not modify user configuration.
-
-## More Paseo plugins
-
-Also available from [Tom Gringauz](https://github.com/tomgrin10):
-
-- [Defer](https://www.npmjs.com/package/paseo-defer) — Schedule messages to agents for later delivery.
-- [Graphite](https://www.npmjs.com/package/paseo-graphite) — Monitor Graphite stacks and PR action state.
-- [Vitals](https://www.npmjs.com/package/paseo-vitals) — Host, Paseo, agent, and Docker health in one dashboard.
-
 ## License
 
 [MIT](LICENSE) © 2026 Tom Gringauz.
+
+## 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.
+- [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.
+- [Transcript Search](https://github.com/tomgrin10/paseo-transcript-search) — Search conversations across connected hosts.
+- [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/button-visibility.ts

@@ -0,0 +1,32 @@
+import type { PluginClientContext, PluginButtonRegistration } from "@getpaseo/plugin/client";
+import { subscribeDisplay } from "./display";
+
+export function withButtonVisibility(client: PluginClientContext) {
+  const entries = new Set<{ reconcile(): void; remove(): void }>();
+  let enableHeader = true;
+  let enableComposer = true;
+  function gated<K extends "addHeaderButton" | "addComposerPill">(method: K, input: Parameters<PluginClientContext[K]>[0]): PluginButtonRegistration {
+    let descriptor = input.button;
+    let registration: PluginButtonRegistration | undefined;
+    const entry = {
+      reconcile() {
+        const enabled = method === "addHeaderButton" ? enableHeader : enableComposer;
+        if (enabled && !registration) registration = (client[method] as (value: typeof input) => PluginButtonRegistration)({ ...input, button: descriptor });
+        if (!enabled && registration) { registration.remove(); registration = undefined; }
+      },
+      remove() { registration?.remove(); registration = undefined; entries.delete(entry); },
+    };
+    entries.add(entry);
+    entry.reconcile();
+    return { remove: entry.remove, update(patch) { descriptor = { ...descriptor, ...patch }; registration?.update(patch); } };
+  }
+  const buttons = Object.create(client) as PluginClientContext;
+  buttons.addHeaderButton = input => gated("addHeaderButton", input);
+  buttons.addComposerPill = input => gated("addComposerPill", input);
+  const unsubscribe = subscribeDisplay(values => {
+    
+    enableComposer = values.enable_composer_button;
+    for (const entry of entries) entry.reconcile();
+  });
+  return { client: buttons, dispose() { unsubscribe(); for (const entry of [...entries]) entry.remove(); } };
+}

package/client/display.tsx

@@ -0,0 +1,102 @@
+import type { PluginClientContext, PluginSidebarContribution, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { useSettings } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import { useEffect } from "react";
+import { ActivityIndicator, ScrollView, Text, View } from "react-native";
+import { displayPreferences, displayRpc } from "../shared/display";
+import { withNavigation } from "./navigation";
+import { sidebarVisibility } from "./sidebar-visibility";
+
+type Display = import("zod").infer<typeof displayPreferences.schema>;
+const listeners = new Set<(values: Display) => void>();
+export function subscribeDisplay(listener: (values: Display) => void) { listeners.add(listener); return () => { listeners.delete(listener); }; }
+
+function DisplaySettings({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(displayPreferences);
+  const values = settings.status === "ready" ? settings.values : undefined;
+  useEffect(() => {
+    if (values !== undefined) for (const listener of listeners) listener(values);
+  }, [values]);
+
+  if (settings.status === "loading") return <ActivityIndicator accessibilityLabel="Loading display settings" color={theme.colors.foregroundMuted} />;
+  if (settings.status !== "ready") return (
+    <View style={{ gap: 12 }}>
+      <Text style={{ color: theme.colors.statusDanger }}>{settings.error}</Text>
+      <SettingsCard>
+        <SettingsAction label="Try loading the saved settings again" actionLabel="Retry" onPress={() => void settings.reload()} />
+        {settings.status === "invalid" && <SettingsAction label="Replace invalid display settings with defaults" actionLabel="Reset" disabled={settings.saving} onPress={() => void settings.reset()} />}
+
+      </SettingsCard>
+      {settings.saveError && <Text style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
+    </View>
+  );
+
+  return (
+    <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
+    <SettingsSection title="Navigation">
+      <SettingsCard>
+        <SettingsSwitch
+          label="Show in sidebar"
+          hint="Open this plugin from Command-K (Ctrl-K on Windows and Linux) while viewing a workspace or plugin on this host."
+          value={settings.values.showSidebar}
+          disabled={settings.saving}
+          onValueChange={(showSidebar) => void settings.save({ ...settings.values, showSidebar }, settings.revision)}
+        />
+
+        <SettingsSwitch label="Show composer button" hint="Command-K and the sidebar remain available when this button is hidden." value={settings.values.enable_composer_button} disabled={settings.saving} onValueChange={(enable_composer_button) => void settings.save({ ...settings.values, enable_composer_button }, settings.revision)} />
+      </SettingsCard>
+      {settings.saveError && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
+    </SettingsSection>
+    </ScrollView>
+  );
+}
+
+/** Settings notifications reach mounted screens; poll for changes made on other clients. */
+export function contributeDisplay(client: PluginClientContext, item: PluginSidebarContribution) {
+  const sidebar = sidebarVisibility(() => client.addSidebarItem(item));
+  // Paseo 0.10.1 memoizes sidebar route resolution when an installation mounts.
+  // Register synchronously, then reconcile the saved preference, so that an
+  // already-open sidebar route can resolve its surface during that first render.
+  sidebar.set(true);
+  const Settings = withNavigation(DisplaySettings, client, item.surface, "display");
+  const removeSurface = client.addSurface("display-settings", Settings);
+  const removeSettings = client.addSettingsScreen({ id: "display", title: "Display", icon: "PanelLeft", Component: Settings });
+  const removeCommand = client.addCommandCenterItem({
+    id: "display-settings",
+    title: `${item.title}: display settings`,
+    icon: "PanelLeft",
+    keywords: [item.title, "sidebar", "show", "hide", "display", "settings"],
+    context: "global",
+    onSelect({ openSurface }) { openSurface("display-settings"); },
+  });
+  let disposed = false;
+  let pending = false;
+  let generation = 0;
+  const update = (values: Display) => { generation += 1; sidebar.set(values.showSidebar); };
+  listeners.add(update);
+  const refresh = async () => {
+    if (disposed || pending) return;
+    pending = true;
+    const currentGeneration = generation;
+    try {
+      const result = await client.rpc(displayRpc.read, {});
+      if (!disposed && generation === currentGeneration && result.status === "ready") {
+        const parsed = displayPreferences.schema.safeParse(result.values);
+        if (parsed.success) { sidebar.set(parsed.data.showSidebar); for (const listener of listeners) listener(parsed.data); }
+      }
+    } catch {
+      // Retain the last valid preference through temporary disconnects.
+    } finally { pending = false; }
+  };
+  void refresh();
+  const timer = setInterval(() => void refresh(), 5000);
+  return () => {
+    disposed = true;
+    clearInterval(timer);
+    listeners.delete(update);
+    sidebar.dispose();
+    removeSurface();
+    removeSettings();
+    removeCommand();
+  };
+}

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