@monster-orange/den 0.4.11 → 0.4.12

package/src/shared/agents/transcript-follow.ts

@@ -0,0 +1,180 @@
+/**
+ * Reading a session's name from what a runtime writes (AG-4b), without
+ * ever reading a whole file at once:
+ *
+ *   - transcriptTitle(file): the latest `{"type":"custom-title",
+ *     "customTitle":…}` record in a JSON-lines transcript (Claude Code's
+ *     `/rename`). Each ask reads on from where the last one stopped, at
+ *     most FOLLOW_MAX_BYTES, so a long transcript is caught up over a few
+ *     asks; a file that got shorter is read again from the start. Only
+ *     lines that mention "custom-title" are parsed. Any failure is null.
+ *   - oscTitles(chunk, carry): the terminal titles (OSC 0 and OSC 2) in a
+ *     PTY's output, for runtimes the catalog marks `titleFromOsc`.
+ *
+ * A name is cleaned for the page: control, format and line-separator
+ * characters go, spaces are squeezed, and it is cut at MAX_NAME.
+ */
+import * as fs from "fs";
+
+/** The most one ask reads of a transcript. */
+export const FOLLOW_MAX_BYTES = 1024 * 1024;
+const CHUNK = 64 * 1024;
+/** A line longer than this is no title record: skipped to its end. */
+const MAX_LINE = 64 * 1024;
+/** The longest name kept. */
+export const MAX_NAME = 80;
+/** The most files followed at once (the oldest is forgotten first). */
+const MAX_FOLLOWED = 256;
+
+interface Follow {
+  offset: number;
+  title: string | null;
+  /** The start of a line whose newline hasn't come yet. */
+  rest: Buffer;
+  /** Inside a line too long to be a title: drop bytes to its newline. */
+  skipping: boolean;
+}
+
+const followers = new Map<string, Follow>();
+
+/** A name as the page may show it, or null when nothing is left. */
+export function cleanName(v: unknown): string | null {
+  if (typeof v !== "string") return null;
+  const s = v
+    .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!s) return null;
+  return [...s].slice(0, MAX_NAME).join("").trim() || null;
+}
+
+function titleOf(line: Buffer): string | null | undefined {
+  if (!line.includes("custom-title")) return undefined;
+  try {
+    const rec = JSON.parse(line.toString("utf-8")) as {
+      type?: unknown;
+      customTitle?: unknown;
+    };
+    if (rec?.type !== "custom-title") return undefined;
+    return cleanName(rec.customTitle) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The latest custom-title in `file` (read on from the last ask), or null. */
+export function transcriptTitle(file: string): string | null {
+  let fd: number | undefined;
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile()) {
+      followers.delete(file);
+      return null;
+    }
+    let f = followers.get(file);
+    if (!f || st.size < f.offset) {
+      f = { offset: 0, title: null, rest: Buffer.alloc(0), skipping: false };
+      followers.delete(file);
+      if (followers.size >= MAX_FOLLOWED)
+        followers.delete(followers.keys().next().value as string);
+      followers.set(file, f);
+    }
+    if (st.size === f.offset) return f.title;
+    fd = fs.openSync(file, "r");
+    const end = Math.min(st.size, f.offset + FOLLOW_MAX_BYTES);
+    const buf = Buffer.alloc(CHUNK);
+    while (f.offset < end) {
+      const n = fs.readSync(
+        fd,
+        buf,
+        0,
+        Math.min(CHUNK, end - f.offset),
+        f.offset,
+      );
+      if (n <= 0) break;
+      f.offset += n;
+      let data = buf.subarray(0, n);
+      for (;;) {
+        const nl = data.indexOf(0x0a);
+        if (nl < 0) {
+          if (!f.skipping) {
+            f.rest = Buffer.concat([f.rest, data]);
+            if (f.rest.length > MAX_LINE) {
+              f.rest = Buffer.alloc(0);
+              f.skipping = true;
+            }
+          }
+          break;
+        }
+        const piece = data.subarray(0, nl);
+        data = data.subarray(nl + 1);
+        if (f.skipping) {
+          f.skipping = false;
+          continue;
+        }
+        const line = f.rest.length ? Buffer.concat([f.rest, piece]) : piece;
+        f.rest = Buffer.alloc(0);
+        const t = titleOf(line);
+        if (t) f.title = t;
+      }
+    }
+    return f.title;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined)
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* closed */
+      }
+  }
+}
+
+/** Where a followed file is up to (tests). */
+export function followState(file: string): { offset: number } | undefined {
+  const f = followers.get(file);
+  return f ? { offset: f.offset } : undefined;
+}
+
+/** Forget every followed file (tests). */
+export function resetFollowers(): void {
+  followers.clear();
+}
+
+/** The most of an unended OSC kept between chunks. */
+const MAX_CARRY = 1024;
+const OSC_START = "\u001b]";
+
+/**
+ * The terminal titles (OSC 0 and OSC 2, ended by BEL or ST) in `chunk`,
+ * with `carry` the unended OSC the last chunk left; returns what this one
+ * leaves. Every other OSC (a link, the cwd) is not a title.
+ */
+export function oscTitles(
+  chunk: string,
+  carry: string,
+): { titles: string[]; carry: string } {
+  const s = carry + chunk;
+  const titles: string[] = [];
+  let i = 0;
+  for (;;) {
+    const at = s.indexOf(OSC_START, i);
+    if (at < 0) {
+      // A lone ESC at the very end may start an OSC in the next chunk.
+      return { titles, carry: s.endsWith("\u001b") ? "\u001b" : "" };
+    }
+    const bel = s.indexOf("\u0007", at + 2);
+    const st = s.indexOf("\u001b\\", at + 2);
+    const ends = [bel, st].filter((x) => x >= 0);
+    if (!ends.length) return { titles, carry: s.slice(at, at + MAX_CARRY) };
+    const stop = Math.min(...ends);
+    const body = s.slice(at + 2, stop);
+    const m = /^([02]);([\s\S]*)$/.exec(body);
+    if (m) {
+      const t = cleanName(m[2]);
+      if (t) titles.push(t);
+    }
+    i = stop + (stop === bel ? 1 : 2);
+  }
+}

