docs(maestro): describe the dormant card, pane and ordering

docs/SIDEBAR.md: the dormant card's muted rendering, its resume
action, and its lowest-precedence ordering.
docs/PREVIEW.md: a session that isn't Running never gets a live
attach through the preview path either — its pane reads the same as
its card.

docs/PREVIEW.md

@@ -28,6 +28,12 @@ A preview is a view, not a state. Nothing about it is durable:
 | Already in a pane, in another tab | That tab is brought forward. The active tab is restored when the preview ends. |
 | Not in any pane | A throwaway tab carries it. It is removed when the preview ends. |
 
+A session that is not `Running` — a dormant one, most often — never gets a
+live attach here or anywhere else a pane is filled: the daemon has nothing to
+answer a `409 not_attachable` and the socket would just die (WS close 1006).
+Its pane shows the same metadata-and-resume view `docs/SIDEBAR.md` describes
+for its card, honest about the fact that there is nothing to preview yet.
+
 The throwaway tab never counts as an open session: the tab bar does not appear
 because of it, the mobile shell does not switch away from the session list for
 it, and the sidebar does not mark the session as open.

docs/SIDEBAR.md

@@ -113,6 +113,33 @@ pane, no scrollback, and nothing to attach to. It is not an exit — nothing was
 observed ending — so the two fragments never both show. The TUI marks the same
 state on line 1 with `◌`, next to `✗` for exited and `●`/`○` for running.
 
