@monster-orange/den 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.12] - 2026-11-07
+
+### Added
+
+- **Agents tab layouts.** A switch in the page header picks Focus, Tabs or
+  Tile, and so do ⌃⇧1, ⌃⇧2 and ⌃⇧3 (Ctrl+Shift+digit on every OS) and ⌘K
+  "Layout: Focus/Tabs/Tile". ⌘1-9 and Ctrl+1-9 stay the browser's, for its
+  tabs; inside a terminal the layout keys never reach the agent. Focus, the default, shows one pane: a
+  click replaces it, and Shift-click or ⌘-click adds one alongside. Tabs
+  shows one pane under a strip of tabs. Tile is a grid: one pane fills
+  it, two sit side by side, three or four make a 2×2. At phone width,
+  Focus and Tile show as Tabs. Your choice is saved for you
+  (`agents.layout` in `config/local/user.yml`, `agents_layout` in
+  `/api/settings`, and Settings › Agents), and the URL says it
+  (`&layout=`).
+- **Named tabs.** Each tab shows the agent's name, then its persona and
+  workspace, and a dot when it is waiting. Double-click a tab to rename
+  the agent. The name is stored in its record (`displayName`) and shows in
+  the list, its pane, ⌘K, the Workspaces page and `agents list --json`.
+  Start fresh and Relaunch keep it. The id never changes. The route is
+  `POST /api/workspaces/<ws>/agents/<id>/name`.
+- **Shift+Enter is a soft newline in agent terminals.** It sends the
+  runtime's `softNewline` from the runtime catalog, not Enter: ESC CR for
+  Claude Code and Gemini CLI (and by default), Ctrl+J for Codex CLI. A
+  plain session's Shift+Enter is still Enter. Catalog entries may set
+  `softNewline: esc-cr | lf | none`.
+- **The session's name in the pane header.** Claude Code's `/rename` shows
+  after the runtime (` · api spike`), and in the tab, the list and ⌘K. Den
+  reads it from the session's transcript, following the file from where it
+  last stopped (the catalog marks this source `unofficial`; a name it
+  can't read is none). The most recent rename wins, Den's or the
+  runtime's. `GET /api/sessions`, `agents list --json` and the start and
+  resume answers carry it as `sessionName`. Catalog entries may set
+  `titleFromOsc` (no runtime does yet, and the session host doesn't read
+  titles yet).
+- **Links and paths in agent panes are clickable.** ⌘-click (Ctrl-click on
+  Windows and Linux) opens a URL or an OSC 8 link in a new tab
+  (`noopener`), http and https only; a plain click still selects. A file
+  path inside the agent's workspace (`src/foo.ts:42`, absolute paths) is
+  a link: ⌘-click opens it in the editor set in Settings › Editor &
+  terminal › "Open file links in" (`editor_open`: vscode, cursor, zed, or
+  none to copy the path, the default). The server checks a path exists
+  inside the workspace with `GET /api/workspaces/<ws>/agents/<id>/paths`
+  (stat only). Den now ships `@xterm/addon-web-links` 0.12.0, served from
+  `/vendor/`.
+
+### Changed
+
+- **The Agents tab fills the window.** The list and the panes reach down to
+  14px above the runs dock at any window height, with the dock open or
+  shut. They used to stop at a fixed guess of the window less 300px.
+- **Re-picking the workspace in view on a page with `?ws=`** (Workspaces'
+  detail pane) now updates `?ws=` before the reload, so the page shows the
+  pick and not the old workspace.
+- **Every terminal fits its pane.** A terminal used to be sized for its
+  pane's padding as well, so its last row could be cut off. It now fits
+  the space inside the padding, in every layout, and refits when the
+  window or the dock changes size.
+
+### Migrations
+
+None. The record's new `displayName` and `displayNameAt` are optional:
+records without them read as before. The layout pref is optional and
+defaults to Focus; `editor_open` is optional and defaults to none. The
+catalog's new `softNewline`, `sessionName` and `titleFromOsc` are
+optional.
+
+## [0.4.11] - 2026-11-07
+
+### Changed
+
+- **Picking a workspace in the top bar also makes it the CLI default.**
+  There is one "current workspace": choosing one in the Workspace menu
+  sets what pages show and where `<cli>` commands run (workspaces.yml, as
+  Local Dev's "Make CLI default" does). "All active (n)" changes only what
+  pages show; the CLI default stays. If the CLI default can't be set,
+  nothing changes and the error shows.
+- **The menu's separate "Make <ws> the CLI default" item is gone**, since
+  picking a workspace does it. The "CLI default" tag stays on its row, and
+  Local Dev keeps its "Make CLI default" button, to set it without
+  changing what pages show. Each workspace row's tooltip says so.
+- **Picking the workspace already in view makes it the CLI default** when
+  it isn't one (after Local Dev's "Make CLI default" or `<cli> workspace
+  focus` moved it). The view stays as it is.
+- **Pages whose address names a workspace follow the pick.** Workspaces'
+  detail pane and breadcrumb now show the workspace the top bar picked,
+  not the one in the old `?ws=`.
+
+### Migrations
+
+None.
+
 ## [0.4.10] - 2026-11-07
 
 ### Changed

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.10/hero-dark.png">
-  <img src="docs/images/0.4.10/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.12/hero-dark.png">
+  <img src="docs/images/0.4.12/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -38,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.10/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.12/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -68,10 +68,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.10/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.10/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.10/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.10/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.12/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.12/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.12/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.12/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -2132,15 +2132,75 @@ agent of the workspaces in view, and their terminals in the browser.
   it, or start it again.
 - **A pane** is the session's terminal: it shows the scrollback, then the
   live output, and your keys go to the session; its size follows the
-  pane. Click more rows to tile up to four (a fifth closes the oldest).
-  The URL holds the open panes (`/agents?open=<id>,<id>`), so a link, a
-  reload or Back reopens them.
+  pane. Up to four are open at once (a fifth closes the oldest). The URL
+  holds the open panes (`/agents?open=<id>,<id>`), so a link, a reload or
+  Back reopens them. The list and the panes fill the window down to the
+  runs dock.
+- **Layouts.** The switch in the page header picks one, or ⌃⇧1, ⌃⇧2, ⌃⇧3
+  (Ctrl+Shift+1/2/3 on every OS; ⌘1-9 and Ctrl+1-9 stay the browser's, for
+  its tabs), or ⌘K "Layout: Focus", "Layout: Tabs", "Layout: Tile". Inside
+  a terminal those keys switch the layout and never reach the agent:
+  - **Focus** (the default) shows one pane. A click replaces it;
+    Shift-click or ⌘-click adds one alongside.
+  - **Tabs** shows one pane under a strip of tabs. Each tab has the
+    agent's name, then its persona and workspace ("reviewer · north"), and
+    a dot when it is waiting.
+  - **Tile** shows the open panes in a grid: one fills it, two sit side
+    by side, three or four make a 2×2.
+
+  At phone width, Focus and Tile show as Tabs. The choice is yours: it is
+  saved in `config/local/user.yml` as `agents.layout` (`POST /api/settings
+{ agents_layout: "focus" | "tabs" | "tile" | null }`, also in Settings ›
+  Agents). The URL says it too (`&layout=tabs`); a link's layout is used
+  for that page and saves nothing.
+
+- **Rename an agent** by double-clicking its tab: Enter saves, Esc keeps
+  the old name. The name (trimmed, up to 40 characters, no control
+  characters) is stored in the agent's record as `displayName`, and the
+  list, its pane, ⌘K and `agents list --json` show it. The agent's id
+  never changes. Clear the name to go back to the id. The route is `POST
+/api/workspaces/<ws>/agents/<id>/name` (`{ name: string | null }`), for
+  a person only.
 - **Close** (×) detaches, as leaving the page does: the session keeps
   running, and opening it again replays what you missed. **Stop** (an
   agent only) is `agents stop`. **+ Start agent** (or
   `/agents?start=1`) starts one and opens its pane; under All it asks for
   the workspace. It says before Start whether the runtime can run, as the
   Workspaces page's form does. It never asks for the admin password.
+- **Shift+Enter** adds a soft newline instead of submitting. It sends the
+  runtime's `softNewline` from the runtime catalog: `esc-cr` (ESC CR, the
+  default; Claude Code and Gemini CLI), `lf` (Ctrl+J; Codex CLI) or `none`
+  (Enter itself). A plain session's Shift+Enter is Enter. A catalog entry
+  a distribution or `user.yml` adds may set `softNewline`.
+- **The session's name.** A runtime may name its conversation: Claude
+  Code's `/rename` writes a `custom-title` record to its transcript, and
+  Den reads the latest one (the catalog marks this source `unofficial`:
+  the format is undocumented, so a name that can't be read is simply
+  none). It reads on from where it last stopped, never the whole file at
+  once. The most recent rename wins, Den's (a tab's) or the runtime's. The
+  pane header adds ` · <name>` after the runtime, and the tab, the list and
+  ⌘K add it too, when it is not empty and says more than the agent's own
+  name or persona. `GET /api/sessions`, `agents list --json` and the start
+  and resume answers (MCP `agent_resume`) carry it as `sessionName`.
+  Codex CLI, Gemini CLI and Grok Build have no name of their own yet. A
+  catalog entry's `titleFromOsc: true` marks a runtime whose terminal
+  title (OSC 0/2) names the session; no built-in runtime sets it, and the
+  session host doesn't read titles yet.
+- **Links.** A URL in a pane, and an OSC 8 hyperlink, open on ⌘-click
+  (Ctrl-click on Windows and Linux) in a new tab, with `noopener`. Only
+  `http:` and `https:` open; an OSC 8 link with any other scheme
+  (`javascript:`, `file:`) is no link. A plain click selects text as
+  ever. A file path an agent prints (`src/foo.ts:42`, `./a/b.js:3:7`, an
+  absolute path) is a link when it exists inside the agent's workspace
+  (its directory, or the agent's own folder), resolved against the
+  agent's folder; one outside it never is. The server checks with `GET
+/api/workspaces/<ws>/agents/<id>/paths?p=<path>&p=…` (stat only, nothing
+  is read; at most 64 at once), which answers each path's absolute path
+  or null. ⌘-click opens it in the editor of Settings › Editor & terminal ›
+  "Open file links in" (`editor_open` in `config/local/user.yml` and
+  `/api/settings`: `vscode`, `cursor` or `zed`, by its URL scheme at the
+  line), or, with `none` (the default), copies its absolute path and says
+  "Copied".
 - ⌘K lists each as "Agents › <ws> / <name>", and "Start agent…".
 - Several browsers and `<cli> sessions attach` can attach to one session
   at once and each sees every byte; the terminal's size is the last
@@ -2626,6 +2686,10 @@ agents:
       dirs: [~/.local/bin, $AIDER_DIR, "{system}"]
       launch:
         argv: ["{bin}"] # "{bin}" first: the path found
+      # Optional, how it behaves in an Agents tab pane (AG-4b):
+      softNewline: esc-cr # what Shift+Enter sends: esc-cr (default), lf, none
+      titleFromOsc: false # its terminal title (OSC 0/2) names the session
+      # sessionName: official | unofficial  (built-in adapters only)
 ```
 
 **Where a runtime's CLI is found.** As your terminal would find it, not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -64,6 +64,7 @@
     "@playwright/test": "^1.61.1",
     "@slack/webhook": "^7.0.2",
     "@xterm/addon-fit": "0.11.0",
+    "@xterm/addon-web-links": "0.12.0",
     "@xterm/xterm": "6.0.0",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",

package/src/shared/agents/catalog.ts

@@ -17,6 +17,18 @@
  *             /usr/local/bin and npm's global bin)
  *   launch    argv: its interactive CLI, "{bin}" first (the path found)
  *
+ * And, optional, how it behaves in a terminal pane (AG-4b):
+ *
+ *   softNewline   what Shift+Enter sends in an Agents tab pane: "esc-cr"
+ *                 (ESC CR, the default), "lf" (Ctrl+J) or "none" (Enter
+ *                 itself: Shift+Enter submits)
+ *   sessionName   where the runtime adapter reads a session's name from:
+ *                 "official" (a documented interface) or "unofficial" (an
+ *                 undocumented file format, read defensively). None: the
+ *                 runtime has no name of its own; Den's rename still works.
+ *   titleFromOsc  the terminal title (OSC 0/2) is a session name. Off by
+ *                 default: many CLIs put a spinner or the cwd there.
+ *
  * Each built-in entry was checked against the vendor's own docs or
  * installer (the URLs beside it). A vendor with no official CLI is left
  * out (docs/distributions.md, Runtimes, says which, and why); nothing is
@@ -38,6 +50,19 @@ export interface CatalogIdentity {
   realpath_under?: string[];
 }
 
+/** What Shift+Enter sends in a pane (AG-4b). */
+export const SOFT_NEWLINES = ["esc-cr", "lf", "none"] as const;
+export type SoftNewline = (typeof SOFT_NEWLINES)[number];
+const SOFT_NEWLINE_SEQ: Record<SoftNewline, string> = {
+  "esc-cr": "\x1b\r",
+  lf: "\n",
+  // none: Shift+Enter is Enter.
+  none: "\r",
+};
+/** How stable a runtime's session-name source is (AG-4b). */
+export const SESSION_NAME_SOURCES = ["official", "unofficial"] as const;
+export type SessionNameSource = (typeof SESSION_NAME_SOURCES)[number];
+
 export interface CatalogEntry {
   id: string;
   vendor: string;
@@ -46,6 +71,19 @@ export interface CatalogEntry {
   version: { args: string[]; identity: CatalogIdentity };
   dirs: string[];
   launch: { argv: string[] };
+  /** What Shift+Enter sends (AG-4b); unset: "esc-cr". */
+  softNewline?: SoftNewline;
+  /** The adapter reads a session name, from a source this stable. */
+  sessionName?: SessionNameSource;
+  /** The terminal title (OSC 0/2) names the session. Unset: no. */
+  titleFromOsc?: boolean;
+}
+
+/** The bytes Shift+Enter sends for an entry (ESC CR when it says none). */
+export function softNewlineSeq(
+  e: Pick<CatalogEntry, "softNewline"> | undefined,
+): string {
+  return SOFT_NEWLINE_SEQ[e?.softNewline ?? "esc-cr"];
 }
 
 /** The keys an entry takes (the validator refuses any other). */
@@ -57,6 +95,9 @@ const ENTRY_KEYS = [
   "version",
   "dirs",
   "launch",
+  "softNewline",
+  "sessionName",
+  "titleFromOsc",
 ] as const;
 
 /** Den's built-in catalog, in the order lists show them. */
@@ -80,6 +121,12 @@ export const BUILTIN_CATALOG: readonly CatalogEntry[] = [
     },
     dirs: ["~/.local/bin", "~/.claude/local", "{system}"],
     launch: { argv: ["{bin}"] },
+    // https://code.claude.com/docs/en/terminal-config: Option+Enter (Meta,
+    // ESC CR) is a newline; /terminal-setup binds Shift+Enter to it.
+    softNewline: "esc-cr",
+    // `/rename` appends {"type":"custom-title","customTitle":…} to the
+    // session's transcript (<token>.jsonl). Undocumented: read defensively.
+    sessionName: "unofficial",
   },
   // Codex CLI. https://github.com/openai/codex: binary `codex`, npm
   // @openai/codex, Homebrew cask codex. The standalone installer
@@ -98,6 +145,9 @@ export const BUILTIN_CATALOG: readonly CatalogEntry[] = [
     },
     dirs: ["$CODEX_INSTALL_DIR", "~/.local/bin", "{system}"],
     launch: { argv: ["{bin}"] },
+    // The composer's insert_newline is Ctrl+J (codex-rs/tui keymap): a
+    // plain terminal's Shift+Enter and Alt+Enter submit (openai/codex#20580).
+    softNewline: "lf",
   },
   // Gemini CLI. https://github.com/google-gemini/gemini-cli: binary
   // `gemini`, npm @google/gemini-cli, Homebrew formula gemini-cli;
