paseo-smart-session 2.0.0 → 2.2.0

package/README.md

@@ -5,188 +5,113 @@
 [![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.
+Know when your plan runs out, and let agents manage their own long-running work. Smart Session records your Claude plan usage and turns it into a forecast ("Session runs out around 5:40 PM"), shows how full each session's context is, lets an agent save its task state and compact itself at a safe point, and with Session Guard pauses work at the session limit and continues it after the reset.
 
-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.
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="docs/media/smart-session-hero-light.png">
+  <img alt="The Smart Session screen: the headline Session runs out around 8:55 PM, 44m before the 9:39 PM reset. Below it the session window at 77% with a chart of this window's usage and the projection crossing 100% before the reset, the earlier session windows of the last 14 days, the week and the Opus week, then each session's context with its compact line" src="docs/media/smart-session-hero.png">
+</picture>
 
-![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)
+Screenshots use synthetic usage history and sessions.
 
 ## 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
+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.
 
-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.
+## Use
 
-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** in the sidebar opens the overview. Its headline says when the session window runs out at the current pace, or that it lasts until the reset.
 
-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.
+- **Plan limits.** Each window (the 5-hour session, the week, per-model weekly caps) shows how much is used, when it resets, and where it lands at the current pace: a faint extension of the meter, and a tick where an even pace would be. The session window adds a chart of its recorded usage and the projection to the reset, plus every session window of the last 14 days, so you can see how often you hit the limit.
+- **Session context.** Every open session with its share of the context window, the line where Smart Compact asks it to compact, how fast it is filling, and whether it is enrolled. Press a row to open the session.
+- **Smart Compact and Session Guard.** One switch each, what they will do, and links to their settings.
+- **Tokens, last 30 days.** Billable tokens, the cache hit rate and the subagent share, per day, by hour of the week, by workspace and by model, reconstructed from Claude Code's transcripts.
 
-### Shows session and plan usage
+The pill above each message box is a ring of that session's context, with a tick at its compact line. Press it to see the detail, when it last saved its task state and compacted, and to enrol the session or take it out.
 
-Smart Session keeps a local history of:
+![Pressing the context ring above the message box, then following it to the Smart Session screen and sweeping the window chart: recorded usage up to now, the projection at this pace, and the stretch after it runs out](docs/media/smart-session-flow.gif)
 
-- 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
+![A session's context popover: 34% of a 1M context, 336k tokens, compacts at 30%, past its compact line; task state saved 10m ago; last compaction 3h ago, 318k to 31k; the Smart Compact switch for this session](docs/media/smart-session-pill.png)
 
-That history remains useful after an individual session ends or a provider cache changes.
-
-## 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
-```
+| `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 |
 
-`request_compaction` refuses when the state file is missing or stale. The agent can checkpoint and request again in the same turn.
+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. In the chat each call is one line ("Saved task state · Cap retries at five", "Asked to compact · …"), and the messages Smart Session sends show as small cards with the full text one press away.
 
-## Smart Compact
+![A chat after a compaction: the agent's own compaction request and the continuation as cards, a context manually compacted divider, and one-line rows for Checked plan usage and Put off compacting](docs/media/smart-session-chat.png)
 
-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.
+## How Smart Compact works
 
-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.
+As a session fills, hooks send context notices. At the compact line, 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.
 
-Every request sends the `/compact` command. The agent can also set:
+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.
 
-- `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**.
+The forecast uses the last half hour for the session window and the window's own average for a week, so a burst of work doesn't read as "the week runs out tonight".
 
-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.
+**Settings → Plugins → Smart Session → Smart Compact:**
 
-### 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 |
+| Enrol sessions automatically | On | Enrol a session once it writes task state |
+| Context pill on every session | On | The ring above each message box |
+| Windows of 400k or more | 30% | Where large windows are asked to compact |
+| Smaller windows | 85% | Where smaller windows are asked to compact |
+| Register the hooks | On | Keep the context and compaction hooks installed in Claude Code |
 
-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 paused session gets a card in its chat with the reset time and a countdown, **Resume now** and **Dismiss pause**; once the pause ends the card folds into one line. **Paused sessions** lists every pause by its reset time, and the session's pill and its workspace read **Paused**. 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/
-```
+![Session Guard: a pause card in the chat with the reset time, Resume now and Dismiss pause, and the Paused sessions screen listing sessions waiting for the reset](docs/media/smart-session-guard.png)
 
-| 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.
+On a phone, the pill popovers open as sheets and every screen fits one column.
 
-## Password-protected daemons
+![Smart Session at phone width: the overview, the context popover as a sheet, and Paused sessions](docs/media/smart-session-mobile.png)
 
-When the Paseo daemon requires a password, Smart Session resolves it in this order:
+**Settings → Plugins → Smart Session → Display** hides the sidebar row or the composer pills; neither turns a feature off.
 
-1. `PASEO_PASSWORD`
-2. The file named by `PASEO_PASSWORD_FILE`
-3. `~/paseo-hub/secrets/daemon-password`
+## Data and access
 
-The secret is used only to connect to the daemon. It is never written or logged.
+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.
+
+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.
-- [Graphite](https://github.com/tomgrin10/paseo-graphite) — Graphite stacks and PR status.
-- [Vitals](https://github.com/tomgrin10/paseo-vitals) — Host, agent, and Docker health.
+- [Follow-up](https://github.com/tomgrin10/paseo-follow-up) — Track workspace PRs, remaining tasks and completion.
+- [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,200 @@
+/**
+ * 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;
+  /** Context occupancy as of the agent's last turn, from its snapshot; null until it has run one. */
+  readonly usedTokens: number | null;
+  readonly maxTokens: number | null;
+}
+
+export interface AgentDirectory {
+  current(): ReadonlyMap<string, DirectoryAgent>;
+  /** Called after every change; read `current()` for the new state. */
+  subscribe(listener: () => void): () => void;
+  /** Bumped on every change, for `useSyncExternalStore`. */
+  version(): number;
+  /** 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;
+  readonly lastUsage?: { readonly contextWindowUsedTokens?: number; readonly contextWindowMaxTokens?: number } | 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;
+  const used = agent.lastUsage?.contextWindowUsedTokens;
+  const max = agent.lastUsage?.contextWindowMaxTokens;
+  return [agent.id, {
+    workspaceId: agent.workspaceId,
+    closed: agent.status === "closed" || !!agent.archivedAt,
+    usedTokens: typeof used === "number" && Number.isFinite(used) ? used : null,
+    maxTokens: typeof max === "number" && Number.isFinite(max) && max > 0 ? max : null,
+  }];
+}
+
+function same(a: DirectoryAgent | undefined, b: DirectoryAgent): boolean {
+  return a !== undefined && a.workspaceId === b.workspaceId && a.closed === b.closed && a.usedTokens === b.usedTokens && a.maxTokens === b.maxTokens;
+}
+
+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;
+
+  let version = 0;
+  const notify = () => {
+    version += 1;
+    for (const listener of [...listeners]) listener();
+  };
+
+  function upsert(agent: ListedAgent | undefined): boolean {
+    let entry = entryOf(agent);
+    if (entry === null) return false;
+    // An update that carries no usage is not a reading of zero: keep the last one.
+    const known = agents.get(entry[0]);
+    if (entry[1].usedTokens === null && agent?.lastUsage == null && known !== undefined) {
+      entry = [entry[0], { ...entry[1], usedTokens: known.usedTokens, maxTokens: known.maxTokens }];
+    }
+    if (same(known, 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,
+    version: () => version,
+    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);
+    },
+  };
+}