paseo-smart-session 2.0.0 → 2.1.0

package/server/guard/index.ts

@@ -0,0 +1,395 @@
+/**
+ * Session Guard's wiring: settings, the governor loop, RPCs and lifecycle hooks.
+ *
+ * The engine (`./engine.ts`) decides what to pause and when to continue; this file
+ * decides whether this process may run it at all. Only one process per host may:
+ *
+ * - With the feature off, nothing here holds the lock or touches a session.
+ * - While the standalone `paseo-session-guard` plugin is configured and enabled, this
+ *   one never governs, even if it could take the lock: that plugin's teardown resumes
+ *   every suspended session in the shared state whether or not it owns it
+ *   (`./standalone.ts`). If it becomes enabled while this one governs, this one
+ *   releases its suspended workers, gives the lock back and waits.
+ * - Otherwise it takes `governor.lock` in the shared state directory (`./store.ts`).
+ *   If another live process holds it, this one defers and retries on every poll.
+ * - Turned off again, it stops pausing at once, releases suspended workers on its next
+ *   pass, and gives the lock back once no pause is left waiting on it.
+ */
+
+import type { PluginHandlerContext, PluginServerContext } from "@getpaseo/plugin/server";
+
+import {
+  agentStatusRpc,
+  cancelResumeRpc,
+  demoPauseRpc,
+  dismissPauseRpc,
+  guardPreferences,
+  resumeNowRpc,
+  runtimeRpc,
+  setProtectionRpc,
+  statusRpc,
+  type Governor,
+} from "../../shared/guard/contracts.ts";
+import { isPending, PolicySchema, sessionWindow, usedPct, type Policy, type State, type Usage } from "../../shared/guard/policy.ts";
+import { agentGuardSummary, callerProtection } from "../../shared/guard/presentation.ts";
+import { withDaemon } from "../daemon.ts";
+import { freshestUsage } from "../store.ts";
+import type { Connect, GuardClient } from "./client.ts";
+import { Engine } from "./engine.ts";
+import { WorkspaceLabels } from "./labels.ts";
+import { LinuxProcessControl, type ProcessControl } from "./processes.ts";
+import { standaloneEnabled } from "./standalone.ts";
+import { guardDataDir, LockHeldError, Store } from "./store.ts";
+import { timelinePublisher } from "./timeline.ts";
+import { withRecordedUsage } from "./usage.ts";
+
+/** The install id this plugin's own RPCs are reached through. */
+const PLUGIN_ID = "smart-session";
+
+/** How often to retry the lock while another process holds it. */
+const DEFERRED_RETRY_SECONDS = 15;
+
+const STANDALONE_MESSAGE =
+  "The standalone Session Guard plugin is enabled on this host, so Smart Session leaves session protection to it and pauses nothing. " +
+  "Disable or uninstall Session Guard to hand over; its per-session choices and waiting pauses carry over.";
+const HANDED_BACK_MESSAGE =
+  "The standalone Session Guard plugin was enabled while Smart Session was protecting this host, so Smart Session released its paused sessions and stopped. " +
+  "Disable or uninstall Session Guard to hand back to Smart Session, or reload Session Guard to let it take over.";
+const LOCK_HELD_MESSAGE =
+  "Another process is already running Session Guard on this host, most likely a second Smart Session install. Nothing is paused from here until it stops.";
+const UNCHECKED_MESSAGE = "Session Guard could not check which plugins are installed, so it is not pausing anything yet. It will retry.";
+const OFF_MESSAGE = "Session Guard is off on this host. Turn it on in Smart Session's Session Guard settings.";
+
+/** The daemon connection and process control, replaceable only by tests. */
+export interface GuardDependencies {
+  connect?: Connect;
+  processes?: ProcessControl;
+}
+
+export function contributeGuard(server: PluginServerContext, options: GuardDependencies = {}): () => Promise<void> {
+  const settings = server.registerSettings(guardPreferences);
+  let settingsError: string | null = null;
+  const readPolicy = async (): Promise<Policy> => {
+    const result = await settings.read();
+    if (result.status !== "ready") throw new Error("Session Guard settings are invalid.");
+    return PolicySchema.parse(result.values);
+  };
+
+  // The guard's own connections, so teardown can close one that is mid-call without
+  // touching a delivery the compaction governor has in flight on another socket.
+  const open = new Set<{ close(): Promise<void> }>();
+  let disposed = false;
+  const daemon: Connect = options.connect ?? ((work) => withDaemon((client) => work(client as unknown as GuardClient)));
+  const connect: Connect = (work) => {
+    if (disposed) return Promise.reject(new Error("Session Guard is stopping."));
+    return daemon(async (client) => {
+      const closable = client as unknown as { close(): Promise<void> };
+      open.add(closable);
+      try {
+        // The same Paseo client the recorder uses, read through the guard's typed view.
+        return await work(client);
+      } finally {
+        open.delete(closable);
+      }
+    });
+  };
+
+  // Timeline appends need the host-owned API, which only an RPC handler receives.
+  let runtime: PluginHandlerContext["paseo"] | null = null;
+  server.handle(runtimeRpc, (_, context) => {
+    runtime = context.paseo;
+    return { ok: true };
+  });
+  const publish = timelinePublisher(async () => {
+    if (!runtime) {
+      await connect(async (client) => {
+        if (!client.invokePluginRpc) throw new Error("Plugin runtime API is unavailable.");
+        await client.invokePluginRpc(PLUGIN_ID, runtimeRpc.name, {});
+      });
+    }
+    if (!runtime) throw new Error("Plugin runtime API is unavailable.");
+    return runtime;
+  });
+
+  const store = new Store(guardDataDir());
+  const readUsage = async (client: GuardClient): Promise<Usage> =>
+    withRecordedUsage(await client.listProviderUsage(), await freshestUsage().catch(() => null));
+  const engine = new Engine(store, readPolicy, connect, Date.now, options.processes ?? new LinuxProcessControl(), publish, readUsage);
+  const labels = new WorkspaceLabels(store, (work) => engine.exclusive(work), connect, readPolicy);
+
+  let governor: Governor = "off";
+  let lockError: string | null = null;
+  let release: (() => Promise<void>) | null = null;
+
+  const claim = async () => {
+    try {
+      release = await store.lock();
+    } catch (error) {
+      governor = error instanceof LockHeldError ? "deferred" : "error";
+      lockError = governor === "deferred" ? LOCK_HELD_MESSAGE : "Session Guard could not take its lock. Check its saved state and try again.";
+      return;
+    }
+    try {
+      await engine.recover();
+      governor = "active";
+      lockError = null;
+    } catch {
+      governor = "error";
+      lockError = "Session Guard could not read its saved state. Restore state.json before continuing.";
+      const unlock = release;
+      release = null;
+      await unlock?.();
+    }
+  };
+
+  /** Gives the lock back, but only with nothing left that needs an owner. */
+  const standDown = async () => {
+    const idle = await engine.exclusive(async () => !(await store.read()).pauses.some(isPending));
+    if (!idle) return;
+    await engine.deliverTimeline();
+    await labels.refresh();
+    await engine.exclusive(async () => {
+      if ((await store.read()).pauses.some(isPending)) return;
+      governor = "off";
+      const unlock = release;
+      release = null;
+      await unlock?.();
+    });
+  };
+
+  /** True or false from the daemon's plugin list; null when it could not be read. */
+  let standalone: boolean | null = null;
+  const checkStandalone = async () => {
+    try {
+      standalone = await connect(async (client) => (client.listPlugins ? standaloneEnabled(await client.listPlugins()) : false));
+    } catch {
+      standalone = null;
+    }
+  };
+
+  /** Steps aside for an enabled standalone plugin: nothing frozen is left without an owner. */
+  const handBack = async () => {
+    governor = "deferred"; // Refuse new actions before releasing anything.
+    lockError = HANDED_BACK_MESSAGE;
+    try {
+      await engine.releaseWorkers();
+    } catch {
+      lockError = `${HANDED_BACK_MESSAGE} Some paused sessions could not be released; check them.`;
+    }
+    await engine.exclusive(async () => {
+      const unlock = release;
+      release = null;
+      await unlock?.();
+    });
+  };
+
+  const pass = async (): Promise<Policy | null> => {
+    let policy: Policy | null = null;
+    try {
+      policy = await readPolicy();
+      settingsError = null;
+    } catch {
+      settingsError = "Session Guard settings are invalid. Reset them in Session Guard settings.";
+    }
+    if (!policy?.enabled && governor !== "active") {
+      governor = "off";
+      lockError = null;
+      return policy;
+    }
+    await checkStandalone();
+    if (governor === "active") {
+      if (standalone === true) {
+        await handBack();
+        return policy;
+      }
+    } else if (standalone === true) {
+      governor = "deferred";
+      // Keep the fuller explanation if this process just handed the host back.
+      if (!lockError?.startsWith(HANDED_BACK_MESSAGE)) lockError = STANDALONE_MESSAGE;
+      return policy;
+    } else if (standalone === null) {
+      governor = "error";
+      lockError = UNCHECKED_MESSAGE;
+      return policy;
+    } else {
+      await claim();
+    }
+    if (governor !== "active") return policy;
+    await engine.tick();
+    void engine.deliverTimeline();
+    void labels.refresh();
+    if (policy !== null && !policy.enabled) await standDown();
+    return policy;
+  };
+
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let current: Promise<void> | null = null;
+  let again = false;
+  const refresh = (): Promise<void> => {
+    if (stopped) return Promise.resolve();
+    if (current) {
+      again = true; // A settings change mid-pass must not wait out a whole interval.
+      return current;
+    }
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    current = (async () => {
+      let policy: Policy | null = null;
+      try {
+        policy = await pass();
+      } catch {
+        // Each step records its own error for the status RPC; the loop must survive.
+      }
+      current = null;
+      if (stopped) return;
+      if (again) {
+        again = false;
+        void refresh();
+        return;
+      }
+      // Off needs no timer: turning it on arrives through the settings subscription.
+      if (governor === "active") timer = setTimeout(() => void refresh(), (policy?.pollSeconds ?? 15) * 1000);
+      else if (governor !== "off") timer = setTimeout(() => void refresh(), DEFERRED_RETRY_SECONDS * 1000);
+    })();
+    return current;
+  };
+
+  const requireOwner = async () => {
+    if (current) await current;
+    if (stopped) throw new Error("Session Guard is stopping.");
+    if (governor !== "active") throw new Error(lockError ?? OFF_MESSAGE);
+  };
+  /** Readable whether or not this process governs: the file is replaced atomically. */
+  const readState = async (): Promise<State> => (governor === "active" ? engine.exclusive(() => store.read()) : store.read());
+  const readPolicyOrDefaults = () => readPolicy().catch(() => PolicySchema.parse({}));
+  const emptyState = (): State => ({ version: 1, overrides: {}, pauses: [] });
+  const providerRows = (policy: Policy) =>
+    (governor === "active" ? (engine.usage?.providers ?? []) : []).map((provider) => {
+      const window = sessionWindow(provider, policy);
+      return { providerId: provider.providerId, usedPct: window ? usedPct(window) : null, resetsAt: window?.resetsAt ?? null };
+    });
+  const afterAction = () => {
+    void engine.deliverTimeline();
+    void labels.refresh();
+  };
+
+  server.handle(statusRpc, async (_, context) => {
+    runtime = context.paseo;
+    const policy = await readPolicyOrDefaults();
+    let state = emptyState();
+    let stateError: string | null = null;
+    try {
+      state = await readState();
+    } catch (error) {
+      stateError = error instanceof Error ? error.message : String(error);
+    }
+    const active = governor === "active";
+    return {
+      governor,
+      standalone: governor === "off" ? null : standalone,
+      checkedAt: active ? engine.checkedAt : null,
+      error: lockError ?? settingsError ?? stateError ?? (active ? (engine.error ?? engine.timelineError ?? labels.error) : null),
+      pauses: state.pauses,
+      overrides: state.overrides,
+      policy,
+      providers: providerRows(policy),
+    };
+  });
+
+  server.handle(agentStatusRpc, async ({ agentId }) => {
+    const policy = await readPolicyOrDefaults();
+    const state = await readState().catch(emptyState);
+    const protection = callerProtection(governor === "active" && policy.enabled, policy.protectByDefault, state.overrides[agentId]);
+    const pauses = state.pauses
+      .filter((pause) => pause.agentId === agentId)
+      .map((pause) => ({ id: pause.id, phase: pause.phase, provider: pause.provider, resetsAt: pause.anchorResetsAt }));
+    return {
+      governor,
+      ...protection,
+      thresholdPct: policy.thresholdPct,
+      autoResume: policy.autoResume,
+      pauses,
+      providers: providerRows(policy),
+      summary: agentGuardSummary({ governor, protected: protection.protected, thresholdPct: policy.thresholdPct, autoResume: policy.autoResume, pauses }),
+    };
+  });
+
+  server.handle(setProtectionRpc, async ({ agentId, enabled }) => {
+    await requireOwner();
+    await engine.setProtection(agentId, enabled);
+    afterAction();
+    void refresh();
+    return { ok: true };
+  });
+  server.handle(cancelResumeRpc, async ({ agentId }) => {
+    await requireOwner();
+    await engine.cancelResume(agentId);
+    afterAction();
+    return { ok: true };
+  });
+  server.handle(resumeNowRpc, async ({ agentId, pauseId }) => {
+    await requireOwner();
+    await engine.resumeNow(agentId, pauseId);
+    afterAction();
+    return { ok: true };
+  });
+  server.handle(dismissPauseRpc, async ({ agentId, pauseId }) => {
+    await requireOwner();
+    await engine.dismissPause(agentId, pauseId);
+    afterAction();
+    return { ok: true };
+  });
+  server.handle(demoPauseRpc, async ({ agentId }) => {
+    await requireOwner();
+    await engine.pauseDemo(agentId);
+    afterAction();
+    return { ok: true };
+  });
+
+  const removeSettings = settings.subscribe(() => {
+    void refresh();
+  });
+  const removeTurnStarted = server.on("agent.turn_started", () => {
+    if (governor !== "off") void refresh();
+  });
+  const removeTurnEnded = server.on("agent.turn_ended", (event) => {
+    if (governor !== "active") return;
+    // Never await a governor tick inside a lifecycle hook: cancelAgent itself causes
+    // turn_ended, and awaiting both would deadlock.
+    if (!stopped) void engine.turnEnded(event.agent.id, event.turnId, event.outcome.kind).catch(() => undefined);
+    if (event.outcome.kind === "failed") engine.quotaFailure(event.agent.id, event.outcome.error.message, event.turnId);
+    void refresh();
+  });
+
+  void refresh();
+
+  return async () => {
+    stopped = true;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    removeSettings();
+    removeTurnStarted();
+    removeTurnEnded();
+    disposed = true;
+    await Promise.allSettled([...open].map((client) => client.close()));
+    await current?.catch(() => undefined);
+    try {
+      // Only the owner may touch suspended workers: a deferring process must leave the
+      // other governor's pauses exactly as they are.
+      if (governor === "active") {
+        try {
+          await engine.stop();
+        } finally {
+          await labels.stop();
+        }
+      }
+    } finally {
+      // Always give the lock back, even when a release failed: this process is exiting,
+      // and a held lock would only keep the next governor waiting.
+      const unlock = release;
+      release = null;
+      await unlock?.();
+    }
+  };
+}

