paseo-smart-session 3.1.0 → 3.2.0

package/client/settings.tsx

@@ -1,14 +1,21 @@
-import { useRpc, type PluginSurfaceProps } from "@getpaseo/plugin/client";
-import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection, SettingsSwitch, useToast } from "@getpaseo/plugin/client/ui";
+import { useRpc, useSettings, type PluginClientContext, type PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection, SettingsSelect, SettingsSwitch, useToast } from "@getpaseo/plugin/client/ui";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { useEffect, useState } from "react";
-import { ActivityIndicator, ScrollView, Text, View } from "react-native";
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { ActivityIndicator, ScrollView, Text, TextInput, View } from "react-native";
 
+import { displayPreferences } from "../shared/display";
 import { formatCompactTokens } from "../shared/format";
 import { enrolmentState } from "../shared/governor";
+import { guardPreferences } from "../shared/guard/contracts";
+import { isPending, type Policy } from "../shared/guard/policy";
+import { checkTiming, timingOf, type Timing } from "../shared/guard/timing";
+import { governorNotice } from "../shared/guard/presentation";
 import { getSettings, installStatus, setSettings } from "../shared/smart-session";
 import { withCompactThreshold } from "../shared/thresholds";
-import { errorText } from "./kit";
+import { broadcastDisplay } from "./display";
+import { guardSnapshot, refreshGuard, subscribeGuard } from "./guard/status";
+import { Button, errorText } from "./kit";
 import { refreshPills } from "./pill-store";
 
 /** A whole number from 1 to 99, or null. */
@@ -18,88 +25,221 @@ function percent(value: string): number | null {
 }
 
 /**
- * Settings → Plugins → Smart Session → Smart Compact. Everything that tunes when a
- * session is asked to compact itself; the overview keeps only the on/off switch.
+ * Settings → Plugins → Smart Session: every setting in one place, in the order a
+ * session meets them. Context first (when to compact), then the limit (pause and
+ * continue), then where Smart Session shows up, the Claude Code hooks, and the
+ * protection timing nobody needs to touch, folded behind Edit. Live lists of paused
+ * sessions and per-session choices live on the overview; this links there.
  */