package/src/shared/den-config.ts

@@ -339,6 +339,11 @@ export interface UserConfig {
    * editor instead of the default.
    */
   editor_overrides?: Record<string, string>;
+  /**
+   * Where a file path in an agent's pane opens (AG-4b): vscode, cursor or
+   * zed by URL scheme, or none (copy the path). editor-open-pref.ts.
+   */
+  editor_open?: string;
   /**
    * Personal override of the team release config (config/den.yml `release:`).
    * Wave-assignment edits made in the Release tab are saved here so they stay
@@ -397,6 +402,8 @@ export interface UserConfig {
      * (the default), 1d or 7d. Interrupted agents are never forgotten.
      */
     remove_stopped_after?: unknown;
+    /** AG-4b: the Agents tab's layout (src/ui/server/agents-layout-pref.ts). */
+    layout?: unknown;
   };
   /**
    * The web server's per-machine keys (src/shared/web-session.ts

package/src/ui/cli/agent-ops.ts

@@ -71,6 +71,7 @@ import {
   type CatalogEntry,
 } from "../../shared/agents/catalog.js";
 import { checkRuntimeBin } from "../../shared/agents/catalog-runtime.js";
+import { agentSessionName } from "../../shared/agents/session-name.js";
 import { cliEntrypoint } from "../../shared/engine.js";
 import { getDistRoot } from "../../shared/paths.js";
 import { envKey } from "../../shared/product.js";
@@ -89,6 +90,7 @@ import {
   removeRecord,
   restoreRecord,
   writeRecord,
+  checkDisplayName,
   writeRuntimeFiles,
   type AgentRecord,
 } from "../../shared/agents/records.js";
@@ -355,6 +357,13 @@ export function agentMcp(
  */
 export interface AgentRow {
   agent: string;
+  /** The name a person gave it (AG-4b), when one did. */
+  displayName?: string;
+  /**
+   * Its session's name (AG-4b): the latest of Den's rename and the
+   * runtime's own (Claude Code's /rename), when there is one.
+   */
+  sessionName?: string;
   persona?: string;
   runtime?: string;
   model?: string;
@@ -460,9 +469,11 @@ export function agentRows(
       isStoppedState(st) && !resumable
         ? (resumeRefusal(rec) ?? (rot?.ready ? rotatedRefusal(rec, rot) : null))
         : null;
+    const named = stateDir ? agentSessionName(rec, stateDir) : undefined;
     return {
       agent: rec.id,
       ...recordFields(rec),
+      ...(named ? { sessionName: named } : {}),
       state: st,
       startedAt: s?.startedAt ?? rec.startedAt,
       resumable,
@@ -489,6 +500,7 @@ export function agentRows(
 
 function recordFields(rec: AgentRecord): Partial<AgentRow> {
   return {
+    ...(rec.displayName ? { displayName: rec.displayName } : {}),
     persona: rec.persona,
     runtime: rec.runtime,
     ...(rec.model ? { model: rec.model } : {}),
@@ -1171,6 +1183,12 @@ export async function startAgent(
           workspace: ws,
           cwd: input.worktree,
           sessionName: sessionName(d.dist, ws, id),
+          // AG-4b: a name given to the agent is the agent's, not its
+          // conversation's: Start fresh and Relaunch keep it.
+          ...(prev?.displayName ? { displayName: prev.displayName } : {}),
+          ...(prev?.displayName && prev.displayNameAt
+            ? { displayNameAt: prev.displayNameAt }
+            : {}),
           // 0.4.8: launched on this token, so a resume continues it.
           ...(out.resumeToken
             ? { resumeToken: out.resumeToken, launched: true }
@@ -1212,6 +1230,37 @@ export function agentRecord(
   return rec;
 }
 
+/**
+ * Name agent `id` (AG-4b: a person double-clicked its tab): `name` as
+ * checkDisplayName takes it; null or blank clears it. The id never
+ * changes. A usage error (400) when the name isn't one.
+ */
+export function renameAgent(
+  d: AgentsResolved,
+  id: string,
+  ws: string,
+  name: unknown,
+): AgentRecord {
+  const rec = agentRecord(d, id, ws);
+  let checked: string | null;
+  try {
+    checked = checkDisplayName(name);
+  } catch (e) {
+    throw usage((e as Error).message);
+  }
+  const next: AgentRecord = { ...rec };
+  if (checked) {
+    next.displayName = checked;
+    // AG-4b: the latest rename wins, Den's or the runtime's.
+    next.displayNameAt = new Date().toISOString();
+  } else {
+    delete next.displayName;
+    delete next.displayNameAt;
+  }
+  writeRecord(d.stateDir(), next);
+  return next;
+}
+
 export interface Stopped {
   rec: AgentRecord;
   /** The session it sent TERM to; undefined when it wasn't running. */

package/src/ui/server/agent-paths.ts

@@ -0,0 +1,52 @@
+/**
+ * Which file paths an agent printed are links (AG-4b): GET
+ * /api/workspaces/<ws>/agents/<id>/paths?p=<path>&p=<path>… answers
+ * { paths: { <path as given>: <absolute path> | null } }.
+ *
+ * A path is resolved against the agent's cwd (an absolute one stays), and
+ * is a link only when it exists and its real path (symlinks followed) is
+ * inside the agent's workspace: the workspace's directory, or the agent's
+ * own cwd (a worktree of it). Anything else is null, so a path outside
+ * the workspace is never a link and the page never learns whether it
+ * exists. Only stat is used: nothing is read, nothing is opened.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+/** The most paths one ask takes (a screen's worth). */
+export const MAX_PATHS = 64;
+/** The longest path taken. */
+const MAX_PATH_LEN = 1024;
+
+function realOrNull(p: string): string | null {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+const inside = (p: string, root: string) =>
+  p === root || p.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+
+/** Each path's absolute path when it is a link, else null. */
+export function agentPathLinks(
+  given: readonly string[],
+  cwd: string,
+  roots: readonly string[],
+): Record<string, string | null> {
+  const real = roots
+    .map((r) => realOrNull(r))
+    .filter((r): r is string => r !== null);
+  const base = realOrNull(cwd) ?? path.resolve(cwd);
+  const out: Record<string, string | null> = {};
+  for (const p of given) {
+    if (Object.hasOwn(out, p)) continue;
+    out[p] = null;
+    if (!p || p.length > MAX_PATH_LEN || p.includes("\0")) continue;
+    const abs = path.resolve(base, p);
+    const r = realOrNull(abs);
+    if (r && real.some((root) => inside(r, root))) out[p] = r;
+  }
+  return out;
+}

package/src/ui/server/agent-routes.ts

@@ -23,6 +23,14 @@
  *                                                 first prompt is its
  *                                                 handoff.md; a resume of
  *                                                 one is refused (409 rotated)
+ *   POST /api/workspaces/<ws>/agents/<id>/name    { name: string | null }: the
+ *                                                 name its tab and the lists
+ *                                                 show (AG-4b); the id never
+ *                                                 changes; null or "" clears
+ *   GET  /api/workspaces/<ws>/agents/<id>/paths?p=…  which printed paths are
+ *                                                 links (AG-4b): inside its
+ *                                                 workspace and there (stat
+ *                                                 only; agent-paths.ts)
  *   POST /api/workspaces/<ws>/agents/<id>/remove  forget a stopped one (Undo:
  *                                                 /api/agents/restore)
  *   POST /api/agents/clear-stopped                { workspaces: [...] }: forget
@@ -74,6 +82,7 @@ import {
   NOT_IN_WORKSPACE,
   pruneStopped,
   removeAgent,
+  renameAgent,
   removeStopped,
   restoreAgents,
   resumeInterrupted,
@@ -88,7 +97,9 @@ import {
   type AgentsResolved,
   type Started,
 } from "../cli/agent-ops.js";
+import { agentSessionName } from "../../shared/agents/session-name.js";
 import { recordAction } from "./audit.js";
+import { agentPathLinks, MAX_PATHS } from "./agent-paths.js";
 import {
   agentPrincipalOf,
   auditActorOf,
@@ -104,7 +115,7 @@ export interface AgentRouteDeps {
 }
 
 const AGENTS_PATH =
-  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove))?$/;
+  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths))?$/;
 
 const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
 /** A start's body is a few short names. */
@@ -163,10 +174,19 @@ function sendError(res: http.ServerResponse, e: unknown, ws?: string): void {
   throw e;
 }
 
+function sessionNameOf(
+  rec: Started["rec"],
+  d: AgentsResolved,
+): { sessionName?: string } {
+  const n = agentSessionName(rec, d.stateDir());
+  return n ? { sessionName: n } : {};
+}
+
 /** A started or resumed agent's answer: its record, or its early exit. */
 function sendStarted(
   res: http.ServerResponse,
   s: Started & { fresh?: boolean },
+  d: AgentsResolved,
 ): void {
   if (s.early) {
     const code =
@@ -197,6 +217,10 @@ function sendStarted(
       // The host's id: the Agents tab opens its pane by it (?open=<id>).
       sessionId: s.info.ref.id,
       startedAt: s.rec.startedAt,
+      ...(s.rec.displayName ? { displayName: s.rec.displayName } : {}),
+      // AG-4b: its session's name (Den's rename or the runtime's), as the
+      // lists show it (MCP agent_resume answers with this).
+      ...sessionNameOf(s.rec, d),
     },
     // A resume with nothing to continue yet started fresh (same id).
     ...(s.fresh ? { fresh: true } : {}),
@@ -294,6 +318,8 @@ export async function handleAgentRoutes(
     | "fresh"
     | "relaunch"
     | "remove"
+    | "name"
+    | "paths"
     | undefined;
 
   if (!action && method === "GET") {
@@ -313,6 +339,38 @@ export async function handleAgentRoutes(
     }
     return true;
   }
+  // AG-4b: which paths an agent printed are links (read-only: stat only).
+  if (action === "paths") {
+    if (method !== "GET" && method !== "HEAD")
+      return methodNotAllowed(res, "GET");
+    try {
+      const rec = agentRecord(d, id!, ws);
+      const given = new URL(
+        req.url ?? "/",
+        "http://localhost",
+      ).searchParams.getAll("p");
+      if (given.length > MAX_PATHS)
+        throw new AgentError(`at most ${MAX_PATHS} paths at once`, {
+          usage: true,
+        });
+      let wsDir: string | null = null;
+      try {
+        wsDir = d.workspaceDir(ws);
+      } catch {
+        wsDir = null;
+      }
+      sendJson(res, {
+        paths: agentPathLinks(
+          given,
+          rec.cwd,
+          [wsDir, rec.cwd].filter((x): x is string => !!x),
+        ),
+      });
+    } catch (e) {
+      sendError(res, e, ws);
+    }
+    return true;
+  }
   if (method !== "POST")
     return methodNotAllowed(res, action ? "POST" : "GET, POST");
 
@@ -354,7 +412,7 @@ export async function handleAgentRoutes(
       });
       what = `start ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
     } else if (verb === "stop") {
       // The answer comes once the session has ended (200, stopped: true),
       // or, still running after the wait, 202 with stillStopping: true.
@@ -375,12 +433,25 @@ export async function handleAgentRoutes(
       const s = await startFresh(d, id!, ws);
       what = `start ${s.rec.id} fresh (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
     } else if (verb === "relaunch") {
       const s = await relaunchAgent(d, id!, ws);
       what = `relaunch ${s.rec.id} from its handoff (${s.why}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
+    } else if (verb === "name") {
+      const body = await jsonBody(req);
+      if (!("name" in body))
+        throw new AgentError("name is required (null clears it)", {
+          usage: true,
+        });
+      const rec = renameAgent(d, id!, ws, body.name);
+      audit(what);
+      sendJson(res, {
+        ok: true,
+        agent: rec.id,
+        ...(rec.displayName ? { displayName: rec.displayName } : {}),
+      });
     } else if (verb === "remove") {
       const removed = await removeAgent(d, id!, ws);
       audit(what);
@@ -388,7 +459,7 @@ export async function handleAgentRoutes(
     } else {
       const s = await resumeAgent(d, id!, ws);
       audit(what);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
     }
   } catch (e) {
     audit(what, e instanceof Error ? e.message : String(e));

package/src/ui/server/agents-layout-pref.ts

@@ -0,0 +1,43 @@
+/**
+ * The Agents tab's layout (AG-4b), a person's view preference: Focus (one
+ * pane, the default), Tabs or Tile. Stored in the user config as
+ * `agents.layout` and served by /api/settings as `agents_layout`, like the
+ * other view prefs (graph-prefs.ts, shell-prefs.ts). It changes no session
+ * and no agent: only how the page lays out their terminals.
+ */
+import type { UserConfig } from "../../shared/den-config.js";
+
+export const AGENTS_LAYOUTS = ["focus", "tabs", "tile"] as const;
+export type AgentsLayout = (typeof AGENTS_LAYOUTS)[number];
+export const AGENTS_LAYOUT_DEFAULT: AgentsLayout = "focus";
+
+const isLayout = (v: unknown): v is AgentsLayout =>
+  typeof v === "string" && (AGENTS_LAYOUTS as readonly string[]).includes(v);
+
+/** The stored layout, or the default when unset or hand-broken. */
+export function agentsLayout(user: UserConfig): AgentsLayout {
+  const v = (user.agents as { layout?: unknown } | undefined)?.layout;
+  return isLayout(v) ? v : AGENTS_LAYOUT_DEFAULT;
+}
+
+/**
+ * Apply a POSTed `agents_layout` to `user` (in place): a layout sets
+ * agents.layout, null clears it (and an agents block left empty goes).
+ * Anything else: the error to answer with.
+ */
+export function patchAgentsLayout(
+  user: UserConfig,
+  v: unknown,
+): { ok: true } | { ok: false; error: string } {
+  if (v !== null && !isLayout(v))
+    return {
+      ok: false,
+      error: `agents_layout must be one of ${AGENTS_LAYOUTS.map((l) => `"${l}"`).join(", ")}, or null`,
+    };
+  const agents = { ...(user.agents ?? {}) } as Record<string, unknown>;
+  if (v === null) delete agents.layout;
+  else agents.layout = v;
+  if (Object.keys(agents).length) user.agents = agents as UserConfig["agents"];
+  else delete user.agents;
+  return { ok: true };
+}

package/src/ui/server/editor-open-pref.ts

@@ -0,0 +1,41 @@
+/**
+ * Where a file path in an agent's pane opens (AG-4b): ⌘-click (Ctrl-click
+ * elsewhere) opens it in this editor by its URL scheme, at the line
+ * (vscode://file/…, cursor://file/…, zed://file/…), or, with `none` (the
+ * default), copies its absolute path. A person's view preference, stored
+ * in the user config as `editor_open` (the `editor` key is already the
+ * repo editor's, ↗) and served by /api/settings as `editor_open`. Nothing
+ * here runs an editor: the browser hands the URL to the OS.
+ */
+import type { UserConfig } from "../../shared/den-config.js";
+
+export const EDITOR_OPENS = ["vscode", "cursor", "zed", "none"] as const;
+export type EditorOpen = (typeof EDITOR_OPENS)[number];
+export const EDITOR_OPEN_DEFAULT: EditorOpen = "none";
+
+const isEditorOpen = (v: unknown): v is EditorOpen =>
+  typeof v === "string" && (EDITOR_OPENS as readonly string[]).includes(v);
+
+/** The stored choice, or none when unset or hand-broken. */
+export function editorOpen(user: UserConfig): EditorOpen {
+  const v = user.editor_open;
+  return isEditorOpen(v) ? v : EDITOR_OPEN_DEFAULT;
+}
+
+/**
+ * Apply a POSTed `editor_open` to `user` (in place): an editor sets it,
+ * null clears it. Anything else: the error to answer with.
+ */
+export function patchEditorOpen(
+  user: UserConfig,
+  v: unknown,
+): { ok: true } | { ok: false; error: string } {
+  if (v !== null && !isEditorOpen(v))
+    return {
+      ok: false,
+      error: `editor_open must be one of ${EDITOR_OPENS.map((e) => `"${e}"`).join(", ")}, or null`,
+    };
+  if (v === null) delete user.editor_open;
+  else user.editor_open = v;
+  return { ok: true };
+}

package/src/ui/server/index.ts

@@ -256,6 +256,8 @@ import {
   sshTarget,
 } from "../../shared/cli-command.js";
 import { graphPrefs, patchStoredGraph } from "./graph-prefs.js";
+import { agentsLayout, patchAgentsLayout } from "./agents-layout-pref.js";
+import { editorOpen, patchEditorOpen } from "./editor-open-pref.js";
 import { graphPageHtml } from "./graph-page.js";
 import { mergeShellPrefs, shellPrefs, storedShell } from "./shell-prefs.js";
 import { distributionSettings, userWebPort } from "./settings-distribution.js";
@@ -4467,6 +4469,10 @@ async function handleRequest(
   //   graph: { direction, group, density, panelWidth } (see graph-prefs.ts)
   //   appearance: { theme: id | null, mode: system|dark|light } (appearance-prefs.ts)
   //   shell: { pins, collapsed, hidden, order, dock, dockHeight } (shell-prefs.ts)
+  //   agents_layout: focus | tabs | tile, the Agents tab's layout (AG-4b,
+  //     agents-layout-pref.ts; user.yml agents.layout); null clears it
+  //   editor_open: vscode | cursor | zed | none, where a path in an agent's
+  //     pane opens (AG-4b, editor-open-pref.ts); null clears it (none)
   //   language: the UI's language, en | ja | es (ui-language.ts); null or
   //     "en" clears it (English is the default)
   // It writes config/local/user.yml only. `distribution` is read-only: what
@@ -4512,6 +4518,8 @@ async function handleRequest(
         graph: graphPrefs(user.graph),
         appearance: appearancePrefs(user.appearance),
         shell: shellPrefs(user.shell),
+        agents_layout: agentsLayout(user),
+        editor_open: editorOpen(user),
         distribution: distributionSettings(getDistRoot()),
         // Set from the command line (`<cli> config`), shown read-only.
         user_web_port: userWebPort(user as Record<string, unknown>),
@@ -4537,8 +4545,20 @@ async function handleRequest(
           shell?: unknown;
           language?: unknown;
           machine_name?: unknown;
+          agents_layout?: unknown;
+          editor_open?: unknown;
         };
         const user = readUserConfig();
+        // AG-4b: the Agents tab's layout, a view preference only.
+        if (body.agents_layout !== undefined) {
+          const l = patchAgentsLayout(user, body.agents_layout);
+          if (!l.ok) return send400(res, l.error);
+        }
+        // AG-4b: where a path link in an agent's pane opens.
+        if (body.editor_open !== undefined) {
+          const e = patchEditorOpen(user, body.editor_open);
+          if (!e.ok) return send400(res, e.error);
+        }
         // SEC-2a: web.machine_name (user.yml); null or "" clears it.
         if (body.machine_name !== undefined) {
           let name: string | null;
@@ -4648,6 +4668,8 @@ async function handleRequest(
           shell: shellPrefs(user.shell),
           language: uiLanguage(user.language),
           machine_name: machineNameSetting(user),
+          agents_layout: agentsLayout(user),
+          editor_open: editorOpen(user),
         });
       } catch (e) {
         return send400(res, `Invalid request: ${(e as Error).message}`);