package/server/guard/labels.ts

@@ -0,0 +1,77 @@
+import type { Connect } from "./client.ts";
+import type { Store } from "./store.ts";
+import type { Policy } from "../../shared/guard/policy.ts";
+
+export const PAUSED_WORKSPACE_LABEL = { name: "Paused", color: "amber" as const };
+type Exclusive = <T>(work: () => Promise<T>) => Promise<T>;
+
+/** Label delivery never holds the governor's action lock during daemon I/O. */
+export class WorkspaceLabels {
+  private store: Store;
+  private exclusive: Exclusive;
+  private connect: Connect;
+  private policy: () => Promise<Policy>;
+  private pending: Promise<void> | null = null;
+  private stopped = false;
+  error: string | null = null;
+  constructor(store: Store, exclusive: Exclusive, connect: Connect, policy: () => Promise<Policy>) {
+    this.store = store; this.exclusive = exclusive; this.connect = connect; this.policy = policy;
+  }
+  refresh(): Promise<void> {
+    if (this.stopped) return Promise.resolve();
+    if (this.pending) return this.pending;
+    this.pending = this.reconcile().catch(() => {
+      this.error = "Workspace pause labels are awaiting delivery. Session protection is still active; labels will retry.";
+    }).finally(() => { this.pending = null; });
+    return this.pending;
+  }
+  private async reconcile() {
+    const pauses = await this.exclusive(async () => (await this.store.read()).pauses.filter(p => ["waiting", "resuming"].includes(p.phase)));
+    const assignments = new Map<string, string>();
+    if (pauses.length) await this.connect(async client => {
+      for (const pause of pauses) {
+        const agent = (await client.fetchAgent(pause.agentId))?.agent;
+        if (agent?.workspaceId) assignments.set(pause.id, agent.workspaceId);
+      }
+    });
+    await this.exclusive(async () => {
+      const state = await this.store.read(); let changed = false;
+      for (const pause of state.pauses) {
+        const workspaceId = assignments.get(pause.id);
+        if (workspaceId && pause.workspaceId !== workspaceId) { pause.workspaceId = workspaceId; changed = true; }
+      }
+      if (changed) await this.store.write(state);
+    });
+    // Re-read after every acknowledgement: another session may pause or resume
+    // while a label RPC is in flight. Journal ownership before an assignment so
+    // a lost acknowledgement or crash still lets us remove the label later.
+    const acknowledged = new Set<string>();
+    for (let i = 0; i < 400 && !this.stopped; i++) {
+      const policy = await this.policy();
+      const action = await this.exclusive(async () => {
+        const state = await this.store.read();
+        const desired = new Set(policy.workspaceLabels ? state.pauses.filter(p => ["waiting", "resuming"].includes(p.phase)).map(p => p.workspaceId).filter((id): id is string => !!id) : []);
+        const managed = state.labelledWorkspaces ?? [];
+        const name = state.workspaceLabelName ?? "Paused by Session Guard";
+        const remove = managed.find(id => name !== PAUSED_WORKSPACE_LABEL.name || !desired.has(id));
+        if (remove) return { workspaceId: remove, assigned: false, name };
+        const add = [...desired].find(id => !acknowledged.has(id));
+        if (!add) return null;
+        if (!managed.includes(add)) { state.labelledWorkspaces = [...managed, add]; state.workspaceLabelName = PAUSED_WORKSPACE_LABEL.name; await this.store.write(state); }
+        return { workspaceId: add, assigned: true, name: PAUSED_WORKSPACE_LABEL.name };
+      });
+      if (!action) { this.error = null; return; }
+      await this.connect(async client => {
+        if (!client.setWorkspaceLabel) throw new Error("Workspace labels are unavailable on this Paseo host.");
+        await client.setWorkspaceLabel({ workspaceId: action.workspaceId, assigned: action.assigned, label: { ...PAUSED_WORKSPACE_LABEL, name: action.name } });
+      });
+      if (action.assigned) acknowledged.add(action.workspaceId);
+      else await this.exclusive(async () => {
+        const state = await this.store.read();
+        state.labelledWorkspaces = (state.labelledWorkspaces ?? []).filter(id => id !== action.workspaceId);
+        await this.store.write(state);
+      });
+    }
+  }
+  async stop() { this.stopped = true; await this.pending; }
+}