-export function SmartCompactSettings({ theme, layout }: PluginSurfaceProps) {
-  const c = theme.colors;
-  const toast = useToast();
-  const queryClient = useQueryClient();
-  const read = useRpc(getSettings);
-  const write = useRpc(setSettings);
-  const readEnrolment = useRpc(enrolmentState);
-  const readInstall = useRpc(installStatus);
-  const query = useQuery({ queryKey: ["smart-session", "settings"], queryFn: () => read({}), refetchInterval: 60_000 });
-  const install = useQuery({ queryKey: ["smart-session", "install"], queryFn: () => readInstall({}), refetchInterval: 5 * 60_000 });
-  const [saving, setSaving] = useState(false);
-  const [draft, setDraft] = useState<{ large: string; small: string } | null>(null);
-  const [inputKey, setInputKey] = useState(0);
-  const settings = query.data?.settings;
-  useEffect(() => { setDraft(null); }, [settings?.thresholds.large.compact, settings?.thresholds.small.compact]);
+export function makeSettings(client: PluginClientContext) {
+  const openPaused = () => client.openScreen({ screenId: "overview", params: { focus: "paused" } });
+  return function SmartSessionSettings({ theme }: PluginSurfaceProps) {
+    const c = theme.colors;
+    const toast = useToast();
+    const queryClient = useQueryClient();
+    const read = useRpc(getSettings);
+    const write = useRpc(setSettings);
+    const readEnrolment = useRpc(enrolmentState);
+    const readInstall = useRpc(installStatus);
+    const query = useQuery({ queryKey: ["smart-session", "settings"], queryFn: () => read({}), refetchInterval: 60_000 });
+    const install = useQuery({ queryKey: ["smart-session", "install"], queryFn: () => readInstall({}), refetchInterval: 5 * 60_000 });
+    const guard = useSettings(guardPreferences);
+    const display = useSettings(displayPreferences);
+    const status = useSyncExternalStore(subscribeGuard, guardSnapshot, guardSnapshot);
+    const [saving, setSaving] = useState(false);
+    const [draft, setDraft] = useState<{ large: string; small: string } | null>(null);
+    const [inputKey, setInputKey] = useState(0);
+    const [timing, setTiming] = useState<{ draft: Timing; revision: string } | null>(null);
+    const [timingTried, setTimingTried] = useState(false);
+    const settings = query.data?.settings;
+    useEffect(() => { setDraft(null); }, [settings?.thresholds.large.compact, settings?.thresholds.small.compact]);
 
-  if (query.isError && settings === undefined) return <View style={{ padding: 16, gap: 12 }}>
-    <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{errorText(query.error)}</Text>
-    <SettingsCard><SettingsAction label="Load the settings again" actionLabel="Retry" onPress={() => void query.refetch()} /></SettingsCard>
-  </View>;
-  if (settings === undefined) return <ActivityIndicator accessibilityLabel="Loading Smart Compact settings" color={c.foregroundMuted} style={{ padding: 24 }} />;
+    // The pill and sidebar follow these documents; `useSettings` hears every client's change.
+    const guardValues = guard.status === "ready" ? guard.values : undefined;
+    useEffect(() => { if (guardValues !== undefined) refreshGuard(); }, [guardValues]);
+    const displayValues = display.status === "ready" ? display.values : undefined;
+    useEffect(() => { if (displayValues !== undefined) broadcastDisplay(displayValues); }, [displayValues]);
 
-  async function save(patch: Parameters<typeof write>[0], message: string) {
-    setSaving(true);
-    try {
-      await write(patch);
-      await refreshPills(() => readEnrolment({}));
-      await queryClient.invalidateQueries({ queryKey: ["smart-session"] });
-      toast.show(message);
-    } catch (error) {
-      toast.error(errorText(error));
-    } finally {
-      setSaving(false);
+    if (query.isError && settings === undefined) return <View style={{ paddingVertical: 8, gap: 12 }}>
+      <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{errorText(query.error)}</Text>
+      <SettingsCard><SettingsAction label="Load the settings again" actionLabel="Retry" onPress={() => void query.refetch()} /></SettingsCard>
+    </View>;
+    if (settings === undefined) return <ActivityIndicator accessibilityLabel="Loading Smart Session settings" color={c.foregroundMuted} style={{ padding: 24 }} />;
+
+    async function save(patch: Parameters<typeof write>[0], message: string) {
+      setSaving(true);
+      try {
+        await write(patch);
+        await refreshPills(() => readEnrolment({}));
+        await queryClient.invalidateQueries({ queryKey: ["smart-session"] });
+        toast.show(message);
+      } catch (error) {
+        toast.error(errorText(error));
+      } finally {
+        setSaving(false);
+      }
+    }
+    function changeGuard(patch: Partial<Policy>, message: string) {
+      if (guard.status !== "ready") return;
+      void guard.save({ ...guard.values, ...patch }, guard.revision).then((saved) => {
+        if (saved) toast.show(message);
+        else toast.error("That change couldn't be saved. Try again.");
+      });
+    }
+    async function setPill(next: boolean) {
+      // One switch over two stored preferences: the Smart Compact pill flag and the Display gate.
+      if (next && display.status === "ready" && !display.values.enable_composer_button) await display.save({ ...display.values, enable_composer_button: true }, display.revision);
+      if (settings!.showPill !== next) await save({ showPill: next }, next ? "Pill shown on every session" : "Pill hidden");
+      else toast.show(next ? "Pill shown on every session" : "Pill hidden");
+    }
+
+    const large = draft === null ? settings.thresholds.large.compact : percent(draft.large);
+    const small = draft === null ? settings.thresholds.small.compact : percent(draft.small);
+    const changed = draft !== null && large !== null && small !== null && (large !== settings.thresholds.large.compact || small !== settings.thresholds.small.compact);
+    const off = !settings.enabled || saving;
+    const report = install.data?.report;
+    const hooksHint = report === undefined ? "Keeps this plugin's context and compaction hooks in ~/.claude/settings.json."
+      : report.error !== null ? report.error
+        : report.pluginDir === null || report.hooks.length === 0 ? "Not registered, so nothing will ask a session to compact itself."
+          : `Registered: ${report.hooks.join(", ")}. Only entries that point at this plugin are touched.`;
+    const from = formatCompactTokens(settings.thresholds.largeWindowFrom);
+
+    // Protection: the stored document, plus who runs it on this host.
+    const policy = guard.status === "ready" ? guard.values : null;
+    const notice = status === null ? null : governorNotice(status);
+    const elsewhere = notice !== null && status?.governor !== "off" ? notice : null;
+    const guardBusy = guard.status !== "ready" || guard.saving || timing !== null;
+    const pending = status?.pauses.filter(isPending) ?? [];
+    const overrides = status === null ? 0 : Object.keys(status.overrides).length;
+    const listHint = status === null ? "Paused sessions and sessions you changed from the default, on the overview."
+      : [pending.length === 0 ? "Nothing paused" : `${pending.length} paused`, overrides === 0 ? "no session changed from the default" : `${overrides} ${overrides === 1 ? "session" : "sessions"} changed from the default`].join(" · ");
+    const checked = timing === null ? null : checkTiming(timing.draft);
+    const fieldError = (key: keyof Timing) => (timingTried ? checked?.errors[key] ?? null : null);
+    async function saveTiming() {
+      if (timing === null || guard.status !== "ready" || checked === null) return;
+      setTimingTried(true);
+      if (Object.keys(checked.errors).length > 0) return;
+      if (await guard.save({ ...guard.values, ...checked.values }, timing.revision)) {
+        setTiming(null); setTimingTried(false);
+        toast.show("Limit timing saved");
+      }
     }
-  }
+    const pillOn = settings.showPill && (display.status !== "ready" || display.values.enable_composer_button);
+
+    return <ScrollView style={{ flex: 1 }} contentContainerStyle={{ paddingVertical: 8, gap: 24 }}>
+      <SettingsSection title="Smart Compact" info="A session is never compacted unless it agrees. At the end of a turn past its line, it is asked whether to compact; it can compact, put it off with a reason, or keep working.">
+        <SettingsCard>
+          <SettingsSwitch label="Smart Compact" hint={settings.enabled ? "On. Context notices, and the question at the compact line." : "Off. Nothing is asked and nothing is compacted."}
+            value={settings.enabled} disabled={saving} onValueChange={(enabled) => void save({ enabled }, enabled ? "Smart Compact on" : "Smart Compact off")} />
+          <SettingsSwitch label="Enrol sessions automatically" hint="A session that saves its task state with the checkpoint tool is enrolled by that alone. Off, enrol each one from its pill."
+            value={settings.autoEnrol} disabled={off} onValueChange={(autoEnrol) => void save({ autoEnrol }, autoEnrol ? "Sessions enrol themselves" : "Sessions are enrolled one at a time")} />
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection title="When to ask" info="What wears a session down is its absolute size, not its share of the window, so large windows are asked much earlier. Earlier context notices move down with the line.">
+        <SettingsCard>
+          <SettingsInput key={`large-${inputKey}`} label={`Windows of ${from} or more (%)`} hint={`Asked at ${large ?? "—"}%, about ${large === null ? "—" : formatCompactTokens((large / 100) * 1_000_000)} tokens of a 1M window. Default 30.`}
+            initialValue={String(settings.thresholds.large.compact)} disabled={off} error={draft !== null && large === null ? "Enter a whole number from 1 to 99." : null}
+            onChangeText={(value) => setDraft((previous) => ({ large: value, small: previous?.small ?? String(settings.thresholds.small.compact) }))} />
+          <SettingsInput key={`small-${inputKey}`} label="Smaller windows (%)" hint={`Asked at ${small ?? "—"}% of a window under ${from}. Default 85.`}
+            initialValue={String(settings.thresholds.small.compact)} disabled={off} error={draft !== null && small === null ? "Enter a whole number from 1 to 99." : null}
+            onChangeText={(value) => setDraft((previous) => ({ small: value, large: previous?.large ?? String(settings.thresholds.large.compact) }))} />
+          {draft !== null ? <>
+            <SettingsAction label="Apply the new lines" hint={changed ? `Large ${large}% · small ${small}%` : "Nothing to apply yet"} actionLabel="Save" disabled={!changed || off}
+              onPress={() => void save({ thresholds: { ...settings.thresholds, large: withCompactThreshold(settings.thresholds.large, large!), small: withCompactThreshold(settings.thresholds.small, small!) } }, `Smart Compact asks at ${large}% and ${small}%`)} />
+            <SettingsAction label="Keep the saved lines" actionLabel="Discard" disabled={saving} onPress={() => { setDraft(null); setInputKey((k) => k + 1); }} />
+          </> : null}
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection title="Pause at the limit" info="When the provider's session window is spent, a running session is paused instead of failing, then continued in the same conversation once the window resets. Formerly the Session Guard plugin; its choices and waiting pauses carry over.">
+        {guard.status === "loading" ? <ActivityIndicator accessibilityLabel="Loading Pause at the limit settings" color={c.foregroundMuted} style={{ padding: 16 }} />
+          : guard.status !== "ready" ? <View style={{ gap: 8 }}>
+            <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{guard.error}</Text>
+            <SettingsCard>
+              <SettingsAction label="Load the saved settings again" actionLabel="Retry" onPress={() => void guard.reload()} />
+              {guard.status === "invalid" ? <SettingsAction label="Replace the invalid settings with defaults" actionLabel="Reset" disabled={guard.saving} onPress={() => void guard.reset()} /> : null}
+            </SettingsCard>
+          </View>
+            : <SettingsCard>
+              {elsewhere ? <SettingsRow label={elsewhere.title} hint={elsewhere.hint} /> : null}
+              <SettingsSwitch label="Pause at the limit" hint={guard.values.enabled ? `On. Sessions pause at ${guard.values.thresholdPct}% of the session window. Works while the app is closed.` : "Off until you turn it on. Turning it off lets frozen workers go; waiting continuations hold until you turn it back on or cancel them."}
+                value={guard.values.enabled} disabled={guardBusy} onValueChange={(enabled) => changeGuard({ enabled }, enabled ? "Sessions pause at the limit" : "Pause at the limit off")} />
+              <SettingsSelect label="Sessions" hint="Change any one session from its pill."
+                value={guard.values.protectByDefault ? "all" : "opt-in"} options={[{ label: "Every session", value: "all" }, { label: "Only ones I turn on", value: "opt-in" }]}
+                disabled={guardBusy || !guard.values.enabled} onValueChange={(value) => changeGuard({ protectByDefault: value === "all" }, value === "all" ? "Every session pauses at the limit" : "Sessions pause only when you turn them on")} />
+              <SettingsSwitch label="Continue after the reset" hint="Waits for a fresh usage reading below the line, then sends the continuation. Off, you continue each one by hand."
+                value={guard.values.autoResume} disabled={guardBusy || !guard.values.enabled} onValueChange={(autoResume) => changeGuard({ autoResume }, autoResume ? "Paused sessions continue after the reset" : "Paused sessions wait for you")} />
+              <SettingsSwitch label="Include native subagents" hint="On Linux, freeze Claude and Codex sessions together with their nested workers. Off, only the foreground turn is interrupted."
+                value={guard.values.includeNativeSubagents} disabled={guardBusy || !guard.values.enabled} onValueChange={(includeNativeSubagents) => changeGuard({ includeNativeSubagents }, includeNativeSubagents ? "Subagents pause too" : "Only the foreground turn pauses")} />
+              <SettingsSwitch label="Label paused workspaces" hint="An amber Paused label in the sidebar until every session in the workspace continues."
+                value={guard.values.workspaceLabels} disabled={guardBusy || !guard.values.enabled} onValueChange={(workspaceLabels) => changeGuard({ workspaceLabels }, workspaceLabels ? "Paused workspaces are labelled" : "No workspace labels")} />
+              <SettingsAction label="Paused sessions and exceptions" hint={listHint} actionLabel="Open" onPress={openPaused} />
+            </SettingsCard>}
+      </SettingsSection>
+
+      <SettingsSection title="Display" info="Hiding the row or the pill never turns a feature off. ⌘K Smart Session still opens the overview.">
+        {display.status === "loading" ? <ActivityIndicator accessibilityLabel="Loading display settings" color={c.foregroundMuted} style={{ padding: 16 }} />
+          : display.status !== "ready" ? <View style={{ gap: 8 }}>
+            <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{display.error}</Text>
+            <SettingsCard>
+              <SettingsAction label="Load the saved display settings again" actionLabel="Retry" onPress={() => void display.reload()} />
+              {display.status === "invalid" ? <SettingsAction label="Replace the invalid display settings with defaults" actionLabel="Reset" disabled={display.saving} onPress={() => void display.reset()} /> : null}
+            </SettingsCard>
+          </View>
+            : <SettingsCard>
+              <SettingsSwitch label="Sidebar row" hint="Smart Session in the sidebar, with the session window's use, or how many sessions are paused."
+                value={display.values.showSidebar} disabled={display.saving} onValueChange={(showSidebar) => void display.save({ ...display.values, showSidebar }, display.revision)} />
+              <SettingsSwitch label="Pill on every session" hint="The context ring above each message box. A paused session keeps its pill either way."
+                value={pillOn} disabled={saving || display.saving} onValueChange={(next) => void setPill(next)} />
+            </SettingsCard>}
+        {display.status === "ready" && display.saveError ? <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{display.saveError}</Text> : null}
+      </SettingsSection>
 
-  const large = draft === null ? settings.thresholds.large.compact : percent(draft.large);
-  const small = draft === null ? settings.thresholds.small.compact : percent(draft.small);
-  const changed = draft !== null && large !== null && small !== null && (large !== settings.thresholds.large.compact || small !== settings.thresholds.small.compact);
-  const off = !settings.enabled || saving;
-  const report = install.data?.report;
-  const hooksHint = report === undefined ? "Keeps this plugin's context and compaction hooks in ~/.claude/settings.json."
-    : report.error !== null ? report.error
-      : report.pluginDir === null || report.hooks.length === 0 ? "Not registered, so nothing will ask a session to compact itself."
-        : `Registered: ${report.hooks.join(", ")}. Only entries that point at this plugin are touched.`;
-  const from = formatCompactTokens(settings.thresholds.largeWindowFrom);
+      <SettingsSection title="Claude Code">
+        <SettingsCard>
+          <SettingsSwitch label="Register the hooks" hint={hooksHint} value={settings.installHooks} disabled={off}
+            onValueChange={(installHooks) => void save({ installHooks }, installHooks ? "Hooks registered with Claude Code" : "Hooks removed from Claude Code")} />
+          {report?.mcp === "unavailable" ? <SettingsRow label="MCP server not registered" hint="The claude command was not reachable from the daemon." /> : null}
+        </SettingsCard>
+      </SettingsSection>
 
-  return <ScrollView style={{ flex: 1 }} contentContainerStyle={{ paddingVertical: 8, gap: 24 }}>
-    <SettingsSection title="Smart Compact" info="A session is never compacted unless it agrees. At the end of a turn past its line, it is asked whether to compact; it can compact, put it off with a reason, or keep working.">
-      <SettingsCard>
-        <SettingsSwitch label="Smart Compact" hint={settings.enabled ? "On. Context notices, and the question at the compact line." : "Off. Nothing is asked and nothing is compacted."}
-          value={settings.enabled} disabled={saving} onValueChange={(enabled) => void save({ enabled }, enabled ? "Smart Compact on" : "Smart Compact off")} />
-        <SettingsSwitch label="Enrol sessions automatically" hint="A session that saves its task state with the checkpoint tool is enrolled by that alone. Off, enrol each one from its pill."
-          value={settings.autoEnrol} disabled={off} onValueChange={(autoEnrol) => void save({ autoEnrol }, autoEnrol ? "Sessions enrol themselves" : "Sessions are enrolled one at a time")} />
-        <SettingsSwitch label="Context pill on every session" hint="A ring above the message box with the session's context and its compact line. Press it to enrol or remove the session."
-          value={settings.showPill} disabled={off} onValueChange={(showPill) => void save({ showPill }, showPill ? "Pill shown on every session" : "Pill hidden")} />
-      </SettingsCard>
-    </SettingsSection>
-    <SettingsSection title="When to ask" info="What wears a session down is its absolute size, not its share of the window, so large windows are asked much earlier. Earlier context notices move down with the line.">
-      <SettingsCard>
-        <SettingsInput key={`large-${inputKey}`} label={`Windows of ${from} or more (%)`} hint={`Asked at ${large ?? "—"}%, about ${large === null ? "—" : formatCompactTokens((large / 100) * 1_000_000)} tokens of a 1M window. Default 30.`}
-          initialValue={String(settings.thresholds.large.compact)} disabled={off} error={draft !== null && large === null ? "Enter a whole number from 1 to 99." : null}
-          onChangeText={(value) => setDraft((previous) => ({ large: value, small: previous?.small ?? String(settings.thresholds.small.compact) }))} />
-        <SettingsInput key={`small-${inputKey}`} label={`Smaller windows (%)`} hint={`Asked at ${small ?? "—"}% of a window under ${from}. Default 85.`}
-          initialValue={String(settings.thresholds.small.compact)} disabled={off} error={draft !== null && small === null ? "Enter a whole number from 1 to 99." : null}
-          onChangeText={(value) => setDraft((previous) => ({ small: value, large: previous?.large ?? String(settings.thresholds.large.compact) }))} />
-        {draft !== null ? <>
-          <SettingsAction label="Apply the new lines" hint={changed ? `Large ${large}% · small ${small}%` : "Nothing to apply yet"} actionLabel="Save" disabled={!changed || off}
-            onPress={() => void save({ thresholds: { ...settings.thresholds, large: withCompactThreshold(settings.thresholds.large, large!), small: withCompactThreshold(settings.thresholds.small, small!) } }, `Smart Compact asks at ${large}% and ${small}%`)} />
-          <SettingsAction label="Keep the saved lines" actionLabel="Discard" disabled={saving} onPress={() => { setDraft(null); setInputKey((k) => k + 1); }} />
-        </> : null}
-      </SettingsCard>
-    </SettingsSection>
-    <SettingsSection title="Claude Code">
-      <SettingsCard>
-        <SettingsSwitch label="Register the hooks" hint={hooksHint} value={settings.installHooks} disabled={off}
-          onValueChange={(installHooks) => void save({ installHooks }, installHooks ? "Hooks registered with Claude Code" : "Hooks removed from Claude Code")} />
-        {report?.mcp === "unavailable" ? <SettingsRow label="MCP server not registered" hint="The claude command was not reachable from the daemon." /> : null}
-      </SettingsCard>
-    </SettingsSection>
-  </ScrollView>;
+      {policy === null ? null : <SettingsSection title="Limit timing" info="How Pause at the limit reads usage and continues sessions. The defaults suit almost everyone.">
+        <SettingsCard>
+          {timing === null ? <SettingsAction label={`Pause at ${policy.thresholdPct}% of the session window`}
+            hint={`Check every ${policy.pollSeconds}s · wait ${policy.resetGraceSeconds}s after the reset · ${policy.resumeSpacingSeconds}s between continuations · ${policy.providerIds.length === 0 ? "every provider" : policy.providerIds.join(", ")}`}
+            actionLabel="Edit" disabled={guard.status !== "ready" || guard.saving} onPress={() => { if (guard.status === "ready") { setTiming({ draft: timingOf(guard.values), revision: guard.revision }); setTimingTried(false); } }} /> : <>
+            <SettingsInput label="Pause at (%)" hint="Of the session window. 1–100, default 100." initialValue={timing.draft.thresholdPct} error={fieldError("thresholdPct")} disabled={guard.saving}
+              onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, thresholdPct: value } })} />
+            <SettingsInput label="Check every (seconds)" hint="5–300, default 15. Paseo may cache usage; this can't force a provider refresh." initialValue={timing.draft.pollSeconds} error={fieldError("pollSeconds")} disabled={guard.saving}
+              onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, pollSeconds: value } })} />
+            <SettingsInput label="Wait after the reset (seconds)" hint="0–600, default 30." initialValue={timing.draft.resetGraceSeconds} error={fieldError("resetGraceSeconds")} disabled={guard.saving}
+              onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, resetGraceSeconds: value } })} />
+            <SettingsInput label="Between continuations (seconds)" hint="0–300, default 5, so paused sessions don't all start at once." initialValue={timing.draft.resumeSpacingSeconds} error={fieldError("resumeSpacingSeconds")} disabled={guard.saving}
+              onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, resumeSpacingSeconds: value } })} />
+            {/* A message is prose: it gets the full width and several lines, not a one-line field. */}
+            <View style={{ paddingHorizontal: 16, paddingVertical: 12, gap: 6 }}>
+              <Text style={{ color: c.foreground, fontSize: 14, lineHeight: 20 }}>Continuation message</Text>
+              <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 17 }}>Sent once into the same conversation after the reset is confirmed.</Text>
+              <TextInput multiline accessibilityLabel="Continuation message" defaultValue={timing.draft.continuation} editable={!guard.saving}
+                onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, continuation: value } })}
+                style={{ minHeight: 96, marginTop: 4, padding: 10, borderRadius: 8, borderWidth: 1, borderColor: fieldError("continuation") ? c.statusDanger : c.border, backgroundColor: c.surface2, color: c.foreground, fontSize: 13, lineHeight: 19, textAlignVertical: "top" }} />
+              {fieldError("continuation") ? <Text style={{ color: c.statusDanger, fontSize: 12, lineHeight: 17 }}>{fieldError("continuation")}</Text> : null}
+            </View>
+            <SettingsInput label="Providers" hint="Comma separated, e.g. claude, codex. Empty means every provider that reports session usage." initialValue={timing.draft.providerIds} error={fieldError("providerIds")} disabled={guard.saving}
+              onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, providerIds: value } })} />
+            <SettingsInput label="Session windows" hint="Which usage window counts as the session limit, first match wins: five_hour is Claude's 5-hour window, session is Codex's." initialValue={timing.draft.windowIds} error={fieldError("windowIds")} disabled={guard.saving}
+              onChangeText={(value) => setTiming((t) => t && { ...t, draft: { ...t.draft, windowIds: value } })} />
+            <SettingsRow label={timingTried && checked && Object.keys(checked.errors).length > 0 ? "Fix the marked fields to save" : "Save the new timing?"}>
+              <View style={{ flexDirection: "row", gap: 6 }}>
+                <Button theme={theme} small kind="ghost" title="Discard" disabled={guard.saving} onPress={() => { setTiming(null); setTimingTried(false); }} />
+                <Button theme={theme} small title={guard.saving ? "Saving…" : "Save"} disabled={guard.saving} onPress={() => void saveTiming()} />
+              </View>
+            </SettingsRow>
+          </>}
+        </SettingsCard>
+        {guard.status === "ready" && guard.saveError ? <Text accessibilityRole="alert" style={{ color: c.statusDanger }}>{guard.saveError}</Text> : null}
+      </SettingsSection>}
+    </ScrollView>;
+  };
 }

