@saadnvd1/agent-os 0.3.594 → 0.3.595

package/components/Providers.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect } from "react";
 import { QueryClientProvider } from "@tanstack/react-query";
 import { ThemeProvider as NextThemesProvider, useTheme } from "next-themes";
 import { TooltipProvider } from "@/components/ui/tooltip";
+import { HoverTip } from "@/components/ui/HoverTip";
 import { createQueryClient } from "@/lib/query-client";
 import { parseTheme, getAllThemes } from "@/lib/theme-config";
 
@@ -41,7 +42,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
         themes={getAllThemes()}
       >
         <ThemeClassHandler>
-          <TooltipProvider delayDuration={200}>{children}</TooltipProvider>
+          <TooltipProvider delayDuration={200}>
+            {children}
+            <HoverTip />
+          </TooltipProvider>
         </ThemeClassHandler>
       </NextThemesProvider>
     </QueryClientProvider>

package/components/SessionList/LiveLine.tsx

@@ -52,7 +52,7 @@ export function LiveLine({ compacting, prStage }: LiveInput) {
                 href={prStage.url}
                 target="_blank"
                 rel="noreferrer"
-                title={pr}
+                data-tip={pr}
                 aria-label={pr}
                 onClick={(e) => e.stopPropagation()}
                 className={cn(

package/components/SessionList/OrchestratorPinRow.tsx

@@ -16,6 +16,7 @@ import { useRowContext } from "./RowContext";
 import { SessionRowMenu } from "./SessionRowMenu";
 import { RowRename, UnreadDot } from "./RowParts";
 import { QuickChangeRow } from "./QuickChangeRow";
+import { NestRail } from "./RowParts";
 
 // A workspace's orchestrator, pinned above its sessions and titled with the
 // workspace's name: what it's doing and how many asks wait on you, on a line
@@ -54,7 +55,7 @@ export const OrchestratorPinRow = memo(function OrchestratorPinRow({
 
   const content = (
     <RowFrame
-      title={`${label}\n${summary}`}
+      data-tip={`${label}\n${summary}`}
       onActivate={() => !renaming && ctx.onSelect(session.id)}
       className={
         active
@@ -172,9 +173,13 @@ export const OrchestratorPinRow = memo(function OrchestratorPinRow({
           {menu("context")}
         </CM.ContextMenuContent>
       </CM.ContextMenu>
-      {row.quick?.map((q) => (
-        <QuickChangeRow key={q.session.id} row={q} />
-      ))}
+      {!!row.quick?.length && (
+        <NestRail>
+          {row.quick.map((q) => (
+            <QuickChangeRow key={q.session.id} row={q} />
+          ))}
+        </NestRail>
+      )}
     </>
   );
 }, sameProps);
@@ -190,7 +195,7 @@ export function OrchestratorStartRow({
 }) {
   return (
     <RowFrame
-      title={`${name}\nStart orchestrator`}
+      data-tip={`${name}\nStart orchestrator`}
       onActivate={() => orchestratorOpenActions.request(workspaceId)}
       className="hover:bg-muted/50 border-dashed"
     >

package/components/SessionList/QuickChangeRow.tsx

@@ -42,7 +42,7 @@ export function QuickChangeRow({ row }: { row: SidebarRow }) {
   );
   const openPr = pr ? () => window.open(pr, "_blank") : undefined;
   return (
-    <div className="ml-5">
+    <div>
       <RowShell
         title={`Quick change: ${session.name}\n${label}`}
         onActivate={openPr}

package/components/SessionList/RowParts.tsx

@@ -1,7 +1,9 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { ClipboardList, Pencil } from "lucide-react";
 import { NEED_LABEL, type SidebarRow } from "@/lib/sidebar/shelves";
+import { rowKindBadge, type RowKindBadge } from "@/lib/sidebar/row-badge";
 import { cn } from "@/lib/utils";
 
 // Amber when it needs you, red when it failed, green while it works, and a
@@ -26,7 +28,8 @@ export function RowDot({ row }: { row: SidebarRow }) {
   );
 }
 
-// What it needs from you, stalled, or a purple dot when it changed since you looked.
+// What it needs from you, stalled, its plan step, or a purple dot when it
+// changed since you looked.
 export function RowBadge({ row }: { row: SidebarRow }) {
   if (row.need) {
     const asks = row.status?.asks ?? 0;
@@ -50,10 +53,42 @@ export function RowBadge({ row }: { row: SidebarRow }) {
         Stalled
       </span>
     );
+  const kind = rowKindBadge(row);
+  if (kind) return <KindBadge badge={kind} />;
   if (row.unread) return <UnreadDot />;
   return null;
 }
 
+// Planning in blue, a plan waiting for approval in the primary colour:
+// an icon and a word, never colour alone.
+function KindBadge({ badge }: { badge: RowKindBadge }) {
+  const Icon = badge.kind === "planning" ? Pencil : ClipboardList;
+  return (
+    <span
+      data-tip={badge.tip}
+      className={cn(
+        "flex shrink-0 items-center gap-1 rounded-md px-1.5 py-0.5 text-[11px] font-semibold whitespace-nowrap",
+        badge.kind === "planning"
+          ? "bg-blue-500/15 text-blue-700 dark:text-blue-400"
+          : "bg-primary/15 text-primary"
+      )}
+    >
+      <Icon aria-hidden className="h-3 w-3" />
+      {badge.label}
+    </span>
+  );
+}
+
+// What belongs to the row above it (a conductor's workers, an
+// orchestrator's quick changes), behind a thin rule.
+export function NestRail({ children }: { children: ReactNode }) {
+  return (
+    <div className="border-foreground/10 ml-3.5 border-l pl-1.5">
+      {children}
+    </div>
+  );
+}
+
 export function UnreadDot() {
   return (
     <span

package/components/SessionList/RowShell.tsx

@@ -11,9 +11,11 @@ export type RowMenuKind = "dropdown" | "context";
 
 // Every sidebar row's frame: a leading mark, title over subtitle, what's on
 // the right (hidden under the ⋯ on hover), and the same menu on ⋯ and on
-// right-click. Session rows and queued tasks both draw through it.
+// right-click. Session rows and queued tasks both draw through it. The
+// title is its hover tip (lib/hover-tip), or tipKey's when one resolves.
 export function RowShell({
   title,
+  tipKey,
   highlight,
   onClick,
   onActivate,
@@ -26,6 +28,7 @@ export function RowShell({
   menuButton = true,
 }: {
   title: string;
+  tipKey?: string;
   highlight?: "selected" | "active" | null;
   onClick?: (e: React.MouseEvent) => void;
   // Enter or Space on the row; without it the row isn't a button.
@@ -45,7 +48,8 @@ export function RowShell({
     <div
       role={onActivate ? "button" : undefined}
       tabIndex={onActivate ? 0 : undefined}
-      title={title}
+      data-tip={title}
+      data-tip-key={tipKey}
       onClick={onClick}
       onKeyDown={(e) => {
         if (!onActivate || e.target !== e.currentTarget) return;

package/components/SessionList/RowSubtitle.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Repeat, Layers } from "lucide-react";
+import { Repeat, Layers, Pause } from "lucide-react";
 import { HostBadge } from "@/components/Hosts";
 import { rowGroup } from "@/lib/recipes/chip";
 import type { Session } from "@/lib/db";
@@ -21,10 +21,12 @@ export function RowSubtitle({
   session,
   detail,
   live,
+  hideHost = false,
 }: {
   session: Session;
   detail?: string | null;
   live?: LiveInput;
+  hideHost?: boolean;
 }) {
   const ctx = useRowContext();
   // What its processes use, on a busy session: "3.1 cores · 4.2 GB".
@@ -61,29 +63,34 @@ export function RowSubtitle({
   return (
     <span className="flex min-w-0 items-center gap-1.5">
       {pause ? (
-        <span className="min-w-0 truncate text-xs text-amber-600 dark:text-amber-400">
-          {pauseSubtitle({
-            state: pause,
-            until: session.paused_until
-              ? Date.parse(`${session.paused_until.replace(" ", "T")}Z`)
-              : null,
-            note: session.pause_note,
-          })}
+        <span className="flex min-w-0 items-center gap-1 text-xs text-amber-600 dark:text-amber-400">
+          <Pause aria-hidden className="h-3 w-3 shrink-0" />
+          <span className="truncate">
+            {pauseSubtitle({
+              state: pause,
+              until: session.paused_until
+                ? Date.parse(`${session.paused_until.replace(" ", "T")}Z`)
+                : null,
+              note: session.pause_note,
+            })}
+          </span>
         </span>
       ) : (
         <LiveLine {...live} />
       )}
       {group && (
         <span
-          className="text-muted-foreground/70 hidden min-w-0 shrink items-center gap-1 truncate text-xs @[14rem]:flex"
-          title={group.kind === "recipe" ? "A recipe run" : "A piece of a plan"}
+          className="text-muted-foreground/70 flex min-w-0 shrink-0 items-center gap-1 truncate text-xs @[14rem]:shrink"
+          data-tip={`${group.kind === "recipe" ? "Recipe run" : "Plan piece"}: ${group.text}`}
         >
           {group.kind === "recipe" ? (
             <Repeat aria-hidden className="h-3 w-3 shrink-0" />
           ) : (
             <Layers aria-hidden className="h-3 w-3 shrink-0" />
           )}
-          <span className="truncate">{group.text}</span>
+          <span className="sr-only truncate @[14rem]:not-sr-only">
+            {group.text}
+          </span>
         </span>
       )}
       {(project || detail || usage || session.placed_note) && (
@@ -98,7 +105,7 @@ export function RowSubtitle({
             .join(" · ")}
         </span>
       )}
-      <HostBadge hostId={session.host_id} />
+      {!hideHost && <HostBadge hostId={session.host_id} />}
     </span>
   );
 }

package/components/SessionList/SessionRow.tsx

@@ -12,6 +12,7 @@ import {
 import { compactTimeAgo } from "@/lib/session-meta";
 import { wakeLabel } from "@/lib/sidebar/snooze";
 import { sameRow, type SidebarRow } from "@/lib/sidebar/shelves";
+import { rowKindBadge } from "@/lib/sidebar/row-badge";
 import { useMinuteTick } from "@/hooks/useMinuteTick";
 import { selectionStore, selectionActions } from "@/stores/sessionSelection";
 import { cn } from "@/lib/utils";
@@ -19,7 +20,7 @@ import { QuickChangeRow } from "./QuickChangeRow";
 import { useRowContext } from "./RowContext";
 import { SessionRowMenu } from "./SessionRowMenu";
 import { RowShell, type RowMenuKind } from "./RowShell";
-import { RowBadge, RowDot, RowRename } from "./RowParts";
+import { NestRail, RowBadge, RowDot, RowRename } from "./RowParts";
 import { RowSubtitle } from "./RowSubtitle";
 import { OrchestratorAsks } from "./OrchestratorAsks";
 
@@ -29,11 +30,12 @@ import { OrchestratorAsks } from "./OrchestratorAsks";
 export const SessionRow = memo(function SessionRow({
   row,
   muted = false,
-  nested = false,
+  inMachineShelf = false,
 }: {
   row: SidebarRow;
   muted?: boolean;
-  nested?: boolean;
+  // Under its machine's own shelf, which already names the machine.
+  inMachineShelf?: boolean;
 }) {
   const ctx = useRowContext();
   const { selectedIds } = useSnapshot(selectionStore);
@@ -69,9 +71,10 @@ export const SessionRow = memo(function SessionRow({
   );
 
   return (
-    <div className={cn(nested && "pl-5")}>
+    <div>
       <RowShell
         title={session.name}
+        tipKey={`session:${session.id}`}
         highlight={selected ? "selected" : active ? "active" : null}
         onClick={onClick}
         onActivate={() => ctx.onSelect(session.id)}
@@ -89,7 +92,7 @@ export const SessionRow = memo(function SessionRow({
         aside={
           <>
             {viaName && (
-              <span title={`Started by ${viaName}`} className="shrink-0">
+              <span data-tip={`Started by ${viaName}`} className="shrink-0">
                 <Workflow
                   aria-label={`Via orchestrator: ${viaName}`}
                   className="text-muted-foreground/60 h-3 w-3"
@@ -104,7 +107,7 @@ export const SessionRow = memo(function SessionRow({
         trailing={
           <>
             <RowBadge row={row} />
-            {!row.need && <RowTime row={row} />}
+            {!row.need && !rowKindBadge(row) && <RowTime row={row} />}
           </>
         }
         menu={menu}
@@ -132,6 +135,7 @@ export const SessionRow = memo(function SessionRow({
         )}
         <RowSubtitle
           session={session}
+          hideHost={inMachineShelf}
           detail={row.status?.detail}
           live={
             row.need
@@ -143,21 +147,28 @@ export const SessionRow = memo(function SessionRow({
       {session.role === "orchestrator" && row.need && (
         <OrchestratorAsks workspaceId={session.workspace_id} />
       )}
-      {row.workers.map((worker) => (
-        <SessionRow key={worker.session.id} row={worker} muted={muted} nested />
-      ))}
-      {row.quick?.map((q) => (
-        <QuickChangeRow key={q.session.id} row={q} />
-      ))}
+      {(row.workers.length > 0 || !!row.quick?.length) && (
+        <NestRail>
+          {row.workers.map((worker) => (
+            <SessionRow key={worker.session.id} row={worker} muted={muted} />
+          ))}
+          {row.quick?.map((q) => (
+            <QuickChangeRow key={q.session.id} row={q} />
+          ))}
+        </NestRail>
+      )}
     </div>
   );
 }, sameRowProps);
 
-function sameRowProps(
-  a: { row: SidebarRow; muted?: boolean; nested?: boolean },
-  b: { row: SidebarRow; muted?: boolean; nested?: boolean }
-) {
-  return a.muted === b.muted && a.nested === b.nested && sameRow(a.row, b.row);
+type RowProps = { row: SidebarRow; muted?: boolean; inMachineShelf?: boolean };
+
+function sameRowProps(a: RowProps, b: RowProps) {
+  return (
+    a.muted === b.muted &&
+    a.inMachineShelf === b.inMachineShelf &&
+    sameRow(a.row, b.row)
+  );
 }
 
 // Snoozed: when it wakes. Otherwise when it last did something.

package/components/SessionList/SessionShelves.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import type { ReactNode } from "react";
-import { ChevronDown } from "lucide-react";
+import { ChevronDown, ListTodo, Server, type LucideIcon } from "lucide-react";
 import {
   DONE_PAGE,
   doneLimit,
@@ -16,21 +16,35 @@ import { OrchestratorPinRow, OrchestratorStartRow } from "./OrchestratorPinRow";
 import { QueuedRow } from "./QueuedRow";
 import type { QueuedRow as QueuedRowData } from "@/lib/sidebar/queued";
 
-function ShelfLabel({
+// A shelf's header. Only groups that aren't a state (a machine, the line,
+// terminals) carry an icon; a shelf that asks for you counts in amber.
+export function ShelfLabel({
   label,
   count,
+  icon: Icon,
+  accent = false,
   collapsed,
   onToggle,
 }: {
   label: string;
   count?: number;
+  icon?: LucideIcon;
+  accent?: boolean;
   collapsed?: boolean;
   onToggle?: () => void;
 }) {
   const text = (
     <>
+      {Icon && <Icon aria-hidden className="h-3 w-3 shrink-0" />}
       {label}
-      {count !== undefined && ` · ${count}`}
+      {count !== undefined && (
+        <>
+          {" · "}
+          <span className={cn(accent && "text-amber-600 dark:text-amber-400")}>
+            {count}
+          </span>
+        </>
+      )}
       {onToggle && (
         <ChevronDown
           className={cn(
@@ -63,15 +77,19 @@ function ShelfLabel({
 function Shelf({
   label,
   count,
+  icon,
+  accent,
   children,
 }: {
   label: string;
   count?: number;
+  icon?: LucideIcon;
+  accent?: boolean;
   children: ReactNode;
 }) {
   return (
     <section aria-label={label}>
-      <ShelfLabel label={label} count={count} />
+      <ShelfLabel label={label} count={count} icon={icon} accent={accent} />
       {children}
     </section>
   );
@@ -80,9 +98,9 @@ function Shelf({
 // A linked machine's sessions no project here holds, under its name.
 export function MachineShelves({ groups }: { groups: MachineGroup[] }) {
   return groups.map((g) => (
-    <Shelf key={g.hostId} label={g.name} count={g.rows.length}>
+    <Shelf key={g.hostId} label={g.name} count={g.rows.length} icon={Server}>
       {g.rows.map((r) => (
-        <SessionRow key={r.session.id} row={r} />
+        <SessionRow key={r.session.id} row={r} inMachineShelf />
       ))}
     </Shelf>
   ));
@@ -108,6 +126,17 @@ export function SessionShelves({
   const shown = shelves.done.slice(0, doneLimit(donePages));
   const hidden = shelves.done.length - shown.length;
   const summary = doneSummary(shelves.done).text;
+  // Live work above, what's resting below a hairline.
+  const live =
+    shelves.orchestrators.length +
+      toStart.length +
+      shelves.pinned.length +
+      shelves.needsYou.length +
+      shelves.working.length +
+      shelves.inReview.length +
+      queued.length +
+      shelves.ongoing.length >
+    0;
   return (
     <>
       {shelves.orchestrators.length + toStart.length > 0 && (
@@ -128,7 +157,7 @@ export function SessionShelves({
         </Shelf>
       )}
       {shelves.needsYou.length > 0 && (
-        <Shelf label="Needs you" count={shelves.needsYou.length}>
+        <Shelf label="Needs you" count={shelves.needsYou.length} accent>
           {shelves.needsYou.map((r) => (
             <SessionRow key={r.session.id} row={r} />
           ))}
@@ -149,7 +178,7 @@ export function SessionShelves({
         </Shelf>
       )}
       {queued.length > 0 && (
-        <Shelf label="Queued" count={queued.length}>
+        <Shelf label="Queued" count={queued.length} icon={ListTodo}>
           {queued.map((r) => (
             <QueuedRow key={r.item.id} row={r} />
           ))}
@@ -162,6 +191,9 @@ export function SessionShelves({
           ))}
         </Shelf>
       )}
+      {live && shelves.snoozed.length + shelves.done.length > 0 && (
+        <div aria-hidden className="border-border mx-2.5 mt-2.5 border-t" />
+      )}
       {shelves.snoozed.length > 0 && (
         <section aria-label="Snoozed">
           <ShelfLabel

package/components/SessionList/SidebarExtras.tsx

@@ -4,7 +4,9 @@ import { DevServerCard } from "@/components/DevServers/DevServerCard";
 import { ElsewhereTmuxList, TmuxSessionRow } from "@/components/Hosts";
 import { useDevServersQuery } from "@/data/dev-servers";
 import { useDiscoveredTmuxQuery } from "@/data/hosts";
+import { SquareTerminal } from "lucide-react";
 import type { ProjectWithRepositories } from "@/lib/projects";
+import { ShelfLabel } from "./SessionShelves";
 
 interface DevServerHandlers {
   onStop: (id: string) => Promise<void>;
@@ -58,7 +60,11 @@ export function SidebarExtras({
       )}
       {tmux.length > 0 && (
         <section aria-label="Terminals">
-          <div className={label}>Terminals · {tmux.length}</div>
+          <ShelfLabel
+            label="Terminals"
+            count={tmux.length}
+            icon={SquareTerminal}
+          />
           {tmux.map((t) => (
             <TmuxSessionRow key={`${t.hostId}:${t.name}`} session={t} />
           ))}

package/components/SessionList/index.tsx

@@ -12,6 +12,7 @@ import type { OrchestratorOverview } from "@/lib/orchestrator/overview";
 import { useSessionListMutations } from "./hooks/useSessionListMutations";
 import { useBulkDelete } from "./hooks/useBulkDelete";
 import { useSidebarData } from "./useSidebarData";
+import { useSessionTips } from "./useSessionTips";
 import { RowProvider, type RowContextValue } from "./RowContext";
 import { SidebarHeader } from "./SidebarHeader";
 import { useAddProject } from "@/components/Projects/AddProject/useAddProject";
@@ -43,6 +44,7 @@ export function SessionList({
   pinControls,
 }: SessionListProps) {
   const data = useSidebarData(sessionStatuses);
+  useSessionTips(data);
   const { shelves, ui, project } = data;
   const mutations = useSessionListMutations({ onSelectSession: onSelect });
   const bulkDelete = useBulkDelete();

package/components/SessionList/useSessionTips.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useEffect, useLayoutEffect, useRef } from "react";
+import { useHostNames } from "@/data/hosts";
+import type { SidebarRow } from "@/lib/sidebar/shelves";
+import type { SidebarData } from "./useSidebarData";
+
+function find(rows: readonly SidebarRow[], id: string): SidebarRow | null {
+  for (const row of rows) {
+    if (row.session.id === id) return row;
+    const nested = find(row.workers, id) ?? find(row.quick ?? [], id);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// A session row's hover tip, built from the latest list only when it
+// opens: nothing runs per row, and registering never re-renders.
+export function useSessionTips(data: SidebarData) {
+  const hostNames = useHostNames();
+  const latest = useRef({ data, hostNames });
+  useLayoutEffect(() => {
+    latest.current = { data, hostNames };
+  });
+  // Loaded after the page, like the tip itself: no first-load cost.
+  useEffect(() => {
+    let off: (() => void) | undefined;
+    let gone = false;
+    Promise.all([
+      import("@/lib/hover-tip"),
+      import("@/lib/sidebar/row-details"),
+    ]).then(([{ registerTip }, { rowDetails }]) => {
+      if (gone) return;
+      off = registerTip("session", (id) => {
+        const { data, hostNames } = latest.current;
+        const row = find(
+          [
+            ...Object.values(data.shelves).flat(),
+            ...data.machines.flatMap((g) => g.rows),
+          ],
+          id
+        );
+        if (!row) return null;
+        const s = row.session;
+        return rowDetails(row, {
+          project: data.projectNames.get(s.project_id ?? ""),
+          startedBy: s.started_by
+            ? data.orchestratorNames.get(s.started_by)
+            : undefined,
+          host:
+            s.host_id && s.host_id !== "local"
+              ? hostNames[s.host_id] || "remote"
+              : undefined,
+        });
+      });
+    });
+    return () => {
+      gone = true;
+      off?.();
+    };
+  }, []);
+}

package/components/ui/HoverTip.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { useEffect } from "react";
+
+// Mounted once: the app's single hover tooltip (lib/hover-tip.ts), loaded
+// after the page so it costs the first load nothing.
+export function HoverTip() {
+  useEffect(() => {
+    let off: (() => void) | undefined;
+    let gone = false;
+    import("@/lib/hover-tip").then(({ installHoverTip }) => {
+      if (!gone) off = installHoverTip();
+    });
+    return () => {
+      gone = true;
+      off?.();
+    };
+  }, []);
+  return null;
+}

package/data/presence/index.ts

@@ -1,7 +1,3 @@
-import {
-  startAuthentication,
-  startRegistration,
-} from "@simplewebauthn/browser";
 import type {
   AuthenticationResponseJSON,
   PublicKeyCredentialCreationOptionsJSON,
@@ -30,12 +26,20 @@ export const passkeysHere = () =>
 export const NO_PASSKEYS_HERE =
   "Approving this needs a passkey, and passkeys need https or localhost: approve it on the machine running AgentOS, or over Connect.";
 
+// The passkey library loads only when a passkey is used, fetched alongside
+// the server's options so the prompt waits on nothing extra.
+const webauthn = () => import("@simplewebauthn/browser");
+
 // Adds a passkey on this browser: free for the very first one, otherwise
 // with a code from a device that has one.
 export async function registerPasskey(enrollCode?: string): Promise<void> {
-  const { options } = await post<{
-    options: PublicKeyCredentialCreationOptionsJSON;
-  }>("/api/presence/register/options", { enrollCode });
+  const [{ startRegistration }, { options }] = await Promise.all([
+    webauthn(),
+    post<{ options: PublicKeyCredentialCreationOptionsJSON }>(
+      "/api/presence/register/options",
+      { enrollCode }
+    ),
+  ]);
   const response = await startRegistration({ optionsJSON: options });
   await post("/api/presence/register/verify", { response, enrollCode });
 }
@@ -55,6 +59,8 @@ export async function provePresence(req: {
     needsPasskey?: boolean;
     canBootstrap?: boolean;
   };
+  const lib = webauthn();
+  lib.catch(() => {}); // awaited below; an early throw mustn't leave it unhandled
   let answer = await post<Answer>("/api/presence/options", req);
   if (answer.needsPasskey) {
     if (!answer.canBootstrap)
@@ -65,5 +71,6 @@ export async function provePresence(req: {
     answer = await post<Answer>("/api/presence/options", req);
   }
   if (!answer.options) throw new Error("No passkey for this host");
+  const { startAuthentication } = await lib;
   return startAuthentication({ optionsJSON: answer.options });
 }

package/lib/hover-tip.ts

@@ -0,0 +1,161 @@
+// One hover tooltip for the whole app. An element opts in with data-tip
+// (plain text) or data-tip-key ("session:<id>", resolved when it opens by
+// whoever registered that prefix). Rows carry an attribute and nothing
+// else: one element and a few passive document listeners do the rest, and
+// a touch screen attaches none. It opens after resting on something, and
+// once one is open the next opens at once, so a list can be scanned.
+
+export interface TipContent {
+  title: string;
+  lines: [label: string, value: string][];
+}
+export type TipValue = string | TipContent | null | undefined;
+
+export const OPEN_DELAY_MS = 600;
+export const WARM_MS = 400;
+const SELECTOR = "[data-tip],[data-tip-key]";
+const TIP_ID = "hover-tip";
+
+const resolvers = new Map<string, (id: string) => TipValue>();
+
+export function registerTip(
+  prefix: string,
+  resolve: (id: string) => TipValue
+): () => void {
+  resolvers.set(prefix, resolve);
+  return () => {
+    if (resolvers.get(prefix) === resolve) resolvers.delete(prefix);
+  };
+}
+
+export function resolveTip(el: Element): TipValue {
+  const key = el.getAttribute("data-tip-key");
+  if (key) {
+    const at = key.indexOf(":");
+    const value = resolvers.get(key.slice(0, at))?.(key.slice(at + 1));
+    if (value) return value;
+  }
+  return el.getAttribute("data-tip");
+}
+
+// Text only: names are user text and never parsed as HTML.
+function fill(el: HTMLElement, value: string | TipContent) {
+  if (typeof value === "string") {
+    el.textContent = value;
+    return;
+  }
+  const doc = el.ownerDocument;
+  const title = doc.createElement("div");
+  title.className = "font-medium";
+  title.textContent = value.title;
+  const rows = value.lines.map(([label, text]) => {
+    const line = doc.createElement("div");
+    const k = doc.createElement("span");
+    k.className = "text-muted-foreground";
+    k.textContent = `${label} `;
+    line.append(k, text);
+    return line;
+  });
+  el.replaceChildren(title, ...rows);
+}
+
+// Beside the target (a sidebar row's tip opens over the page, not the
+// list), flipped or dropped below when there's no room. One measure.
+function place(el: HTMLElement, target: Element, win: Window) {
+  const r = target.getBoundingClientRect();
+  const w = el.offsetWidth;
+  const h = el.offsetHeight;
+  const gap = 8;
+  let x = r.right + gap;
+  let y = r.top;
+  if (x + w > win.innerWidth - gap) x = r.left - w - gap;
+  if (x < gap) {
+    x = Math.min(Math.max(gap, r.left), win.innerWidth - w - gap);
+    y = r.bottom + gap;
+  }
+  y = Math.max(gap, Math.min(y, win.innerHeight - h - gap));
+  el.style.transform = `translate(${Math.round(x)}px, ${Math.round(y)}px)`;
+}
+
+// Works across documents (tests, frames), unlike instanceof Element.
+const isElement = (node: EventTarget | null): node is Element =>
+  !!node && typeof (node as Element).closest === "function";
+
+export function installHoverTip(win: Window = window): () => void {
+  if (!win.matchMedia?.("(hover: hover) and (pointer: fine)").matches)
+    return () => {};
+  const doc = win.document;
+  const el = doc.createElement("div");
+  el.id = TIP_ID;
+  el.setAttribute("role", "tooltip");
+  el.className =
+    "popover-surface text-popover-foreground pointer-events-none fixed top-0 left-0 z-[60] max-w-72 rounded-lg px-2.5 py-1.5 text-xs leading-relaxed whitespace-pre-line";
+  el.hidden = true;
+  doc.body.append(el);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending: Element | null = null;
+  let shown: Element | null = null;
+  let warmUntil = 0;
+
+  const hide = () => {
+    clearTimeout(timer);
+    timer = undefined;
+    pending = null;
+    if (shown) {
+      shown.removeAttribute("aria-describedby");
+      warmUntil = Date.now() + WARM_MS;
+      shown = null;
+    }
+    el.hidden = true;
+  };
+  const show = (target: Element) => {
+    timer = undefined;
+    if (!target.isConnected) return;
+    const value = resolveTip(target);
+    if (!value) return;
+    fill(el, value);
+    el.hidden = false;
+    place(el, target, win);
+    target.setAttribute("aria-describedby", TIP_ID);
+    shown = target;
+  };
+  const arm = (target: Element | null) => {
+    if (target && (target === pending || target === shown)) return;
+    hide();
+    if (!target) return;
+    pending = target;
+    if (Date.now() < warmUntil) show(target);
+    else timer = setTimeout(() => show(target), OPEN_DELAY_MS);
+  };
+  const tipOf = (node: EventTarget | null) =>
+    isElement(node) ? node.closest(SELECTOR) : null;
+
+  const onOver = (e: Event) => arm(tipOf(e.target));
+  const onOut = (e: Event) => {
+    if (!(e as PointerEvent).relatedTarget) hide();
+  };
+  const onFocusIn = (e: Event) => {
+    const t = e.target;
+    if (isElement(t) && t.matches(SELECTOR) && t.matches(":focus-visible"))
+      arm(t);
+  };
+  const passive = { passive: true } as const;
+  const listeners: [string, (e: Event) => void, AddEventListenerOptions][] = [
+    ["pointerover", onOver, passive],
+    ["pointerout", onOut, passive],
+    ["pointerdown", hide, passive],
+    ["keydown", hide, passive],
+    ["focusin", onFocusIn, passive],
+    ["focusout", hide, passive],
+    ["scroll", hide, { passive: true, capture: true }],
+  ];
+  for (const [type, fn, opts] of listeners)
+    doc.addEventListener(type, fn, opts);
+  return () => {
+    hide();
+    for (const [type, fn, opts] of listeners)
+      doc.removeEventListener(type, fn, opts);
+    el.remove();
+  };
+}

package/lib/sidebar/row-badge.ts

@@ -0,0 +1,40 @@
+// The plan badge a row shows on its right: writing its plan, or a plan
+// waiting for approval. A need or a stall says more and wins; finished,
+// snoozed and quick-change rows show none. Client-safe.
+import type { SidebarRow } from "./shelves";
+
+export type RowKindBadge = {
+  kind: "planning" | "plan-ready";
+  label: string;
+  // What it means and what to do: the badge's hover text.
+  tip: string;
+};
+
+export function rowKindBadge(
+  row: Pick<SidebarRow, "need" | "task" | "settled" | "wakesAt"> & {
+    session: SidebarRow["session"];
+    status?: SidebarRow["status"];
+  }
+): RowKindBadge | null {
+  const s = row.session;
+  if (row.need || row.status?.stalled) return null;
+  if (row.settled || row.wakesAt || s.quick_of || s.role) return null;
+  if (s.task_status && s.task_status !== "running") return null;
+  if (row.task === "plan-ready" || s.plan_phase === "awaiting")
+    return {
+      kind: "plan-ready",
+      label: "Plan ready",
+      tip: "Plan ready: waiting for your approval. Open it to read the plan.",
+    };
+  if (s.plan_phase === "planning" || (!s.plan_phase && !!Number(s.chat_plan)))
+    return {
+      kind: "planning",
+      label: "Planning",
+      tip: s.plan_only
+        ? "Planning: plan only, it stops at the plan for your approval."
+        : s.plan_phase
+          ? "Planning: writing its plan, then it implements."
+          : "Plan mode: it plans and changes nothing yet.",
+    };
+  return null;
+}

package/lib/sidebar/row-details.ts

@@ -0,0 +1,53 @@
+// What a session row's hover tip says: its full name, then what the row
+// abbreviates. Built when the tip opens, never on render. Client-safe.
+import type { TipContent } from "@/lib/hover-tip";
+import { rowGroup } from "@/lib/recipes/chip";
+import { compactTimeAgo } from "@/lib/session-meta";
+import { prStageText } from "@/lib/tasks/pr-stage";
+import { NEED_LABEL, type SidebarRow } from "./shelves";
+import { pauseSubtitle } from "./paused";
+import { rowKindBadge } from "./row-badge";
+
+export function rowState(row: SidebarRow, now: number): string {
+  if (row.need) return `Needs you: ${NEED_LABEL[row.need]}`;
+  if (row.status?.stalled) return "Stalled";
+  const badge = rowKindBadge(row);
+  if (badge?.kind === "plan-ready") return "Plan ready, waiting for approval";
+  if (badge?.kind === "planning")
+    return row.session.plan_only ? "Planning (plan only)" : "Planning";
+  if (row.paused) return pauseSubtitle(row.paused, now);
+  if (row.compacting) return "Compacting its context";
+  const pr = row.status?.prStage;
+  if (pr) return prStageText(pr);
+  if (row.working) return "Working";
+  if (row.wakesAt) return "Snoozed";
+  return row.settled ? "Done" : "Idle";
+}
+
+export function rowDetails(
+  row: SidebarRow,
+  names: {
+    project?: string;
+    startedBy?: string;
+    host?: string;
+  },
+  now: number = Date.now()
+): TipContent {
+  const s = row.session;
+  const lines: TipContent["lines"] = [["State", rowState(row, now)]];
+  if (names.project) lines.push(["Project", names.project]);
+  const group = rowGroup(s);
+  if (group)
+    lines.push([group.kind === "recipe" ? "Recipe" : "Plan", group.text]);
+  if (s.pr_number) lines.push(["PR", `#${s.pr_number}`]);
+  if (names.host) lines.push(["Machine", names.host]);
+  if (names.startedBy) lines.push(["Started by", names.startedBy]);
+  if (row.activeAt) {
+    const ago = compactTimeAgo(new Date(row.activeAt), new Date(now));
+    lines.push([
+      "Last active",
+      ago === "now" ? "just now" : /^\d+[mhd]$/.test(ago) ? `${ago} ago` : ago,
+    ]);
+  }
+  return { title: s.name, lines };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.594",
+  "version": "0.3.595",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"