@saadnvd1/agent-os 0.3.488 → 0.3.493

package/README.md

@@ -920,7 +920,13 @@ other sessions. Sessions sit on shelves: **Pinned** (pin from a row's ⋯
 menu), **Needs you** (an approval, a question, a terminal waiting for input, a
 message typed and never sent, a failed task, or the orchestrator's open asks,
 each with a badge), **Working**,
-and **Done**, newest first, ten at a time. A purple dot marks a session that
+and **Done**. Done is folded to one row, "3 done today · 12 earlier", until you
+tap it (open or folded is remembered per device); open, it lists newest first,
+ten at a time. The orchestrator's row carries small chips for the work it
+started: running, in review, blocked and queued, each left out at zero. Tap
+them to show only that orchestrator's work on the same shelves; the "Showing
+… work ×" chip at the top clears it (it resets on reload). A session an
+orchestrator started has a small orchestrator icon on its row. A purple dot marks a session that
 finished or changed since you last opened it. Search matches
 titles and project names, and the project filter narrows the list to one
 project and holds that project's own actions: new session, terminal, dev
@@ -1059,7 +1065,31 @@ it may do on its own, and the lines that always come back to you as asks.
   arrives marked as from that orchestrator and fenced as untrusted, so it can't
   approve, answer an ask or pass a gate. The route
   they call answers only the orchestrator's worker, by a per-orchestrator
-  secret. Its shell runs only `aos` commands that read.
+  secret.
+- **Shell:** it runs anything without asking, so an orchestrator can read and
+  investigate on its own: `gh pr list`, `gh run view --log-failed`, `gh api`
+  GETs, `curl`, `sqlite3 -readonly`, git in any repository, a skill's scripts,
+  pipes and chains. Its chat worker refuses a deny list before a command runs,
+  naming the tool to use instead: merging, closing or retargeting a PR
+  (`gh pr merge`, `gh pr close`, `gh pr edit --base`, and `gh api` or `curl`
+  calls that merge a pull request or PATCH or PUT one; use `sign_off`, `arm`,
+  `land` or `drop`), `git push` (`quick_pr` pushes), writing in a project
+  repository or task worktree other than its own open quick changes (git
+  commit, reset, checkout, rebase, merge, stash, clean or rm there, and `rm`,
+  `mv`, `cp`, `tee` or a redirect into one), writing AgentOS's state (`sqlite3`
+  on its database without `-readonly` or with INSERT, UPDATE, DELETE, DROP,
+  ALTER or ATTACH; files under `~/.agent-os` outside its folder), stopping
+  AgentOS or its tmux (`pkill`/`kill` aimed at it, `tmux kill-*`, a
+  `launchctl` or `serviceman` restart), and reading secret files (the same
+  list as the write guard) or tokenvault (`tv get`, `tv dump`). It reads each
+  command line the way a shell would, so these are caught inside pipes,
+  chains and `$( )`, behind `bash -c`, `sh -c`, `env`, `sudo`, `xargs`,
+  `find -exec` or an absolute path, and after a `cd` or `git -C`. **The deny
+  list catches honest mistakes, not a determined bypass:** a script or
+  `python -c` can do any of these where no parser sees it, and an
+  orchestrator reads other sessions' text, which can carry planted
+  instructions. The trade-off was chosen on 2026-10-11, for an orchestrator
+  that does its own investigating instead of handing it to him.
 - **Triage:** its brief has it decide each job: small and clear is a task with
   `plan: false` and the steps written into the brief; big, unclear or
   cross-cutting is `plan: true`; work outside a repository is a

package/components/Chat/ChatPanel.tsx