package/docs/navigation-verification.md

@@ -3,9 +3,9 @@
 Verified in an isolated Paseo 0.15 daemon with synthetic workspaces, usage history and sessions, using the app's web runtime at 1440×900 and 390×844, light and dark.
 
 - The sidebar row **Smart Session** opens the overview screen; its header reads **Smart Session**, not a raw id. The row trails the session window's use, or how many sessions are paused.
-- **Paused sessions** is its own screen with its own title, opened from the overview, the Session Guard pill's menu, a pause card or Command Center.
-- Smart Compact, Session Guard and Display settings live in **Settings → Plugins → Smart Session** and open from the overview's gear, the feature cards and Command Center.
-- **Display** hides the sidebar row or the composer pills; hiding either never turns a feature off, and Command Center still opens the overview.
+- Paused sessions are a section of the overview, right under its headline. ⌘K **Smart Session: paused sessions**, a pause card, the pill's popover and settings open the overview at that list; the old `paused-sessions` screen id still resolves to it.
+- One settings screen, **Settings → Plugins → Smart Session → Settings** (id `smart-compact`, which the old first page used), opens from the overview's gear, the feature rows, the pill's popover and Command Center.
+- **Display** in that screen hides the sidebar row or the pill; hiding either never turns a feature off, a paused session keeps its pill, and Command Center still opens the overview.
 - Compact settings have no horizontal overflow and keep accessible native switches.
 