+### Dormant cards (#168)
+
+A dormant card is a muted variant of the normal card (the web client's
+`is-dormant` class, the same muted foreground `exited` already uses): name,
+cwd and last-known age render as usual, but the activity rail carries no
+colour, since recovery resets a dormant session's activity to `Idle` and
+there is nothing running to report otherwise.
+
+The row's right-hand actions swap **spawn similar** for **resume** (↻) — there
+is no live state to clone from — and call `POST /api/sessions/:id/resume`
+(#166). **Kill** stays: it is how a dormant session is dismissed, since the
+daemon already treats a kill of a dormant session as removing its sidecar
+rather than anything it needs to be running to do.
+
+A dormant session takes the **lowest precedence in the ordering**: within a
+folder, every live (`Running` or `Dead`) session sorts before every dormant
+one, name notwithstanding, and dormant sessions sort among themselves by name.
+So a reboot that leaves a whole tree dormant never buries the live work a
+session spawns into it.
+
+Selecting a dormant session — by click, by keyboard, or by preview
+(`docs/PREVIEW.md`) — never opens a live attach: the content pane shows the
+same metadata and resume affordance the card does, rather than a terminal
+that would die on the daemon's `409 not_attachable` (WS close 1006). Resuming
+turns the session `Running`; the pane and the card pick that up on their own
+next update, no navigation required.
+
 `<diff stat>` is the blocked-work breakdown (#83) in diff notation, replacing
 the spelled-out `⚠ 3 uncommitted files, 2 unpushed commits`. It renders only
 while something would block an unforced kill, and reads:

web/src/api.ts

@@ -91,6 +91,18 @@ export async function killSession(id: Uuid, force = false): Promise<void> {
   );
 }
 
+/** Respawn a dormant session under its own uuid and sidecar (#166/#168).
+ * Refused with `409` (`already_running` / `cwd_missing`) when there is
+ * nothing a respawn could fix. */
+export async function resumeSession(id: Uuid): Promise<Session> {
+  return jsonOrError(
+    await fetch(routes.sessionResume(id), {
+      method: "POST",
+      credentials: "same-origin",
+    }),
+  );
+}
+
 /** Report whether this client's pane is the one currently showing `id` — not
  * merely highlighted in a sidebar. The daemon uses this to clear an
  * `AwaitingInput` glow once the pane has been looked at long enough

web/src/attach.ts

@@ -65,9 +65,17 @@ export interface AttachOptions {
    *  dropped — but NOT on an intentional `dispose()` (eviction / user close). The
    *  shell uses this to auto-close the pane rather than leave a dead one. */
   onClosed?: (sessionId: Uuid) => void;
+  /** Invoked when the handshake itself never completed — no retry was
+   *  attempted (see `shouldReconnect`'s `everOpened`). Unlike `onClosed`, this
+   *  is not "the session is gone": it is at least as likely a dormant
+   *  session's `409 not_attachable` caught mid-status-update (#168 review).
+   *  The shell re-renders rather than tearing the pane's leaf out, so a
+   *  dormant session's resume affordance can take over in place. */
+  onNeverAttached?: (sessionId: Uuid) => void;
   /** Asked on every close: should the socket be retried? The shell answers
-   *  from the catalog — see `shouldRetryClose`. */
-  shouldReconnect?: (sessionId: Uuid, code: number) => boolean;
+   *  from the catalog — see `shouldRetryClose`. `everOpened` is false when
+   *  this attempt never reached `open`. */
+  shouldReconnect?: (sessionId: Uuid, code: number, everOpened: boolean) => boolean;
 }
 
 /** What the header shows about the session (name / command). Optional — falls
@@ -379,6 +387,10 @@ export function createAttachConnection(
   let ws: WebSocket;
   let reconnectMs = INITIAL_RECONNECT_MS;
   let reconnectTimer: number | null = null;
+  // #168 review: a fresh attempt that never reaches `open` is a rejected
+  // handshake (dormant/unknown session), not a dropped stream — see
+  // `shouldRetryClose`'s `everOpened` param.
+  let everOpened = false;
 
   const sendControl = (msg: ClientControl) => {
     if (ws.readyState !== WebSocket.OPEN) return;
@@ -402,6 +414,7 @@ export function createAttachConnection(
     ws.binaryType = "arraybuffer";
 
     ws.onopen = () => {
+      everOpened = true;
       reconnectMs = INITIAL_RECONNECT_MS;
       setState("connected", "open");
       sendControl({ type: "Resize", cols: term.cols, rows: term.rows });
@@ -444,7 +457,7 @@ export function createAttachConnection(
       // close handle their own pane teardown.
       if (disposed) return;
 
-      if (opts.shouldReconnect?.(sessionId, ev.code)) {
+      if (opts.shouldReconnect?.(sessionId, ev.code, everOpened)) {
         const delay = Math.min(reconnectMs, MAX_RECONNECT_MS);
         setState("reconnecting…", "connecting");
         reconnectTimer = window.setTimeout(() => {
@@ -455,6 +468,12 @@ export function createAttachConnection(
         return;
       }
 
+      if (!everOpened) {
+        setState("not attached", "closed");
+        opts.onNeverAttached?.(sessionId);
+        return;
+      }
+
       setState(`closed (${ev.code})`, "closed");
       opts.onClosed?.(sessionId);
     };

web/src/catalog.test.ts

@@ -427,6 +427,44 @@ describe("session cards (#107)", () => {
     expect(line2?.textContent).not.toContain("exited");
   });
 
+  // #168: a dormant card is a muted variant with a resume action in place of
+  // "spawn similar", since there is nothing running to clone from live state.
+  it("renders a dormant card muted, with a resume action instead of spawn-similar", async () => {
+    const calls: string[] = [];
+    window.fetch = ((url: string, init?: RequestInit) => {
+      calls.push(`${init?.method ?? "GET"} ${url}`);
+      return Promise.resolve(
+        new Response(JSON.stringify({ id: "aaaaaaaa-0000-0000-0000-000000000120", status: "Running" }), {
+          status: 200,
+        }),
+      );
+    }) as typeof fetch;
+    const s = session({ id: "aaaaaaaa-0000-0000-0000-000000000120", status: "Dormant" });
+    const el = renderSidebar(storeWith([s])).el;
+    const row = rowFor(el, s.id) as HTMLElement;
+    expect(row.classList.contains("is-dormant")).toBe(true);
+    expect(row.querySelector(".leaf-clone")).toBeNull();
+    const resumeBtn = row.querySelector<HTMLButtonElement>(".leaf-resume");
+    expect(resumeBtn).toBeTruthy();
+    resumeBtn?.click();
+    await flush();
+    expect(calls).toContain(`POST /api/sessions/${s.id}/resume`);
+  });
+
+  // #168: a two-way running/dead test made a dormant card lie to screen
+  // readers — the visible flag says dormant, the aria-label said "exited".
+  it("marks a dormant row's status and aria-label distinctly from dead", () => {
+    const s = session({
+      id: "aaaaaaaa-0000-0000-0000-000000000119",
+      status: "Dormant",
+    });
+    const el = renderSidebar(storeWith([s])).el;
+    const row = rowFor(el, s.id) as HTMLElement;
+    expect(row.dataset.status).toBe("dormant");
+    expect(row.getAttribute("aria-label")).toContain("dormant");
+    expect(row.getAttribute("aria-label")).not.toContain("exited");
+  });
+
   it("carries the state word only in tooltips and aria labels, never as text", () => {
     const s = session({
       id: "aaaaaaaa-0000-0000-0000-000000000019",

web/src/catalog.ts

@@ -1,5 +1,5 @@
 import { escapeHtml } from "./html.js";
-import { ApiRequestError, getDaemonInfo, killSession, renameSession } from "./api.js";
+import { ApiRequestError, getDaemonInfo, killSession, renameSession, resumeSession } from "./api.js";
 import { openForceKillDialog, openKillConfirmDialog } from "./killDialog.js";
 import { openContextMenu } from "./contextMenu.js";
 import { toggleHelp } from "./help.js";
@@ -104,6 +104,21 @@ const STATE_WORDS: Record<string, string> = {
   error: "Error",
 };
 
+// #168: dormancy is not an exit (docs/SIDEBAR.md), so `dataset.status` and
+// the aria-label read the session's own three-way `status` rather than a
+// two-way running/dead test that folded `Dormant` into "dead"/"exited".
+function statusSlug(status: Session["status"]): string {
+  if (status === "Running") return "running";
+  if (status === "Dormant") return "dormant";
+  return "dead";
+}
+
+function statusWord(status: Session["status"]): string {
+  if (status === "Running") return "running";
+  if (status === "Dormant") return "dormant";
+  return "exited";
+}
+
 /** docs/SIDEBAR.md: the activity rail is pinned to the row's own left edge,
  * full height. The row's own padding (`renderNode`) shifts outward with
  * nesting depth, carrying the rail with it. */