@@ -115,6 +165,9 @@ export const BUILTIN_CATALOG: readonly CatalogEntry[] = [
     },
     dirs: ["{system}"],
     launch: { argv: ["{bin}"] },
+    // https://geminicli.com/docs/reference/keyboard-shortcuts: Alt+Enter
+    // (ESC CR), Ctrl+J and Shift+Enter insert a newline.
+    softNewline: "esc-cr",
   },
   // Grok Build. https://docs.x.ai/build/overview: install with
   // https://x.ai/cli/install.sh, run `grok` in a project directory. The
@@ -279,6 +332,29 @@ export function validateCatalogEntry(
     throw new Error(
       `${where}.launch.argv[0]: must be "{bin}" (the path Den found)`,
     );
+  const traits: Pick<
+    CatalogEntry,
+    "softNewline" | "sessionName" | "titleFromOsc"
+  > = {};
+  if (raw.softNewline !== undefined) {
+    if (!(SOFT_NEWLINES as readonly unknown[]).includes(raw.softNewline))
+      throw new Error(
+        `${where}.softNewline: ${shown(raw.softNewline)} must be one of ${SOFT_NEWLINES.join(", ")}`,
+      );
+    traits.softNewline = raw.softNewline as SoftNewline;
+  }
+  if (raw.sessionName !== undefined) {
+    if (!(SESSION_NAME_SOURCES as readonly unknown[]).includes(raw.sessionName))
+      throw new Error(
+        `${where}.sessionName: ${shown(raw.sessionName)} must be one of ${SESSION_NAME_SOURCES.join(", ")}`,
+      );
+    traits.sessionName = raw.sessionName as SessionNameSource;
+  }
+  if (raw.titleFromOsc !== undefined) {
+    if (typeof raw.titleFromOsc !== "boolean")
+      throw new Error(`${where}.titleFromOsc: must be true or false`);
+    traits.titleFromOsc = raw.titleFromOsc;
+  }
   return {
     id,
     vendor: text(`${where}.vendor`, raw.vendor),
@@ -287,6 +363,7 @@ export function validateCatalogEntry(
     version: { args, identity },
     dirs,
     launch: { argv },
+    ...traits,
   };
 }
 

package/src/shared/agents/den-claude.ts

@@ -66,6 +66,7 @@ import { builtinEntry } from "./catalog.js";
 import { catalogFind } from "./catalog-runtime.js";
 import { locateRuntime, type RuntimeFind } from "./runtime-search.js";
 import { claudeProjectsDir } from "../usage/paths.js";
+import { transcriptTitle } from "./transcript-follow.js";
 
 export const DEN_CLAUDE_ID = "den-claude";
 const BIN = "claude";
@@ -313,6 +314,31 @@ export function firstPromptArg(text: string | undefined): string[] {
   return [t.startsWith("-") ? `Prompt: ${t}` : t];
 }
 
+const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+/**
+ * Claude Code's transcript for conversation `token`: <token>.jsonl in any
+ * project under its projects dir, or null (a bad token, none written yet).
+ */
+export function transcriptFile(
+  token: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  if (!token || !TOKEN_RE.test(token)) return null;
+  const root = claudeProjectsDir(env);
+  let projects: string[] = [];
+  try {
+    projects = fs.readdirSync(root);
+  } catch {
+    return null;
+  }
+  for (const p of projects) {
+    const file = path.join(root, p, `${token}.jsonl`);
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}
+
 export const denClaude: Runtime = {
   id: DEN_CLAUDE_ID,
   label: DEN_CLAUDE_CATALOG.name,
@@ -355,17 +381,19 @@ export const denClaude: Runtime = {
   },
   // Its transcript, <token>.jsonl in any project under its projects dir.
   conversationExists(token, env = process.env) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(token)) return false;
-    const root = claudeProjectsDir(env);
-    let projects: string[] = [];
+    return transcriptFile(token, env) !== null;
+  },
+  // AG-4b, unofficial (catalog sessionName): `/rename` appends a
+  // {"type":"custom-title","customTitle":…} record to the transcript; the
+  // latest one, read on from the last ask (never the whole file). Null on
+  // any failure: it must never break a pane.
+  sessionName(rec, env = process.env) {
     try {
-      projects = fs.readdirSync(root);
+      const file = transcriptFile(rec.resumeToken, env);
+      return file ? transcriptTitle(file) : null;
     } catch {
-      return false;
+      return null;
     }
-    return projects.some((p) =>
-      fs.existsSync(path.join(root, p, `${token}.jsonl`)),
-    );
   },
   launchFailures: {
     noConversation: /no conversation found/i,

package/src/shared/agents/records.ts

@@ -72,6 +72,35 @@ export interface AgentRecord {
    * rotation), oldest first.
    */
   rotations?: RotationEntry[];
+  /**
+   * The name a person gave it (AG-4b: double-click its tab), shown in the
+   * Agents tab, its tabs, ⌘K and the agent lists; the id never changes.
+   * checkDisplayName says what one may be.
+   */
+  displayName?: string;
+  /** When displayName was given (ISO 8601): the latest rename wins (AG-4b). */
+  displayNameAt?: string;
+}
+
+/** The longest name a person may give an agent (AG-4b). */
+export const MAX_DISPLAY_NAME = 40;
+
+/**
+ * A name given to an agent, checked (AG-4b): a string, trimmed, at most
+ * MAX_DISPLAY_NAME characters, with no control or format characters (no
+ * newline, no bidi override). Blank (or null) clears it: null. Anything
+ * else throws, saying why.
+ */
+export function checkDisplayName(v: unknown): string | null {
+  if (v === null) return null;
+  if (typeof v !== "string") throw new Error("name must be a string, or null");
+  const name = v.trim();
+  if (!name) return null;
+  if ([...name].length > MAX_DISPLAY_NAME)
+    throw new Error(`name must be at most ${MAX_DISPLAY_NAME} characters`);
+  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(name))
+    throw new Error("name can't have control characters");
+  return name;
 }
 
 /** What an agent's run came to (den#6). Read locally; never sent. */