-Screenshots: [desktop](screenshots/display-settings-desktop.png), [compact](screenshots/display-settings-mobile.png). Screenshots contain synthetic data. No main daemon restart or real-agent messages were used.
+Screenshots: [settings](media/smart-session-settings.png), [phone](media/smart-session-mobile.png). Screenshots contain synthetic data. No main daemon restart or real-agent messages were used.

package/docs/session-guard.md

@@ -1,16 +1,16 @@
-# Session Guard
+# Pause at the limit
 
-Session Guard pauses agents at their provider's session limit and continues the same conversations after the window resets, even while the Paseo app is closed. It began as the standalone [paseo-session-guard](https://github.com/tomgrin10/paseo-session-guard) plugin and now ships inside Smart Session. See the [README](../README.md) for installation.
+Pause at the limit (formerly the Session Guard plugin, and still called Session Guard in the code and data paths) pauses agents at their provider's session limit and continues the same conversations after the window resets, even while the Paseo app is closed. It began as the standalone [paseo-session-guard](https://github.com/tomgrin10/paseo-session-guard) plugin and now ships inside Smart Session. See the [README](../README.md) for installation.
 
 ## Turning it on
 
-Session Guard is **off by default**. Turn it on with the **Session Guard** switch on the Smart Session overview, or in **Settings → Plugins → Smart Session → Session Guard**. Off, it holds no lock, writes nothing and draws no pill.
+It is **off by default**. Turn it on with the **Pause at the limit** switch on the Smart Session overview, or in **Settings → Plugins → Smart Session**. Off, it holds no lock, writes nothing and adds nothing to the pill.
 
 ### Moving from the standalone plugin
 
 Smart Session never runs Session Guard while the standalone plugin is configured **and enabled** on the host, even when it could. Released versions of the standalone plugin resume every suspended session in the shared state when they are disabled or removed, whichever plugin paused it, so two enabled copies cannot share a host safely. Both keep their state in `$PASEO_HOME/plugin-data/session-guard/` and take the same `governor.lock` there, so a disabled copy that is still shutting down is waited out too.
 