@@ -226,6 +226,7 @@ export function ChatPanel({
     earlierTasks,
     toolBodies,
     requestToolBody,
+    pinToolBody,
     state,
     connected,
     commands,
@@ -364,8 +365,13 @@ export function ChatPanel({
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const rowState = useMemo(() => new RowStore(), [sessionId]);
   const bodies = useMemo(
-    () => ({ bodies: toolBodies, request: requestToolBody, connected }),
-    [toolBodies, requestToolBody, connected]
+    () => ({
+      bodies: toolBodies,
+      request: requestToolBody,
+      pin: pinToolBody,
+      connected,
+    }),
+    [toolBodies, requestToolBody, pinToolBody, connected]
   );
   const itemsById = useMemo(
     () => new Map(items.map((i) => [i.id, i])),

package/components/Chat/Tools.tsx

@@ -5,6 +5,7 @@ import { Check, ChevronRight, Loader2, Square, X } from "lucide-react";
 import type { FileDiff, ToolBody } from "@/lib/chat/events";
 import type { ToolItem } from "@/lib/chat/group";
 import { lineDiff, shortPath, type DiffLine } from "@/lib/chat/diff";
+import { needsBody } from "@/lib/chat/bodyCache";
 import { cn } from "@/lib/utils";
 import { formatElapsed } from "@/lib/chat/elapsed";
 import { Highlighted } from "./Code";
@@ -16,16 +17,21 @@ import { useRowState } from "./rowState";
 export const ToolBodies = createContext<{
   bodies: Record<string, ToolBody | null>;
   request: (id: string) => void;
+  // Marks a body as on screen until the returned cleanup runs.
+  pin: (id: string) => () => void;
   connected: boolean;
-}>({ bodies: {}, request: () => {}, connected: false });
+}>({ bodies: {}, request: () => {}, pin: () => () => {}, connected: false });
 
 // A tool call's output and diff: its own, or once loaded. `undefined` while
 // it loads.
 export function useToolBody(tool: ToolItem): ToolBody | null | undefined {
-  const { bodies, request, connected } = useContext(ToolBodies);
+  const { bodies, request, pin, connected } = useContext(ToolBodies);
   const body = tool.deferred ? bodies[tool.id] : tool;
   useEffect(() => {
-    if (tool.deferred && body === undefined && connected) request(tool.id);
+    if (tool.deferred) return pin(tool.id);
+  }, [tool.deferred, tool.id, pin]);
+  useEffect(() => {
+    if (needsBody(tool.deferred, body, connected)) request(tool.id);
   }, [tool.deferred, tool.id, body, request, connected]);
   return body;
 }

package/components/SessionList/OrchestratorPinRow.test.ts

@@ -77,6 +77,8 @@ describe("OrchestratorPinRow", () => {
     orchestrators: [],
     runningByWorkspace: new Map(),
     queuedByWorkspace: new Map(),
+    rollups: new Map(),
+    orchestratorNames: new Map(),
     orderedIds: () => [],
     cardUrl: () => null,
     onSelect,

package/components/SessionList/OrchestratorPinRow.tsx

@@ -6,6 +6,9 @@ import { Button } from "@/components/ui/button";
 import * as DM from "@/components/ui/dropdown-menu";
 import * as CM from "@/components/ui/context-menu";
 import { sameRow, type SidebarRow } from "@/lib/sidebar/shelves";
+import { visibleChips } from "@/lib/sidebar/rollup";
+import { sidebarUi, sidebarUiActions } from "@/stores/sidebarUi";
+import { useSnapshot } from "valtio";
 import { orchestratorRowText } from "@/lib/sidebar/orchestrator-row";
 import { cn } from "@/lib/utils";
 import { orchestratorOpenActions } from "@/stores/orchestratorOpen";
@@ -36,6 +39,9 @@ export const OrchestratorPinRow = memo(function OrchestratorPinRow({
     inReview: overview?.inReview ?? 0,
     queued: ctx.queuedByWorkspace.get(ws) ?? 0,
   });
+  const chips = visibleChips(ctx.rollups.get(session.id));
+  const { orchestratorId } = useSnapshot(sidebarUi);
+  const filtering = orchestratorId === session.id;
   const label = ctx.workspaceNames.get(ws) ?? "Orchestrator";
   const summary = asks ? `${status} · ${asks}` : status;
   const menu = (kind: "dropdown" | "context") => (
@@ -100,6 +106,36 @@ export const OrchestratorPinRow = memo(function OrchestratorPinRow({
                 </>
               )}
             </span>
+            {chips.length > 0 && (
+              <button
+                type="button"
+                aria-pressed={filtering}
+                title={`Show only ${label}'s work`}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  sidebarUiActions.setOrchestrator(
+                    filtering ? null : session.id
+                  );
+                }}
+                className={cn(
+                  "text-muted-foreground -mx-1 mt-0.5 flex min-h-6 flex-wrap items-center gap-x-2.5 rounded px-1 text-xs",
+                  "hover:bg-muted hover:text-foreground md:min-h-5",
+                  filtering && "bg-muted text-foreground"
+                )}
+              >
+                {chips.map((c) => (
+                  <span key={c.key} className="flex items-center gap-1">
+                    <span
+                      aria-hidden
+                      className={cn("h-1.5 w-1.5 rounded-full", c.dot)}
+                    />
+                    <span className="tabular-nums">
+                      {ctx.rollups.get(session.id)![c.key]} {c.label}
+                    </span>
+                  </span>
+                ))}
+              </button>
+            )}
           </>
         )}
       </span>

package/components/SessionList/RowContext.tsx

@@ -2,6 +2,7 @@
 
 import { createContext, useContext } from "react";
 import type { ProjectWithRepositories } from "@/lib/projects";
+import type { Rollup } from "@/lib/sidebar/rollup";
 import type { OrchestratorOverview } from "@/lib/orchestrator/overview";
 
 // What every row needs from the list, so shelves don't pass it along.
@@ -14,6 +15,9 @@ export interface RowContextValue {
   orchestrators: OrchestratorOverview[];
   runningByWorkspace: Map<string, number>;
   queuedByWorkspace: Map<string, number>;
+  // What each orchestrator session started, and its name (its workspace's).
+  rollups: Map<string, Rollup>;
+  orchestratorNames: Map<string, string>;
   // Render order, for shift-click range selection.
   orderedIds: () => string[];
   cardUrl: (sessionId: string) => string | null | undefined;

package/components/SessionList/SessionRow.tsx

@@ -2,7 +2,7 @@
 
 import { memo, useState } from "react";
 import { useSnapshot } from "valtio";
-import { CheckSquare, GitFork, Square } from "lucide-react";
+import { CheckSquare, GitFork, Square, Workflow } from "lucide-react";
 import { compactTimeAgo, fromSqliteTime } from "@/lib/session-meta";
 import { sameRow, type SidebarRow } from "@/lib/sidebar/shelves";
 import { useMinuteTick } from "@/hooks/useMinuteTick";
@@ -33,6 +33,9 @@ export const SessionRow = memo(function SessionRow({
   const [renaming, setRenaming] = useState(false);
   const { session } = row;
   const active = session.id === ctx.activeSessionId;
+  const viaName = session.started_by
+    ? ctx.orchestratorNames.get(session.started_by)
+    : undefined;
   const selecting = selectedIds.size > 0;
   const selected = selectedIds.has(session.id);
   const onClick = (e: React.MouseEvent) => {
@@ -76,9 +79,19 @@ export const SessionRow = memo(function SessionRow({
           )
         }
         aside={
-          session.parent_session_id && (
-            <GitFork className="text-muted-foreground/60 h-3 w-3 shrink-0" />
-          )
+          <>
+            {viaName && (
+              <span title={`Started by ${viaName}`} className="shrink-0">
+                <Workflow
+                  aria-label={`Via orchestrator: ${viaName}`}
+                  className="text-muted-foreground/60 h-3 w-3"
+                />
+              </span>
+            )}
+            {session.parent_session_id && (
+              <GitFork className="text-muted-foreground/60 h-3 w-3 shrink-0" />
+            )}
+          </>
         }
         trailing={
           <>

package/components/SessionList/SessionShelves.tsx

@@ -2,7 +2,12 @@
 
 import type { ReactNode } from "react";
 import { ChevronDown } from "lucide-react";
-import { DONE_PAGE, doneLimit, type Shelves } from "@/lib/sidebar/shelves";
+import {
+  DONE_PAGE,
+  doneLimit,
+  doneSummary,
+  type Shelves,
+} from "@/lib/sidebar/shelves";
 import type { MachineGroup } from "@/lib/sidebar/machines";
 import { sidebarUiActions } from "@/stores/sidebarUi";
 import { cn } from "@/lib/utils";
@@ -97,6 +102,7 @@ export function SessionShelves({
 }) {
   const shown = shelves.done.slice(0, doneLimit(donePages));
   const hidden = shelves.done.length - shown.length;
+  const summary = doneSummary(shelves.done).text;
   return (
     <>
       {shelves.orchestrators.length + toStart.length > 0 && (
@@ -140,7 +146,7 @@ export function SessionShelves({
       {shelves.done.length > 0 && (
         <section aria-label="Done">
           <ShelfLabel
-            label="Done"
+            label={doneCollapsed ? summary : "Done"}
             collapsed={doneCollapsed}
             onToggle={sidebarUiActions.toggleDone}
           />

package/components/SessionList/SidebarBody.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { AlertCircle, FolderPlus, Plus } from "lucide-react";
+import { AlertCircle, FolderPlus, Plus, X } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { ShimmeringLoader } from "@/components/ui/skeleton";
+import { sidebarUiActions } from "@/stores/sidebarUi";
 import type { SidebarData } from "./useSidebarData";
 import { MachineShelves, SessionShelves } from "./SessionShelves";
 import { SidebarExtras } from "./SidebarExtras";
@@ -71,6 +72,21 @@ export function SidebarBody({
 
   return (
     <>
+      {ui.orchestratorId && (
+        <button
+          type="button"
+          onClick={() => sidebarUiActions.setOrchestrator(null)}
+          aria-label="Clear the orchestrator filter"
+          className="bg-muted hover:bg-muted/70 text-foreground mx-2.5 mt-2 flex min-h-8 max-w-[calc(100%-1.25rem)] items-center gap-1.5 rounded-full px-3 text-xs md:min-h-7"
+        >
+          <span className="truncate">
+            Showing{" "}
+            {data.orchestratorNames.get(ui.orchestratorId) ?? "orchestrator"}
+            &rsquo;s work
+          </span>
+          <X className="h-3 w-3 shrink-0" />
+        </button>
+      )}
       <DraftShelf projects={data.projects} />
       {count === 0 &&
         (ui.query ? (

package/components/SessionList/index.tsx

@@ -110,6 +110,8 @@ export function SessionList({
       orchestrators,
       runningByWorkspace: data.runningByWorkspace,
       queuedByWorkspace: data.queuedByWorkspace,
+      rollups: data.rollupByOrchestrator,
+      orchestratorNames: data.orchestratorNames,
       cardUrl: data.taskCardUrl,
     }),
     [
@@ -122,6 +124,8 @@ export function SessionList({
       orchestrators,
       data.runningByWorkspace,
       data.queuedByWorkspace,
+      data.rollupByOrchestrator,
+      data.orchestratorNames,
       data.taskCardUrl,
     ]
   );

package/components/SessionList/useSidebarData.ts

@@ -15,6 +15,7 @@ import { useSessionsQuery } from "@/data/sessions";
 import { useLinkedHostNames } from "@/data/hosts";
 import { useProjectsQuery } from "@/data/projects";
 import { useQueuedTasksQuery, useTasksQuery } from "@/data/tasks";
+import { rollups, type Rollup } from "@/lib/sidebar/rollup";
 import { queuedRows } from "@/lib/sidebar/queued";
 import { useSelectedWorkspace } from "@/hooks/useSelectedWorkspace";
 import { useOrchestratorsQuery } from "@/data/orchestrators";
@@ -69,7 +70,7 @@ export function useSidebarData(
   );
   const project = workspaceProjects.find((p) => p.id === ui.projectId) ?? null;
 
-  const { shelves, machines } = useMemo(() => {
+  const { all, shelves, machines } = useMemo(() => {
     const byId = new Map(projects.map((p) => [p.id, p]));
     const workspaceName = new Map(workspaces.map((w) => [w.id, w.name]));
     const taskStates: Record<string, TaskState> = {};
@@ -84,23 +85,32 @@ export function useSidebarData(
       projectName,
       query: ui.query,
     };
+    const input = {
+      ...common,
+      sessions: sessions.filter(
+        (s) =>
+          !onMachineOnly(s, linked) &&
+          inWorkspace(
+            s,
+            (id) => byId.get(id)?.workspace_id,
+            workspace?.id ?? null
+          )
+      ),
+      projectId: project?.id ?? null,
+      currentOrchestrators,
+    };
+    // The rollups count the whole list; the filter only narrows what shows.
+    const all = buildShelves(input);
     return {
-      shelves: buildShelves({
-        ...common,
-        sessions: sessions.filter(
-          (s) =>
-            !onMachineOnly(s, linked) &&
-            inWorkspace(
-              s,
-              (id) => byId.get(id)?.workspace_id,
-              workspace?.id ?? null
-            )
-        ),
-        projectId: project?.id ?? null,
-        currentOrchestrators,
-      }),
-      // Not in any project, so not under a chosen one.
-      machines: project ? [] : machineGroups({ ...common, sessions }, linked),
+      all,
+      shelves: ui.orchestratorId
+        ? buildShelves({ ...input, startedBy: ui.orchestratorId })
+        : all,
+      // Not in any project, nor started by an orchestrator.
+      machines:
+        project || ui.orchestratorId
+          ? []
+          : machineGroups({ ...common, sessions }, linked),
     };
   }, [
     linked,
@@ -113,6 +123,7 @@ export function useSidebarData(
     workspace,
     project,
     ui.query,
+    ui.orchestratorId,
   ]);
 
   // Per workspace, how many of its project sessions are working: the
@@ -150,7 +161,7 @@ export function useSidebarData(
   );
 
   // Tasks waiting to start, in their line's order.
-  const queued = useMemo(
+  const queuedAll = useMemo(
     () =>
       queuedRows({
         queue,
@@ -161,6 +172,39 @@ export function useSidebarData(
       }),
     [queue, sessions, workspace, project, ui.query]
   );
+  const queued = useMemo(
+    () =>
+      ui.orchestratorId
+        ? queuedAll.filter((r) => r.item.startedBy === ui.orchestratorId)
+        : queuedAll,
+    [queuedAll, ui.orchestratorId]
+  );
+
+  // Each orchestrator's started work, keyed by its counts like the ones
+  // above so a push that changed none of them redraws no row.
+  const rollupKey = useMemo(
+    () => JSON.stringify([...rollups(all, queuedAll)].sort()),
+    [all, queuedAll]
+  );
+  const rollupByOrchestrator = useMemo(
+    () => new Map(JSON.parse(rollupKey) as [string, Rollup][]),
+    [rollupKey]
+  );
+
+  // Orchestrator session id -> the workspace it serves, for tags and chips.
+  const orchestratorKey = JSON.stringify(
+    sessions
+      .filter((s) => s.role === "orchestrator")
+      .map((s) => [
+        s.id,
+        workspaces.find((w) => w.id === s.workspace_id)?.name ?? s.name,
+      ])
+      .sort()
+  );
+  const orchestratorNames = useMemo(
+    () => new Map(JSON.parse(orchestratorKey) as [string, string][]),
+    [orchestratorKey]
+  );
 
   const taskCardUrl = useCallback(
     (id: string) => tasks.find((t) => t.id === id)?.cardUrl,
@@ -194,6 +238,8 @@ export function useSidebarData(
     projectNames,
     runningByWorkspace,
     queuedByWorkspace,
+    rollupByOrchestrator,
+    orchestratorNames,
     workspaces,
     workspace,
     workspaceProjects,

package/data/chat/useChat.ts

@@ -19,6 +19,7 @@ import type {
   UndoPreview,
 } from "@/lib/chat/events";
 import type { SearchResult } from "@/lib/chat/find";
+import { addBody, touchBody } from "@/lib/chat/bodyCache";
 
 // The index of the item with `id`, searched from the end: what changes is
 // almost always the latest.
@@ -129,6 +130,13 @@ export function useChat(
   const [toolBodies, setToolBodies] = useState<Record<string, ToolBody | null>>(
     {}
   );
+  // Bodies open on screen, never evicted from toolBodies.
+  const visibleBodies = useRef(new Set<string>());
+  const pinToolBody = useCallback((id: string) => {
+    visibleBodies.current.add(id);
+    setToolBodies((prev) => touchBody(prev, id));
+    return () => void visibleBodies.current.delete(id);
+  }, []);
   const [state, setState] = useState<ChatState>("idle");
   const [connected, setConnected] = useState(false);
   const [commands, setCommands] = useState<ChatCommand[]>([]);
@@ -249,7 +257,9 @@ export function useChat(
           const have = new Set(prev.map((p) => p.id));
           setItems(m.items.filter((i) => !have.has(i.id)).concat(prev));
         } else if (m.type === "tool_body") {
-          setToolBodies((prev) => ({ ...prev, [m.id]: m.body }));
+          setToolBodies((prev) =>
+            addBody(prev, m.id, m.body, visibleBodies.current)
+          );
         } else if (m.type === "item") {
           withDeltas(() => {
             const routed = routeItem(
@@ -457,6 +467,7 @@ export function useChat(
     earlierTasks,
     toolBodies,
     requestToolBody,
+    pinToolBody,
     state,
     connected,
     commands,

package/data/push/topics.test.ts

@@ -2,6 +2,7 @@ import { QueryClient } from "@tanstack/react-query";
 import { describe, expect, it } from "vitest";
 import { WATCHED_TABLES } from "@/lib/db/changes";
 import { gitKeys } from "../git/keys";
+import { taskKeys } from "../tasks/keys";
 import { sessionKeys } from "../sessions/keys";
 import { ALL_TOPICS, invalidateTopics, topicKeys } from "./topics";
 
@@ -16,6 +17,14 @@ describe("pushed topics", () => {
       expect(topicKeys(topic), topic).not.toEqual([]);
   });
 
+  it("a snapshot refetches the queue and every other watched table", () => {
+    for (const table of WATCHED_TABLES) expect(ALL_TOPICS).toContain(table);
+    const client = new QueryClient();
+    client.setQueryData(taskKeys.queue(), []);
+    invalidateTopics(client, ALL_TOPICS);
+    expect(client.getQueryState(taskKeys.queue())?.isInvalidated).toBe(true);
+  });
+
   it("maps a git folder and a session's setup to their queries", () => {
     expect(topicKeys("git:~/app")).toContainEqual(gitKeys.status("~/app"));
     expect(topicKeys("git:~/app")).toContainEqual([

package/data/push/topics.ts

@@ -1,4 +1,5 @@
 import type { QueryClient, QueryKey } from "@tanstack/react-query";
+import { WATCHED_TABLES } from "@/lib/db/changes";
 import { sessionKeys } from "../sessions/keys";
 import { taskKeys } from "../tasks/keys";
 import { projectKeys } from "../projects/keys";
@@ -88,19 +89,7 @@ export function invalidateTopics(
 }
 
 // Every pushed topic but git folders: after a gap the stream can't replay.
-export const ALL_TOPICS = [
-  "sessions",
-  "projects",
-  "workspaces",
-  "hosts",
-  "discovered",
-  "stacks",
-  "bus_messages",
-  "schedules",
-  "orchestrator_asks",
-  "orchestrator_rules",
-  "away_periods",
-  "dev_servers",
-];
+// Every table the triggers watch is in it, so a new one can't be left out.
+export const ALL_TOPICS = [...new Set([...WATCHED_TABLES, "discovered"])];
 
 export { keysFor as topicKeys };

package/lib/chat/bodyCache.ts

@@ -0,0 +1,69 @@
+import type { ToolBody } from "./events";
+
+// Opened tool output kept in memory, least recently used first out.
+export const MAX_LOADED_BODIES = 40;
+export const MAX_LOADED_BODY_CHARS = 5_000_000;
+
+export type Bodies = Record<string, ToolBody | null>;
+
+export function bodySize(body: ToolBody | null): number {
+  if (!body) return 0;
+  const d = body.diff;
+  return (
+    (body.output?.length ?? 0) +
+    (d ? d.path.length + d.before.length + d.after.length : 0)
+  );
+}
+
+// Object keys keep insertion order, so the first key is the least recently
+// used. Puts `id` last, loaded or being opened again.
+export function touchBody(bodies: Bodies, id: string): Bodies {
+  if (!(id in bodies) || Object.keys(bodies).pop() === id) return bodies;
+  const { [id]: body, ...rest } = bodies;
+  return { ...rest, [id]: body };
+}
+
+// Drops the least recently used bodies until both limits hold. A body on
+// screen stays, even when that leaves the cache over a limit.
+export function capBodies(
+  bodies: Bodies,
+  visible: ReadonlySet<string>
+): Bodies {
+  const ids = Object.keys(bodies);
+  let count = ids.length;
+  let chars = ids.reduce((n, id) => n + bodySize(bodies[id]), 0);
+  if (count <= MAX_LOADED_BODIES && chars <= MAX_LOADED_BODY_CHARS)
+    return bodies;
+  const drop = new Set<string>();
+  for (const id of ids) {
+    if (count <= MAX_LOADED_BODIES && chars <= MAX_LOADED_BODY_CHARS) break;
+    if (visible.has(id)) continue;
+    drop.add(id);
+    count--;
+    chars -= bodySize(bodies[id]);
+  }
+  return Object.fromEntries(
+    ids.filter((id) => !drop.has(id)).map((id) => [id, bodies[id]])
+  );
+}
+
+// A body arriving: it is the most recently used.
+export function addBody(
+  bodies: Bodies,
+  id: string,
+  body: ToolBody | null,
+  visible: ReadonlySet<string>
+): Bodies {
+  const { [id]: _old, ...rest } = bodies;
+  return capBodies({ ...rest, [id]: body }, visible);
+}
+
+// Whether an opened tool must ask for its body: deferred, not loaded (never
+// was, or evicted), and the socket is up.
+export function needsBody(
+  deferred: boolean | undefined,
+  body: ToolBody | null | undefined,
+  connected: boolean
+): boolean {
+  return !!deferred && body === undefined && connected;
+}