package/server/guard/processes.ts

@@ -0,0 +1,147 @@
+import { readFile, readdir } from "node:fs/promises";
+import type { Agent, Pause } from "../../shared/guard/policy.ts";
+
+export type Suspension = NonNullable<Pause["suspension"]>;
+type Identity = Suspension["processes"][number];
+type Snapshot = Identity & { ppid: number; state: string };
+export interface ProcessControl {
+  discover(agent: Agent, daemonPid: number): Promise<Suspension | null>;
+  freeze(suspension: Suspension, journal: () => Promise<void>): Promise<void>;
+  resume(suspension: Suspension): Promise<void>;
+  stopped(suspension: Suspension): Promise<boolean>;
+  alive?(suspension: Suspension): Promise<boolean>;
+  owned?(suspension: Suspension): Promise<boolean>;
+  daemonIdentity?(): Promise<string>;
+}
+
+/** Linux process suspension keeps native workers and their in-memory turns intact.
+ * Roots must be direct children of this daemon with its exact injected agent ID.
+ * No process-name scans, credentials, transcripts, or provider sessions are used.
+ */
+export class LinuxProcessControl implements ProcessControl {
+  private readonly daemonPid: number;
+  constructor(daemonPid: number = process.ppid) { this.daemonPid = daemonPid; }
+  private async inspect(pid: number): Promise<Snapshot | null> {
+    try {
+      const raw = await readFile(`/proc/${pid}/stat`, "utf8");
+      const fields = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/);
+      if (!fields[19] || !Number.isInteger(Number(fields[1]))) return null;
+      return { pid, state: fields[0], ppid: Number(fields[1]), startTime: fields[19] };
+    } catch (error) {
+      if (["ENOENT", "ESRCH"].includes((error as NodeJS.ErrnoException).code ?? "")) return null;
+      throw new Error("Provider process could not be inspected.");
+    }
+  }
+  private async table(): Promise<Snapshot[]> {
+    const entries = await readdir("/proc");
+    const result: Snapshot[] = [];
+    // Bounded batches avoid opening one descriptor per host process at once.
+    const pids = entries.filter(name => /^\d+$/.test(name)).map(Number);
+    for (let i = 0; i < pids.length; i += 64) {
+      const batch = await Promise.all(pids.slice(i, i + 64).map(pid => this.inspect(pid)));
+      result.push(...batch.filter((item): item is Snapshot => item !== null));
+    }
+    return result;
+  }
+  async discover(agent: Agent, daemonPid: number): Promise<Suspension | null> {
+    if (process.platform !== "linux" || !["claude", "codex"].includes(agent.provider)) return null;
+    if (!Number.isInteger(daemonPid) || daemonPid <= 1 || daemonPid !== this.daemonPid || daemonPid === process.pid) return null;
+    const candidates: Snapshot[] = [];
+    for (const child of (await this.table()).filter(p => p.ppid === daemonPid)) {
+      if (child.pid === process.pid || ["T", "t", "Z", "X"].includes(child.state)) continue;
+      try {
+        const environment = await readFile(`/proc/${child.pid}/environ`);
+        const owner = environment.toString().split("\0").find(field => field.startsWith("PASEO_AGENT_ID="));
+        if (owner === `PASEO_AGENT_ID=${agent.id}`) candidates.push(child);
+      } catch (error) {
+        if (!["ENOENT", "ESRCH", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+      }
+    }
+    // Ambiguous ownership must never freeze a shared process or another session.
+    if (candidates.length !== 1) return null;
+    const root = candidates[0];
+    return { rootPid: root.pid, processes: [{ pid: root.pid, startTime: root.startTime }] };
+  }
+  private async signal(identity: Identity, signal: "SIGSTOP" | "SIGCONT"): Promise<boolean> {
+    if (identity.pid <= 1 || identity.pid === process.pid || identity.pid === process.ppid) throw new Error("Unsafe provider process identity.");
+    const snapshot = await this.inspect(identity.pid);
+    if (!snapshot || snapshot.startTime !== identity.startTime || ["Z", "X"].includes(snapshot.state)) return false;
+    try { process.kill(identity.pid, signal); return true; }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ESRCH") return false;
+      throw new Error("Provider process signal failed.");
+    }
+  }
+  async freeze(suspension: Suspension, journal: () => Promise<void>): Promise<void> {
+    const root = suspension.processes.find(p => p.pid === suspension.rootPid);
+    if (!root || !await this.signal(root, "SIGSTOP")) throw new Error("Provider process exited before suspension.");
+    // Stop the root before traversing. Descendants are then stopped as discovered;
+    // repeat to catch a tool worker that forked during the previous scan.
+    const seen = new Set(suspension.processes.map(p => `${p.pid}:${p.startTime}`));
+    for (let pass = 0; pass < 8; pass++) {
+      const table = await this.table();
+      const owned = new Set<number>();
+      for (const p of suspension.processes) {
+        if (table.some(s => s.pid === p.pid && s.startTime === p.startTime)) owned.add(p.pid);
+      }
+      let grew = true;
+      while (grew) {
+        grew = false;
+        for (const p of table) if (owned.has(p.ppid) && !owned.has(p.pid)) { owned.add(p.pid); grew = true; }
+      }
+      const additions = table.filter(p => owned.has(p.pid) && !seen.has(`${p.pid}:${p.startTime}`) && !["Z", "X"].includes(p.state));
+      if (!additions.length) {
+        if (!await this.stopped(suspension)) throw new Error("Provider suspension was externally changed.");
+        return;
+      }
+      for (const p of additions) {
+        seen.add(`${p.pid}:${p.startTime}`);
+        // A worker already stopped by a person/debugger is never ours to resume.
+        if (["T", "t"].includes(p.state)) continue;
+        suspension.processes.push({ pid: p.pid, startTime: p.startTime });
+        await journal(); // Durable identity before each signal, including crash windows.
+        await this.signal(p, "SIGSTOP");
+      }
+    }
+    throw new Error("Provider process tree did not settle.");
+  }
+  async resume(suspension: Suspension): Promise<void> {
+    let failed = false;
+    // Tools first, then root, so the provider can consume their pending responses.
+    for (const p of [...suspension.processes].reverse()) {
+      try { await this.signal(p, "SIGCONT"); } catch { failed = true; }
+    }
+    if (failed) throw new Error("Some suspended provider processes could not be released.");
+  }
+  async stopped(suspension: Suspension): Promise<boolean> {
+    const root = suspension.processes.find(p => p.pid === suspension.rootPid);
+    if (!root) return false;
+    const snapshot = await this.inspect(root.pid);
+    if (!snapshot || snapshot.startTime !== root.startTime || !["T", "t"].includes(snapshot.state)) return false;
+    for (const p of suspension.processes) {
+      if (p.pid === root.pid) continue;
+      const child = await this.inspect(p.pid);
+      if (child && child.startTime === p.startTime && !["T", "t", "Z", "X"].includes(child.state)) return false;
+    }
+    return true;
+  }
+  async daemonIdentity(): Promise<string> {
+    if (process.platform !== "linux") return `portable:${this.daemonPid}`;
+    const boot = (await readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim();
+    const daemon = await this.inspect(this.daemonPid);
+    if (!daemon) throw new Error("Daemon identity is unavailable.");
+    return `${boot}:${daemon.pid}:${daemon.startTime}`;
+  }
+  async owned(suspension: Suspension): Promise<boolean> {
+    const root = suspension.processes.find(p => p.pid === suspension.rootPid);
+    if (!root) return false;
+    const snapshot = await this.inspect(root.pid);
+    return !!snapshot && snapshot.startTime === root.startTime && snapshot.ppid === this.daemonPid;
+  }
+  async alive(suspension: Suspension): Promise<boolean> {
+    const root = suspension.processes.find(p => p.pid === suspension.rootPid);
+    if (!root) return false;
+    const snapshot = await this.inspect(root.pid);
+    return !!snapshot && snapshot.startTime === root.startTime && !["Z", "X"].includes(snapshot.state);
+  }
+}

package/server/guard/standalone.ts

@@ -0,0 +1,61 @@
+/**
+ * Recognising the standalone `paseo-session-guard` plugin among the daemon's plugins.
+ *
+ * Sharing its lock keeps the two plugins from pausing a session twice, but it does not
+ * cover the standalone plugin's teardown: released versions call `engine.stop()` on
+ * disable or uninstall whether or not they hold the lock, which resumes every
+ * suspended session in `state.json` and rewrites the file. Those versions cannot be
+ * changed, so Smart Session refuses to govern at all while the standalone plugin is
+ * configured and enabled. A disabled one has already run that teardown and is safe.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const STANDALONE_ID = "paseo-session-guard";
+
+/** The fields of the daemon's plugin listing this reads; older daemons omit some. */
+export interface ListedPlugin {
+  readonly id: string;
+  readonly path?: string;
+  readonly enabled: boolean;
+  readonly remote?: string;
+  readonly npm?: { readonly packageName?: string };
+}
+
+type ReadText = (path: string) => Promise<string>;
+const readText: ReadText = (path) => readFile(path, "utf8");
+
+async function readJson(read: ReadText, path: string): Promise<Record<string, unknown> | null> {
+  try {
+    const value = JSON.parse(await read(path)) as unknown;
+    return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether one listed plugin is the standalone Session Guard.
+ *
+ * The install id can be anything (`--id`), so the manifest and package name in its
+ * directory are checked too, along with the npm package and Git remote the daemon
+ * recorded.
+ */
+export async function isStandalone(plugin: ListedPlugin, read: ReadText = readText): Promise<boolean> {
+  if (plugin.id === STANDALONE_ID || plugin.npm?.packageName === STANDALONE_ID) return true;
+  if (plugin.remote !== undefined && /[/:]paseo-session-guard(\.git)?\/?$/i.test(plugin.remote)) return true;
+  if (!plugin.path) return false;
+  const manifest = await readJson(read, join(plugin.path, "paseo-plugin.json"));
+  if (manifest?.id === STANDALONE_ID) return true;
+  const pkg = await readJson(read, join(plugin.path, "package.json"));
+  return pkg?.name === STANDALONE_ID;
+}
+
+/** Whether any configured, enabled plugin is the standalone Session Guard. */
+export async function standaloneEnabled(plugins: readonly ListedPlugin[], read: ReadText = readText): Promise<boolean> {
+  for (const plugin of plugins) {
+    if (plugin.enabled && (await isStandalone(plugin, read))) return true;
+  }
+  return false;
+}