-- While the standalone plugin is enabled, Smart Session's Session Guard pauses nothing. Its settings, the paused-sessions list and the overview say so, its pill stays hidden, and pauses in the list are marked as the standalone plugin's, with no controls.
+- While the standalone plugin is enabled, Smart Session's Session Guard pauses nothing. Settings, the pill's popover and the overview say so in one line, and pauses in the overview's list are marked read-only, with no controls.
 - **Disable or uninstall Session Guard** (**Settings → Plugins**, `paseo plugin disable paseo-session-guard` or `paseo plugin remove paseo-session-guard`). Smart Session takes over on its next check, about 15 seconds later. Per-session choices and waiting pauses carry over, because they are the same file. The standalone plugin releases native workers when it stops; if the quota is still full, Smart Session normally pauses that work again on its first check.
 - Smart Session's settings start from defaults: the standalone plugin's settings belong to that installation and are deleted with it. Re-apply any custom threshold, timing or continuation message.
 - If the standalone plugin is enabled again while Smart Session is protecting the host, Smart Session releases the sessions it suspended, keeps their confirmed waits, gives up the lock and stops. The standalone plugin does not retry its lock, so reload it to let it take over, or disable it again to hand back to Smart Session. Between enabling it and Smart Session's next check (up to the check interval) both are loaded; avoid disabling it again within that window.