@@ -203,33 +218,46 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
   row.style.paddingLeft = `${depth * 16 + 8}px`;
   row.dataset.sessionId = s.id;
   row.dataset.navKey = `session:${s.id}`;
-  const running = s.status === "Running";
-  row.dataset.status = running ? "running" : "dead";
+  row.dataset.status = statusSlug(s.status);
+  // docs/SIDEBAR.md: a dormant card is a muted variant — nothing running
+  // behind it, so it earns no activity colour or spawn-similar affordance.
+  const dormant = s.status === "Dormant";
+  row.classList.toggle("is-dormant", dormant);
   const name = sessionName(s);
   const slug = activityColorSlug(s.activity ?? "Idle");
   const stateWord = STATE_WORDS[slug] ?? STATE_WORDS.idle;
-  row.setAttribute(
-    "aria-label",
-    `${name}, ${running ? "running" : "exited"}, ${stateWord}`,
-  );
+  row.setAttribute("aria-label", `${name}, ${statusWord(s.status)}, ${stateWord}`);
+  const cloneOrResumeAction = dormant
+    ? `<button class="leaf-act leaf-resume" type="button" title="Resume session" aria-label="Resume ${escapeHtml(name)}">↻</button>`
+    : `<button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${escapeHtml(name)}">⧉</button>`;
   // docs/SIDEBAR.md: line 1 reserves action width, and line 2 is unconditional.
   row.innerHTML = `
     ${activityRailMarkup(slug, stateWord)}
     <span class="card-line1">
       <span class="leaf-name${isProvisionalName(s) ? " is-provisional" : ""}">${escapeHtml(name)}</span>
       <span class="leaf-actions">
-        <button class="leaf-act leaf-clone" type="button" title="Spawn similar" aria-label="Spawn similar to ${escapeHtml(name)}">⧉</button>
+        ${cloneOrResumeAction}
         <button class="leaf-act leaf-kill" type="button" title="Kill session" aria-label="Kill ${escapeHtml(name)}">✕</button>
       </span>
     </span>
     ${metaLine(s, now)}
   `;
-  const similarBtn = row.querySelector(".leaf-clone") as HTMLButtonElement;
-  similarBtn.addEventListener("click", (ev) => {
+  const similarBtn = row.querySelector<HTMLButtonElement>(".leaf-clone");
+  similarBtn?.addEventListener("click", (ev) => {
     ev.preventDefault();
     ev.stopPropagation();
     document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur }));
   });