package/src/shared/agents/runtime.ts

@@ -17,6 +17,7 @@ import {
   type StrategyEntry,
 } from "../strategies/registry.js";
 import type { CatalogEntry } from "./catalog.js";
+import type { AgentRecord } from "./records.js";
 import type { Persona } from "./personas.js";
 import type { BinSource, RuntimeFind } from "./runtime-search.js";
 
@@ -157,6 +158,13 @@ export interface Runtime {
    * conversation's id is taken. Den then tries the other way, once.
    */
   launchFailures?: { noConversation?: RegExp; idInUse?: RegExp };
+  /**
+   * The name the runtime gives the agent's conversation (AG-4b: Claude
+   * Code's `/rename`), or null when it has none or can't say. Optional:
+   * a runtime without it has Den's rename only. Must be quick and never
+   * throw; its catalog entry's `sessionName` says how stable its source is.
+   */
+  sessionName?(rec: AgentRecord, env?: NodeJS.ProcessEnv): string | null;
   /** Where permission prompts surface (Q-AG-2). */
   approvals?: "terminal" | "hook";
   /**

package/src/shared/agents/session-name.ts

@@ -0,0 +1,110 @@
+/**
+ * An agent's session name (AG-4b): what its pane header adds after
+ * `{workspace} · {runtime}`, and what its tab, the Agents list and ⌘K show.
+ *
+ * Two sources, and the most recent rename wins:
+ *
+ *   - Den's own: a person double-clicked its tab (the record's displayName,
+ *     made at displayNameAt). Every runtime has it.
+ *   - The runtime's, when its adapter has `sessionName` (Runtime, AG-4b):
+ *     Claude Code's `/rename`. Its time is when Den first saw it, kept in
+ *     the agent's files dir (session-name.json, with the conversation's
+ *     token: Start fresh forgets it). An adapter that fails or throws is no
+ *     name; it never breaks the list.
+ *
+ * Den never writes a name back into the runtime.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { agentFilesDir, writePrivate, type AgentRecord } from "./records.js";
+import { getRuntime } from "./runtimes.js";
+import { cleanName } from "./transcript-follow.js";
+
+export {
+  FOLLOW_MAX_BYTES,
+  followState,
+  oscTitles,
+  resetFollowers,
+  transcriptTitle,
+} from "./transcript-follow.js";
+
+interface Seen {
+  token: string | null;
+  name: string;
+  /** When Den first saw it (ms). */
+  at: number;
+}
+
+const seenFile = (stateDir: string, id: string) =>
+  path.join(agentFilesDir(stateDir, id), "session-name.json");
+
+function readSeen(file: string): Seen | null {
+  try {
+    const v = JSON.parse(fs.readFileSync(file, "utf-8")) as Partial<Seen>;
+    if (typeof v.name !== "string" || typeof v.at !== "number") return null;
+    return {
+      token: typeof v.token === "string" ? v.token : null,
+      name: v.name,
+      at: v.at,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** The runtime's name for the agent's conversation, with when it was first seen. */
+function runtimeName(
+  rec: AgentRecord,
+  stateDir: string,
+  env: NodeJS.ProcessEnv,
+  now: () => number,
+): Seen | null {
+  const rt = getRuntime(rec.runtime);
+  if (!rt?.sessionName) return null;
+  const token = rec.resumeToken ?? null;
+  const file = seenFile(stateDir, rec.id);
+  let seen = readSeen(file);
+  if (seen && seen.token !== token) seen = null;
+  let name: string | null = null;
+  try {
+    name = cleanName(rt.sessionName(rec, env));
+  } catch {
+    name = null;
+  }
+  // null: nothing new (not caught up, not found); the last name stays.
+  if (name && name !== seen?.name) {
+    seen = { token, name, at: now() };
+    try {
+      writePrivate(file, JSON.stringify(seen) + "\n");
+    } catch {
+      /* shown, not kept: it is seen again next time */
+    }
+  }
+  return seen;
+}
+
+/**
+ * The agent's session name: the latest of Den's rename and the runtime's,
+ * or undefined when neither has one. Never throws.
+ */
+export function agentSessionName(
+  rec: AgentRecord,
+  stateDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+  now: () => number = Date.now,
+): string | undefined {
+  let rt: Seen | null = null;
+  try {
+    rt = runtimeName(rec, stateDir, env, now);
+  } catch {
+    rt = null;
+  }
+  const den = rec.displayName
+    ? {
+        name: rec.displayName,
+        at: Date.parse(rec.displayNameAt ?? rec.startedAt) || 0,
+      }
+    : null;
+  if (den && rt) return rt.at > den.at ? rt.name : den.name;
+  return (den ?? rt)?.name;
+}