@@ -19,21 +19,17 @@ Turning Session Guard off releases suspended workers immediately. A message cont
 
 ## Use
 
-Every live session with a workspace gets a **Session Guard** composer pill while the feature is on. Open its menu to:
+There is no separate pill. Each session's Smart Session pill (the context ring) carries its protection, and says nothing about it while the session is simply protected. Press it for the **Pause at the limit** switch for that session: it shows whether the session follows your default or was changed, with **Use default** to go back. Turning the switch to match the default removes the override.
 
-- **Turn off for this session** / **Protect this session**: persist an explicit session override.
-- **Use host default**: remove that override.
-- **Cancel automatic continuation**: leave an interrupted turn for you to continue manually. For suspended native workers, **Release and turn off for this session** resumes them immediately and opts the session out, preventing the next check from pausing it again.
-- **Session Guard settings**: configure the host policy and see paused sessions.
-- **All paused sessions**: open the host-wide overview.
+When a session is paused, its pill becomes the pause: an amber pause glyph and the moment it resumes (**Resumes 5:58 PM**, **Paused · reset due**, or **Check session** in red when it needs a look). It stays on the composer while paused even if the pill is hidden in settings. Its popover leads with what happened and when it continues, with **Cancel continuation** (for an interrupted turn) or **Release and turn off** (for frozen native workers, which also opts the session out so the next check doesn't pause it again), and a link to all paused sessions.
 
-The **Paused sessions** screen gathers every Session Guard pause on the selected host, each led by the time its window resets and a countdown, with the session title, provider and whether native subagents are frozen or the turn was interrupted. Uncertain stops are grouped under **Needs attention**. Open a session or manage its pause directly; search appears when the list is busy. Open it from the Smart Session overview (the **2 paused** line under the headline, or the Session Guard card), the pill's menu, Command Center, settings, or a pause card. While anything is paused, the Smart Session sidebar row shows the count. A waiting session's composer pill begins **Paused**. Its workspace also gets an amber **Paused** label in the left sidebar. The label persists through restarts and stays until the last paused session in that workspace is released. Turn it off with **Label paused workspaces** in settings; other workspace labels stay intact.
+The Smart Session overview leads with paused sessions while there are any ("2 sessions resume at 5:58 PM"), and lists them right under the headline, each with the session title, provider, whether native subagents are frozen or the turn was interrupted, **Open session** and the release action. Uncertain stops sort first. Search appears when the list is busy. ⌘K **Smart Session: paused sessions**, a pause card and the settings screen all open the overview at this list. Sessions changed from your default are listed under the **Pause at the limit** row, each with **Use default**. While anything is paused, the Smart Session sidebar row shows the count. Paused workspaces get an amber **Paused** label in the left sidebar until the last paused session in them is released. Turn it off with **Label paused workspaces** in settings; other workspace labels stay intact.
 
-Confirmed pauses write a **Paused for session limit** timeline entry: the reset time with a live countdown, the provider and how much of the window was used, and whether native subagents are covered. When the pause ends, the entry folds into one line ("Paused at 7:57 PM · resumed 9:41 PM"), so the chat keeps the history without a stale card. Resume, release, and uncertain-stop entries make the recovery history clear. Existing confirmed waits are backfilled when upgrading. Timeline events use the host-owned plugin IPC identity, stay outside model messages, and never start a new turn. Delivery is journaled and retried; a lost acknowledgement is checked against timeline IDs before another append. Timeline delivery failures do not undo pauses and are shown in the overview/settings.
+Confirmed pauses write a **Paused at the session limit** timeline entry: the reset time with a live countdown, the provider and how much of the window was used, and whether native subagents are covered. When the pause ends, the entry folds into one line ("Paused at 7:57 PM · resumed 9:41 PM"), so the chat keeps the history without a stale card. Resume, release, and uncertain-stop entries make the recovery history clear. Existing confirmed waits are backfilled when upgrading. Timeline events use the host-owned plugin IPC identity, stay outside model messages, and never start a new turn. Delivery is journaled and retried; a lost acknowledgement is checked against timeline IDs before another append. Timeline delivery failures do not undo pauses and are shown in the overview/settings.
 
 Choose **Dismiss pause** on an active pause or restart-recovery timeline item to release it **without sending a message**. This cancels its scheduled continuation, turns protection off for that session, clears its active pause from the overview and workspace label when applicable, and collapses the original card to a short acknowledgement. Existing suspended workers are released and may continue their current work. The dismissal is saved before release so it survives restarts; partial release retries without sending. Historical cards cannot dismiss a newer pause. **Resume now** remains available when you want Guard to continue interrupted work immediately.
 
-Settings are also available in **Settings → Plugins → Smart Session → Session Guard** and Command Center. The default can be changed from **Protect all sessions** to **Opt in per session**. Explicit overrides survive that change. Native subagents inherit their parent session's protection and opt-out. Paseo-created child sessions have their own protection and pill, like every other session.
+Settings live in the **Pause at the limit** and **Limit timing** sections of **Settings → Plugins → Smart Session** (⌘K **Smart Session: settings**). **Sessions** can be changed from **Every session** to **Only ones I turn on**. Explicit overrides survive that change. Native subagents inherit their parent session's protection and opt-out. Paseo-created child sessions have their own protection and pill, like every other session.
 
 | Setting | Default | Range / meaning |
 |---|---|---|
@@ -57,9 +53,9 @@ Native coverage currently requires **Linux**, access to `/proc`, and a uniquely
 
 Suspension does not undo an API request or external action already sent. Network calls can time out while paused, and tools can retain locks. Resumption preserves local process state, but a provider's ordinary network/tool error still requires normal recovery; Session Guard automatically recovers only matching quota failures. Outstanding permission prompts remain for the person to answer.
 
-The pill's icon carries its state: a shield when protected, a muted crossed-out shield when off, an amber pause while paused, and a red warning when the session needs a look. A confirmed pause timeline entry offers **Resume now** while that exact pause is still waiting. This resumes owned native workers in place, or sends one manual continuation for an interrupted turn, and opts that session out so a still-full quota cannot immediately pause it again. Restore protection from the pill when ready. Resuming does not restore provider capacity: requests can still be rejected before reset. Historical entries cannot resume a newer pause, and unconfirmed message delivery is left for inspection without a blind retry.
+The pill's icon carries the pause: the context ring normally, an amber pause while paused, and a red warning when the session needs a look. A confirmed pause timeline entry offers **Resume now** while that exact pause is still waiting. This resumes owned native workers in place, or sends one manual continuation for an interrupted turn, and opts that session out so a still-full quota cannot immediately pause it again. Restore protection from the pill when ready. Resuming does not restore provider capacity: requests can still be rejected before reset. Historical entries cannot resume a newer pause, and unconfirmed message delivery is left for inspection without a blind retry.
 
-A disposable, empty session labelled `session_guard_demo=true` can exercise the real native pause/release path through the `smart-session.guard.demo-pause` RPC (`node probe.mjs rpc smart-session.guard.demo-pause '{"agentId":"…"}'`). It must have no user messages, active turn, or pending permissions. Its timeline explicitly says **Session Guard demo paused**, makes no quota claim, and waits for your action even when capacity resets. The demo never sends a task or changes provider quota reports.
+A disposable, empty session labelled `session_guard_demo=true` can exercise the real native pause/release path through the `smart-session.guard.demo-pause` RPC (`node probe.mjs rpc smart-session.guard.demo-pause '{"agentId":"…"}'`). It must have no user messages, active turn, or pending permissions. Its timeline explicitly says **Test pause**, makes no quota claim, and waits for your action even when capacity resets. The demo never sends a task or changes provider quota reports.
 
 ## Timing and persistence
 
@@ -77,7 +73,7 @@ If a reload or connection loss interrupts an unconfirmed stop/send, the pill rea
 
 ## With ZeroSub
 
-[ZeroSub](https://github.com/kapybara-org/zerosub) runs Claude and Codex agents on several subscription accounts. When an account hits a limit, ZeroSub moves the agent to another account and continues it. It switches only on the CLI's own limit notice, so an agent the guard interrupts or freezes first never switches. Paseo and the recorder also measure only the CLI's own login. When ZeroSub is enabled on the host, Session Guard reads ZeroSub's registry and usage readings from `$PASEO_HOME/zerosub/` and changes its behaviour as follows:
+[ZeroSub](https://github.com/kapybara-org/zerosub) runs Claude and Codex agents on several subscription accounts. When an account hits a limit, ZeroSub moves the agent to another account and continues it. It switches only on the CLI's own limit notice, so an agent the guard interrupts or freezes first never switches. Paseo and the recorder also measure only the CLI's own login. When ZeroSub is enabled on the host, Pause at the limit reads ZeroSub's registry and usage readings from `$PASEO_HOME/zerosub/` and changes its behaviour as follows:
 
 - **Each agent is measured on its own account.**
   - An agent on an account ZeroSub added is paused only when *that* account reaches the threshold.
@@ -100,4 +96,4 @@ Workspace labels support text and color. Session Guard uses the short amber labe
 
 ## Agents
 
-Inside Paseo, the `budget_status` tool adds one line about the calling session: whether Session Guard will pause it at the limit and continue it afterwards, or whether it is paused now. It covers only the caller, never other sessions or continuation text, and it cannot turn protection off or resume a pause. Under ZeroSub, `budget_status` names the Claude account the session runs on. For an account ZeroSub added, it reports ZeroSub's reading of that account in place of the CLI login's history, and it says when ZeroSub has another account with room.
+Inside Paseo, the `budget_status` tool adds one line about the calling session: whether it pauses at the limit and continues afterwards, or whether it is paused now. It covers only the caller, never other sessions or continuation text, and it cannot turn protection off or resume a pause. Under ZeroSub, `budget_status` names the Claude account the session runs on. For an account ZeroSub added, it reports ZeroSub's reading of that account in place of the CLI login's history, and it says when ZeroSub has another account with room.

package/index.client.tsx

@@ -4,45 +4,29 @@ import type { PluginClientContext } from "@getpaseo/plugin/client";
 
 import { observeAgents } from "./client/agents";
 import { contributeChat } from "./client/chat";
-import { contributeGuardClient } from "./client/guard/index";
+import { commandItems } from "./client/commands";
+import { contributeGuardTimeline } from "./client/guard/index";
+import { watchGuard } from "./client/guard/status";
 import { createLive } from "./client/live";
-import { OVERVIEW_SCREEN, SMART_COMPACT_SETTINGS, makeOverview } from "./client/overview";
-import { contributeClient, refreshPills } from "./client/pill";
-import { SmartCompactSettings } from "./client/settings";
-import { enrolmentState } from "./shared/governor";
-import { budgetStatus, getSettings, setSettings } from "./shared/smart-session";
+import { OVERVIEW_SCREEN, PAUSED_SCREEN, SMART_COMPACT_SETTINGS, makeOverview } from "./client/overview";
+import { contributeClient } from "./client/pill";
+import { makeSettings } from "./client/settings";
+import { budgetStatus } from "./shared/smart-session";
 
 export default function contribute(host: PluginClientContext) {
   const visibility = withButtonVisibility(host);
   const client = visibility.client;
   const live = createLive();
+  const Overview = makeOverview(client, live);
   const removers = [
-    client.addScreen({ id: OVERVIEW_SCREEN, title: "Smart Session", Component: makeOverview(client, live) }),
-    client.addSettingsScreen({ id: SMART_COMPACT_SETTINGS, title: "Smart Compact", icon: "FoldVertical", Component: SmartCompactSettings }),
+    client.addScreen({ id: OVERVIEW_SCREEN, title: "Smart Session", Component: Overview }),
+    // The old Paused sessions screen: links to it from older chats and clients land on the list.
+    client.addScreen({ id: PAUSED_SCREEN, title: "Smart Session", Component: (props) => <Overview {...props} params={{ ...props.params, focus: "paused" }} /> }),
+    client.addSettingsScreen({ id: SMART_COMPACT_SETTINGS, title: "Settings", icon: "Gauge", Component: makeSettings(client) }),
     contributeDisplay(client, live),
-    client.addCommandCenterItem({
-      id: "smart-session-open",
-      title: "Smart Session: plan usage and context",
-      icon: "Gauge",
-      keywords: ["usage", "budget", "limit", "forecast", "context", "tokens", "compact", "smart session"],
-      context: "global",
-      onSelect({ openScreen }) {
-        openScreen({ screenId: OVERVIEW_SCREEN });
-      },
-    }),
-    client.addCommandCenterItem({
-      id: "smart-session-pill",
-      title: "Show or hide the context pill",
-      icon: "ToggleLeft",
-      keywords: ["pill", "compact", "smart", "context", "ring", "enrol"],
-      context: "global",
-      async onSelect({ rpc }) {
-        const { settings } = await rpc(getSettings, {});
-        await rpc(setSettings, { showPill: !settings.showPill });
-        await refreshPills(() => rpc(enrolmentState, {}));
-      },
-    }),
+    ...commandItems().map((item) => client.addCommandCenterItem(item)),
     contributeChat(client),
+    contributeGuardTimeline(client),
   ];
 
   // The sidebar row shows the session window between overview visits.
@@ -50,13 +34,14 @@ export default function contribute(host: PluginClientContext) {
   void readBudget();
   const budgetTimer = setInterval(() => void readBudget(), 2 * 60_000);
 
-  // One agent observation for every pill in this bundle.
+  // One agent observation and one protection poll for the one pill.
   const agents = observeAgents(client);
-  const removeClient = contributeClient(client, agents);
-  const removeGuard = contributeGuardClient(client, agents, live);
+  const stopGuard = watchGuard(client, live);
+  // The pill registers on the host's own client: a paused session keeps it even when pills are hidden.
+  const removeClient = contributeClient(host, agents);
   return () => {
     clearInterval(budgetTimer);
-    removeGuard();
+    stopGuard();
     removeClient();
     for (const remove of removers.splice(0)) void remove();
     visibility.dispose();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {

package/paseo-plugin.json

@@ -9,6 +9,7 @@
     "docs/media/smart-session-pill.png",
     "docs/media/smart-session-chat.png",
     "docs/media/smart-session-guard.png",
+    "docs/media/smart-session-settings.png",
     "docs/media/smart-session-mobile.png"
   ],
   "requirements": {