+  const resumeBtn = row.querySelector<HTMLButtonElement>(".leaf-resume");
+  resumeBtn?.addEventListener("click", (ev) => {
+    ev.preventDefault();
+    ev.stopPropagation();
+    resumeBtn.disabled = true;
+    void resumeSession(cur.id).catch((e: Error) => {
+      resumeBtn.disabled = false;
+      alert(`Failed to resume: ${e.message}`);
+    });
+  });
   const killBtn = row.querySelector(".leaf-kill") as HTMLButtonElement;
   killBtn.addEventListener("click", (ev) => {
     ev.preventDefault();
@@ -244,11 +272,19 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
     ev.stopPropagation();
     openContextMenu(ev.clientX, ev.clientY, [
       { label: "Rename…", onSelect: () => beginRename(row, cur) },
-      {
-        label: "Spawn similar",
-        onSelect: () =>
-          document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur })),
-      },
+      cur.status === "Dormant"
+        ? {
+            label: "Resume",
+            onSelect: () =>
+              void resumeSession(cur.id).catch((e: Error) =>
+                alert(`Failed to resume: ${e.message}`),
+              ),
+          }
+        : {
+            label: "Spawn similar",
+            onSelect: () =>
+              document.dispatchEvent(new CustomEvent(SPAWN_SIMILAR_EVENT, { detail: cur })),
+          },
       {
         label: "Kill session",
         danger: true,
@@ -260,10 +296,8 @@ function renderNode(node: TreeNode, depth: number): HTMLElement {
     cur = next;
     const nextSlug = activityColorSlug(next.activity ?? "Idle");
     const nextWord = STATE_WORDS[nextSlug] ?? STATE_WORDS.idle;
-    row.setAttribute(
-      "aria-label",
-      `${sessionName(next)}, ${next.status === "Running" ? "running" : "exited"}, ${nextWord}`,
-    );
+    row.dataset.status = statusSlug(next.status);
+    row.setAttribute("aria-label", `${sessionName(next)}, ${statusWord(next.status)}, ${nextWord}`);
     const rail = row.querySelector(".activity-rail");
     if (rail) rail.outerHTML = activityRailMarkup(nextSlug, nextWord);
     const meta = row.querySelector(".card-line2");

web/src/connections.ts

@@ -25,8 +25,13 @@ export interface PoolOptions {
   /** Fired when a connection's socket closes on its own (session ended/dropped),
    *  not via an intentional close/eviction. The embedder closes the pane. */
   onClosed?: (id: Uuid) => void;
+  /** Fired when a connection's handshake never completed and so was never
+   *  retried (see `AttachOptions.onNeverAttached`). Unlike `onClosed`, the
+   *  embedder should not assume the session is gone — a dormant session's
+   *  pane wants its resume affordance, not teardown. */
+  onNeverAttached?: (id: Uuid) => void;
   /** Forwarded to each connection: should a dropped socket be retried? */
-  shouldReconnect?: (id: Uuid, code: number) => boolean;
+  shouldReconnect?: (id: Uuid, code: number, everOpened: boolean) => boolean;
 }
 
 /**
@@ -85,7 +90,9 @@ export class ConnectionPool {
         {
           onRequestClose: (sid) => this.opts.onRequestClose?.(sid),
           onClosed: (sid) => this.opts.onClosed?.(sid),
-          shouldReconnect: (sid, code) => this.opts.shouldReconnect?.(sid, code) ?? false,
+          onNeverAttached: (sid) => this.opts.onNeverAttached?.(sid),
+          shouldReconnect: (sid, code, everOpened) =>
+            this.opts.shouldReconnect?.(sid, code, everOpened) ?? false,
         },
         info,
       );

web/src/main.ts

@@ -19,6 +19,7 @@ import {
   getDaemonInfo,
   gitRoot,
   projects as fetchProjects,
+  resumeSession,
 } from "./api.js";
 import {
   buildFastForwardRequest,
@@ -172,17 +173,42 @@ const pool = new ConnectionPool({
   // pane is never left lying around.
   onRequestClose: (id) => closePane(id),
   onClosed: (id) => closePane(id),
-  shouldReconnect: (id, code) => shouldRetryClose(id, code, store.snapshot().sessions),
+  // #168 review: a handshake that never opened (a dormant session's `409
+  // not_attachable`, most likely) isn't "the session is gone" — drop the dead
+  // connection and re-render so the leaf gets a fresh attempt if the catalog
+  // still says Running, or the resume affordance if it doesn't.
+  onNeverAttached: (id) => {
+    pool.close(id);
+    mv?.render();
+  },
+  shouldReconnect: (id, code, everOpened) =>
+    shouldRetryClose(id, code, store.snapshot().sessions, everOpened),
 });
 
 // Session death used to reach the UI on two uncoordinated channels — the row
 // from the events socket, the pane from `ws.onclose` — so either could happen
 // without the other. The catalog is the authority: a pane for a session that is
 // no longer listed gets closed here.
+//
+// A pane can also be showing the dormant placeholder (or, briefly, a dead
+// socket) rather than a live attach (#168): when an *open* session's
+// Running-ness flips — most commonly a resume completing — the pane and the
+// placeholder need to swap without waiting on an unrelated layout change.
+let lastOpenRunning = new Map<string, boolean>();
 store.subscribe((state) => {
   for (const id of mv?.openSessions() ?? []) {
     if (!state.sessions.has(id)) closePane(id);
   }
+  const open = mv?.openSessions() ?? new Set<string>();
+  const nextRunning = new Map<string, boolean>();
+  let runningChanged = false;
+  for (const id of open) {
+    const running = state.sessions.get(id)?.status === "Running";
+    nextRunning.set(id, running);
+    if (lastOpenRunning.get(id) !== running) runningChanged = true;
+  }
+  lastOpenRunning = nextRunning;
+  if (runningChanged) mv?.render();
 });
 
 function closePane(id: string): void {
@@ -275,6 +301,8 @@ mv = createMultiView({
   // catalog (no sessions) to attach.
   onOpenSessionsChange: updateShellRoute,
   onLayoutChange: scheduleSave,
+  sessionFor: (id) => store.snapshot().sessions.get(id),
+  onResume: (id) => resumeSession(id),
 });
 let contentShowsMv = false;
 /** Put the multi-view in the content pane, without rendering it. A preview

web/src/multiview.test.ts

@@ -45,7 +45,7 @@ function fakeSidebar(): SidebarHandle {
   };
 }
 
-function makeMv(layout: Layout): MultiView {
+function makeMv(layout: Layout, overrides: Partial<Parameters<typeof createMultiView>[0]> = {}): MultiView {
   return createMultiView({
     pool: fakePool(),
     layout,
@@ -53,6 +53,7 @@ function makeMv(layout: Layout): MultiView {
     infoFor: () => ({ name: "sess", command: "bash" }),
     onDisconnect: () => {},
     renderWelcome: () => document.createElement("div"),
+    ...overrides,
   });
 }
 
@@ -87,6 +88,102 @@ describe("multiview empty panes", () => {
   });
 });
 
+// #168 review: highlighting a dormant session used to open a pane and attempt
+// a live attach, which the daemon answers with 404/409 and the socket dies
+// with WS 1006. A dormant leaf must never reach the pool at all — it gets the
+// resume affordance instead.
+describe("multiview dormant gating (#168)", () => {
+  beforeEach(() => {
+    stubFetch();
+    document.body.replaceChildren();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function dormantSession(id: string) {
+    return {
+      id,
+      cwd: "/home/n/work",
+      command: "claude",
+      env: {},
+      metadata: { name: "worker" },
+      status: "Dormant" as const,
+      created_at: "2026-08-24T10:00:00Z",
+    };
+  }
+
+  it("never hands a dormant session's leaf to the pool, and shows a resume affordance", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "d1", "row", true);
+    const setVisible = vi.fn();
+    const pool = { setVisible, setFocus() {} } as unknown as ConnectionPool;
+    const mv = createMultiView({
+      pool,
+      layout,
+      sidebar: fakeSidebar(),
+      infoFor: () => ({ name: "worker", command: "claude" }),
+      onDisconnect: () => {},
+      renderWelcome: () => document.createElement("div"),
+      sessionFor: (id) => (id === "d1" ? dormantSession("d1") : undefined),
+    });
+    document.body.appendChild(mv.el);
+    mv.render();
+    await flush();
+
+    expect(setVisible).toHaveBeenCalledWith([], expect.anything());
+    const pane = mv.el.querySelector('[data-leaf-id]') as HTMLElement;
+    expect(pane.querySelector(".mv-pane-dormant")).toBeTruthy();
+    expect(pane.textContent).toContain("worker");
+    expect(pane.textContent).toContain("/home/n/work");
+    expect(pane.querySelector(".mv-dormant-resume")).toBeTruthy();
+  });
+
+  it("still attaches a Running session's leaf normally", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "r1", "row", true);
+    const setVisible = vi.fn();
+    const pool = { setVisible, setFocus() {} } as unknown as ConnectionPool;
+    const mv = createMultiView({
+      pool,
+      layout,
+      sidebar: fakeSidebar(),
+      infoFor: () => ({ name: "worker", command: "claude" }),
+      onDisconnect: () => {},
+      renderWelcome: () => document.createElement("div"),
+      sessionFor: (id) => ({ ...dormantSession(id), status: "Running" }),
+    });
+    document.body.appendChild(mv.el);
+    mv.render();
+    await flush();
+
+    expect(setVisible).toHaveBeenCalledWith(
+      [expect.objectContaining({ id: "r1" })],
+      expect.anything(),
+    );
+  });
+
+  it("clicking resume calls back with the session id", async () => {
+    const layout = emptyLayout();
+    const tab = layout.tabs[0];
+    tab.focusedLeafId = splitLeaf(tab, "", "d1", "row", true);
+    const onResume = vi.fn().mockResolvedValue(undefined);
+    const mv = makeMv(layout, {
+      sessionFor: (id) => (id === "d1" ? dormantSession("d1") : undefined),
+      onResume,
+    });
+    document.body.appendChild(mv.el);
+    mv.render();
+    await flush();
+
+    mv.el.querySelector<HTMLButtonElement>(".mv-dormant-resume")?.click();
+    expect(onResume).toHaveBeenCalledWith("d1");
+  });
+});
+
 describe("multiview pane-drag swap", () => {
   beforeEach(() => {
     stubFetch();

web/src/multiview.ts

@@ -6,6 +6,10 @@
 
 import type { SidebarHandle } from "./catalog.js";
 import type { ConnectionPool } from "./connections.js";
+import { activityDurationLabel, activityHeldMs } from "./activity.js";
+import { escapeHtml } from "./html.js";
+import { sessionName } from "./types.js";
+import type { Session } from "./types.js";
 import {
   activeTab,
   addTab,
@@ -34,6 +38,14 @@ export interface MultiViewOptions {
   onDisconnect: (sessionId: string) => void;
   /** Welcome content for an empty tab. */
   renderWelcome: () => HTMLElement;
+  /** The session behind a leaf, when known — used to gate a live attach on
+   *  `status === "Running"` (#168 review) and to fill in the dormant pane's
+   *  resume affordance. A leaf whose session this returns `undefined` for
+   *  (unknown to the caller) attaches as before, so callers that don't wire
+   *  this up see no change in behaviour. */
+  sessionFor?: (sessionId: string) => Session | undefined;
+  /** Resume a dormant session (#166/#168), from its pane's own affordance. */
+  onResume?: (sessionId: string) => Promise<unknown>;
   /** Called when a spawn fills a pane with a new session, so the shell can
    *  re-evaluate its route (sidebar vs attach layout). */
   onOpenSessionsChange?: () => void;
@@ -262,6 +274,44 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     persist();
   }
 
+  // ---- dormant panes (#168 review) ----
+
+  /** The session behind `sessionId` when it is known and not `Running` —
+   *  what gates a leaf away from a live attach and towards the resume
+   *  affordance instead. */
+  function dormantSessionFor(sessionId: string): Session | undefined {
+    const s = opts.sessionFor?.(sessionId);
+    return s && s.status !== "Running" ? s : undefined;
+  }
+
+  /** docs/PREVIEW.md / docs/SIDEBAR.md: what the content pane can honestly
+   *  show for a session with no pane behind it — its metadata and a resume
+   *  affordance, never a live terminal that would just die with WS 1006. */
+  function renderDormantPane(host: HTMLElement, session: Session): void {
+    const heldMs = activityHeldMs(session.last_activity_at ?? session.created_at, Date.now());
+    const age = heldMs !== null ? activityDurationLabel(heldMs) : null;
+    const wrap = document.createElement("div");
+    wrap.className = "mv-pane-dormant";
+    wrap.innerHTML = `
+      <div class="mv-dormant-glyph" aria-hidden="true">◌</div>
+      <div class="mv-dormant-name">${escapeHtml(sessionName(session))}</div>
+      <div class="mv-dormant-cwd" title="${escapeHtml(session.cwd)}">${escapeHtml(session.cwd)}</div>
+      <div class="mv-dormant-detail">dormant${age ? ` for ${escapeHtml(age)}` : ""} — nothing running behind it</div>
+      <button type="button" class="btn btn-primary mv-dormant-resume">Resume</button>
+    `;
+    const btn = wrap.querySelector(".mv-dormant-resume") as HTMLButtonElement;
+    btn.addEventListener("click", () => {
+      btn.disabled = true;
+      btn.textContent = "Resuming…";
+      opts.onResume?.(session.id)?.catch((e: Error) => {
+        btn.disabled = false;
+        btn.textContent = "Resume";
+        alert(`Failed to resume: ${e.message}`);
+      });
+    });
+    host.replaceChildren(wrap);
+  }
+
   // ---- pane + split DOM ----
 
   function buildPane(leaf: Extract<Node, { kind: "leaf" }>): {
@@ -378,7 +428,12 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     if (node.kind === "leaf") {
       const pane = buildPane(node);
       if (node.sessionId) {
-        hosts.push({ id: node.sessionId, host: pane.host, info: infoFor(node.sessionId) });
+        const dormant = dormantSessionFor(node.sessionId);
+        if (dormant) {
+          renderDormantPane(pane.host, dormant);
+        } else {
+          hosts.push({ id: node.sessionId, host: pane.host, info: infoFor(node.sessionId) });
+        }
       }
       return pane.el;
     }
@@ -616,9 +671,13 @@ export function createMultiView(opts: MultiViewOptions): MultiView {
     wrap.appendChild(pane.el);
     canvas.appendChild(wrap);
 
+    const dormant = focused.sessionId ? dormantSessionFor(focused.sessionId) : undefined;
+    if (dormant) renderDormantPane(pane.host, dormant);
     // Only the focused leaf's session is live on mobile; the rest park.
     pool.setVisible(
-      focused.sessionId ? [{ id: focused.sessionId, pane: pane.host, info: infoFor(focused.sessionId) }] : [],
+      focused.sessionId && !dormant
+        ? [{ id: focused.sessionId, pane: pane.host, info: infoFor(focused.sessionId) }]
+        : [],
       { focus: !preview && !quietRender },
     );
     if (!preview) pool.setFocus(focused.sessionId ?? null);

web/src/reconnect.test.ts

@@ -47,6 +47,13 @@ describe("shouldRetryClose", () => {
   it("never retries a clean close", () => {
     expect(shouldRetryClose("a", 1000, running)).toBe(false);
   });
+
+  // #168 review: a handshake that never opened is a rejection (e.g. a
+  // dormant session's 409 not_attachable), not a dropped stream. Retrying it
+  // loops forever if the catalog status hasn't caught up yet.
+  it("never retries a socket that never opened, even if the catalog still says running", () => {
+    expect(shouldRetryClose("a", 1006, running, false)).toBe(false);
+  });
 });
 
 describe("backoff bounds", () => {

web/src/reconnect.ts

@@ -26,7 +26,15 @@ export function shouldRetryClose(
   sessionId: Uuid,
   code: number,
   sessions: ReadonlyMap<Uuid, Session>,
+  /** Did this socket ever reach `open`? A handshake that never completed is
+   *  the daemon rejecting the attach (dormant/unknown) rather than a dropped
+   *  stream — retrying it spins in place until the catalog updates, which for
+   *  a dormant session it never will (#168 review). Defaults to `true` so
+   *  existing callers that only track drops of an established link are
+   *  unaffected. */
+  everOpened = true,
 ): boolean {
   if (code >= APPLICATION_CLOSE || code === CLEAN_CLOSE) return false;
+  if (!everOpened) return false;
   return sessions.get(sessionId)?.status === "Running";
 }

web/src/routes.ts

@@ -37,6 +37,12 @@ export function sessionFocus(id: Uuid): string {
   return `${session(id)}/focus`;
 }
 
+/** `POST /api/sessions/:id/resume` (#166/#168): respawn a dormant session
+ * under its own uuid and sidecar. */
+export function sessionResume(id: Uuid): string {
+  return `${session(id)}/resume`;
+}
+
 /** Append the `path` query parameter `DIRS` and `GITROOT` accept. */
 export function withPathQuery(route: string, value: string): string {
   return `${route}?${PATH_QUERY}=${encodeURIComponent(value)}`;

web/src/styles.css

@@ -1210,12 +1210,16 @@ textarea {
 }
 
 /* Exited sessions recede: dimmed name + an "exited" badge carry status, so it's
-   never the running tint's absence alone doing the work. */
-.tree-leaf[data-status="dead"] {
+   never the running tint's absence alone doing the work. A dormant session
+   (#168, docs/SIDEBAR.md) reads the same muted way — it is known, not gone,
+   but there is nothing running behind it either. */
+.tree-leaf[data-status="dead"],
+.tree-leaf.is-dormant {
   color: var(--muted);
 }
 
-.tree-leaf[data-status="dead"] .leaf-name {
+.tree-leaf[data-status="dead"] .leaf-name,
+.tree-leaf.is-dormant .leaf-name {
   color: var(--muted);
   font-weight: 400;
 }
@@ -1754,7 +1758,8 @@ input.leaf-rename:focus {
   }
 }
 
-.leaf-clone:hover {
+.leaf-clone:hover,
+.leaf-resume:hover {
   color: var(--accent);
   background: var(--accent-tint);
   border-color: color-mix(in oklab, var(--accent) 40%, transparent);
@@ -3265,6 +3270,42 @@ input.leaf-rename:focus {
   font-size: var(--fs-13);
 }
 
+/* #168: what a pane shows for a dormant session — its metadata and a resume
+   action, in place of the live terminal there is nothing to attach to. */
+.mv-pane-dormant {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sp-2);
+  padding: var(--sp-4);
+  text-align: center;
+  color: var(--muted);
+}
+.mv-dormant-glyph {
+  font-size: 28px;
+  color: var(--faint);
+}
+.mv-dormant-name {
+  font-size: var(--fs-15);
+  font-weight: 500;
+  color: var(--ink);
+}
+.mv-dormant-cwd {
+  font-size: var(--fs-12);
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.mv-dormant-detail {
+  font-size: var(--fs-12);
+}
+.mv-dormant-resume {
+  margin-top: var(--sp-2);
+}
+
 /* pane tools cluster (disconnect / split / close), top-right corner. The attach
    header's own disconnect button is hidden — ⏻ lives here as the leftmost tool. */
 .mv-pane-tools {

web/src/tree.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { buildTree, mergeLinear, type TreeFolder, type TreeNode } from "./tree.js";
+import { buildTree, compareNodes, mergeLinear, type TreeFolder, type TreeNode } from "./tree.js";
 import type { Session } from "./types.js";
 
 function session(id: string, cwd: string, command = "bash"): Session {
@@ -67,6 +67,42 @@ describe("buildTree", () => {
     expect(root.children[0].kind).toBe("folder");
     expect(root.children[1].kind).toBe("leaf");
   });
+
+  // #168, docs/SIDEBAR.md: a dormant session takes the lowest precedence in
+  // the ordering, so live work always sorts above it, even a name that would
+  // otherwise sort first.
+  it("sorts a dormant session after live ones in the same folder, name notwithstanding", () => {
+    const dormant = { ...session("aaa-dormant", "/home/n/work"), status: "Dormant" } as Session;
+    const live = session("zzz-live", "/home/n/work");
+    const root = buildTree([dormant, live], "/home/n") as TreeFolder;
+    const folder = root.children[0] as TreeFolder;
+    const ids = folder.children.map((c) => (c.kind === "leaf" ? c.session.id : c.name));
+    expect(ids).toEqual(["zzz-live", "aaa-dormant"]);
+  });
+
+  it("still sorts dormant sessions by name against each other", () => {
+    const a = {
+      ...session("a", "/home/n/work"),
+      status: "Dormant",
+      metadata: { name: "a" },
+    } as Session;
+    const b = {
+      ...session("b", "/home/n/work"),
+      status: "Dormant",
+      metadata: { name: "b" },
+    } as Session;
+    const root = buildTree([b, a], "/home/n") as TreeFolder;
+    const folder = root.children[0] as TreeFolder;
+    const ids = folder.children.map((c) => (c.kind === "leaf" ? c.session.id : c.name));
+    expect(ids).toEqual(["a", "b"]);
+  });
+
+  it("exposes the leaf/name precedence directly via compareNodes", () => {
+    const dormant: TreeNode = { kind: "leaf", session: { ...session("a", "/x"), status: "Dormant" } };
+    const live: TreeNode = { kind: "leaf", session: session("b", "/x") };
+    expect(compareNodes(dormant, live)).toBeGreaterThan(0);
+    expect(compareNodes(live, dormant)).toBeLessThan(0);
+  });
 });
 
 describe("mergeLinear", () => {

web/src/tree.ts

@@ -18,8 +18,16 @@ export interface TreeLeaf {
 
 export type TreeNode = TreeFolder | TreeLeaf;
 
+/** docs/SIDEBAR.md: a dormant session takes the lowest precedence in the
+ * ordering, so live work always sorts above it regardless of name. */
+function dormantRank(node: TreeNode): number {
+  return node.kind === "leaf" && node.session.status === "Dormant" ? 1 : 0;
+}
+
 export function compareNodes(a: TreeNode, b: TreeNode): number {
   if (a.kind !== b.kind) return a.kind === "folder" ? -1 : 1;
+  const rank = dormantRank(a) - dormantRank(b);
+  if (rank !== 0) return rank;
   const an = a.kind === "folder" ? a.name : sessionName(a.session);
   const bn = b.kind === "folder" ? b.name : sessionName(b.session);
   return an.localeCompare(bn);