@monster-orange/den 0.4.11 → 0.4.13

package/CHANGELOG.md

@@ -4,6 +4,175 @@ 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.13] - 2026-11-07
+
+### Added
+
+- **The Start dialog.** + Start agent opens the dialog from the Den Shell
+  design. Pick a persona from a list you can search, with category and
+  source chips (built-in, distribution, mine); with no filter it is grouped
+  by category, and Plain session (your shell in the workspace, no agent) is
+  pinned last. Each persona shows its one-line description. "What's a
+  persona?" explains the idea, and Details shows the instructions, runtime,
+  model and version, permission mode and allowed commands. Then Runtime,
+  Workspace, an optional first instruction, and a collapsed Advanced
+  section: Model and Version, Permission mode, and Extra allowed commands,
+  with a preview of exactly what the runtime will be given.
+- **First instruction.** Den types it into the agent's session once the
+  session is ready, as a bracketed paste when the runtime asks for one,
+  then Enter. It never goes on the command line and is never stored; the
+  audit log records its length only.
+- **Your own personas.** + New persona, Duplicate and Edit write personas
+  of your own to `<state_dir>/personas/<id>.md` (0600). Settings ›
+  Personas lists every persona with the same search and chips: View or
+  Edit, Duplicate, Delete (your own only), + New persona. Built-in and
+  distribution personas are read-only; Duplicate makes your own copy.
+  Routes: `GET /api/personas/<id>`, `POST /api/personas`, `POST` and
+  `DELETE /api/personas/<id>`.
+- **Models and versions.** A runtime lists its models (den-claude: opus,
+  sonnet and haiku, each "latest" or a pinned version, from a catalog
+  shipped with Den). A pinned version runs as `--model <full id>`. A
+  persona or session pinned to an older version says "newer available";
+  your own persona has Use latest.
+- **Permissions as intent.** Ask for everything, Auto-approve edits in the
+  worktree, or Auto-approve all, plus extra allowed commands as plain
+  prefixes. den-claude turns them into `--permission-mode` and
+  `Bash(<prefix>)` / `Bash(<prefix> *)` allow rules beside Den's deny
+  rules. Other runtimes take none from Den yet, and the dialog says "not
+  supported on <runtime>" rather than dropping one.
+- **Override tags.** A session started with choices that differ from its
+  persona is tagged in the list: "model: haiku", "pinned <version>",
+  "auto-approve edits", "custom tools", the runtime. "auto-approve all" is
+  always tagged. Start fresh and Relaunch keep the choices.
+- **Roles and categories.** Den's roles are planner, orchestrator, sde,
+  reviewer, tester and designer. Each is a template (instructions,
+  permission mode, a read-only command preset) that fills in New persona
+  without overwriting what you typed, and it adds nothing hidden to a
+  prompt. A distribution adds roles and categories (`agents.roles`,
+  `agents.categories`) and may extend a Den role's preset, never redefine
+  it.
+- **Plain session from the page.** `POST /api/workspaces/<ws>/sessions`
+  starts your login shell in the workspace's folder (capped by
+  `sessions.max_concurrent`).
+- **A tester persona** in Den's default pack.
+
+### Changed
+
+- `POST /api/workspaces/<ws>/agents` takes `version`, `permission`,
+  `allow` and `instruction`, and refuses an unknown field. Each is checked
+  against the runtime's catalog: a model or version it doesn't list, a
+  mode other than `ask`, `edits` or `all`, or a command that isn't a plain
+  prefix (at most 32, 120 characters each) is a 400. An agent's token gets
+  403 on every persona route and on a plain session.
+- The agent record keeps `version`, `permission`, `allow` and `overrides`.
+- A persona's `role` is a role key; a sentence there still reads as its
+  description. Personas gain `display_name`, `category`, `version` and
+  `allowed_commands`. `permission_mode` takes `ask`, `edits` or `all`
+  (Claude Code's own modes still read). `agents personas` shows SOURCE and
+  ROLE columns.
+- fe-dev, be-dev and devops are role `sde`; ux-designer is role
+  `designer` in category Design.
+- A persona whose runtime isn't installed starts on the first one that is,
+  and the Start dialog says so.
+- **`sessionTitle` is the name a session shows.** `agents list --json`,
+  `GET /api/sessions` and the start and resume answers (MCP
+  `agent_resume`) now carry the resolved name (Den's rename or the
+  runtime's, the later) as `sessionTitle`. 0.4.12 called it `sessionName`,
+  which is the agent record's session handle (`<dist>-<ws>:<id>`) and has
+  been since 0.4.0. Records are unchanged.
+
+### Fixed
+
+- **Settings shows a saved choice at once.** Agents tab layout and Open
+  file links in saved, but the pressed button stayed on the old value
+  until a reload. The page now takes every setting the save returns.
+- **Claude Code's `/rename "x"` shows as x.** Its title keeps the quotes;
+  Den drops one pair around the whole name, for display only.
+- **The terminal fit check is exact again.** The browser test compares
+  what is left below and beside a terminal with the cell size xterm drew
+  with (now on each pane as `data-cell-w` and `data-cell-h`), less than
+  one cell, so a missed row fails on any font.
+
+### Migrations
+
+- None required. A persona whose `role:` is a sentence keeps working (it
+  becomes the description); set `role:` to a role key to give it one.
+- A persona pack may now set `display_name`, `category`, `version` and
+  `allowed_commands`. Use `permission_mode: ask | edits | all` for a mode
+  every runtime can translate.
+- `agents.roles` and `agents.categories` are new keys of `agents:` in the
+  distribution's config (see docs/distributions.md, Personas).
+- Read `sessionTitle`, not `sessionName`, for the name a session shows in
+  `agents list --json`, `GET /api/sessions` and the start and resume
+  answers. No record needs changing.
+
+## [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

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.11/hero-dark.png">
-  <img src="docs/images/0.4.11/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.13/hero-dark.png">
+  <img src="docs/images/0.4.13/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.11/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.13/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.11/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.11/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.11/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.11/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.13/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.13/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.13/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.13/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

@@ -2054,10 +2054,25 @@ server scoped to its workspace.
   unique in the distribution, so a second workspace's planner gets
   `planner-<ws>` unless you give `--id`.
 - The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
-  persona, runtime, model, workspace, cwd, session and times. It never holds
-  the environment or the command line. `list` reads it for persona, runtime
+  persona, runtime, model, workspace, cwd, session and times, and what it was
+  started with from the Start dialog: `version` (the model's, "latest" or
+  pinned), `permission` (`ask`, `edits` or `all`), `allow` (extra allowed
+  commands) and `overrides` (which of these differ from its persona). Start
+  fresh and Relaunch keep them. It never holds the environment, the command
+  line or a first instruction. `list` reads it for persona, runtime
   and model; a record whose session has gone is listed as `stopped` (after
   `stop`) or `ended`.
+- **Two name fields.** In the record, `sessionName` is the session's
+  handle, `<dist>-<ws>:<id>` (what `sessions attach` takes); it has meant
+  that since 0.4.0, and `displayName` is the name a person gave the agent.
+  In `agents list --json`, `GET /api/sessions` and the start and resume
+  answers (MCP `agent_resume`), `sessionTitle` is the name its session
+  shows: the latest of Den's rename and the runtime's own (Claude Code's
+  `/rename`, one pair of surrounding quotes dropped), absent when there is
+  none. The handle there is `name` (`/api/sessions`) or `session` (the
+  start and resume answers). 0.4.12 sent the name shown as `sessionName`;
+  read `sessionTitle` instead. Records are unchanged, so none written
+  before needs migrating.
 - `list` shows agents only: sessions with an agent record. A session from
   `sessions start` is not an agent; `sessions list` shows it.
 - `stop` sends its session TERM and marks it stopped. `resume` works only
@@ -2104,13 +2119,78 @@ started. The workspace header counts them ("2 agents").
   workspace, and **Open** on a row with a session opens its terminal there.
 
 The routes: `GET /api/workspaces/<ws>/agents`, `POST
-/api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, id? }`), `POST
-/api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, and `GET
-/api/personas` (personas and runtimes). Errors are the usual
+/api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, version?,
+permission?, allow?, instruction?, id? }`, see
+[The Start dialog](#the-start-dialog)), `POST
+/api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, `POST
+/api/workspaces/<ws>/sessions` (a plain session), `GET /api/personas`
+(personas, runtimes with their models and permission translation, roles
+and categories), and the persona routes under
+[Personas](#personas). Errors are the usual
 `{ ok: false, error, code, requestId }`: `cap` (429),
 `conflict` (409, e.g. already running, or no resume), `not_found` (404),
 `exited_at_once` (502, with the session's last lines).
 
+### The Start dialog
+
+**+ Start agent** on the Agents tab (or `/agents?start=1`) opens the Start
+dialog:
+
+- **Persona**: a list you can search (name, role, description), with
+  category chips (only the categories that have personas) and source chips
+  (built-in, distribution, mine). With no filter set it is grouped by
+  category. Each row is the persona's name ("Rita (reviewer)", else its
+  id), its source badge and its one-line description, and "not installed"
+  when its runtime isn't. **Plain session** is pinned last: your login
+  shell in the workspace's folder, no agent. **What's a persona?** explains
+  the idea; **Details** shows the selected persona's instructions, runtime,
+  model and version, permission mode, role preset and extra commands.
+  **+ New persona**, **Duplicate** and (for your own) **Edit** open the
+  persona editor, and the dialog picks what you saved.
+- **Runtime** and **Workspace**. Installed runtimes come first; the rest
+  are listed, disabled, and named under the field ("Not found on this
+  machine: …"). A persona whose runtime isn't installed starts on the first
+  one that is, and the dialog says so. The line under the runtime says what
+  will run (see below).
+- **First instruction** (optional, up to 8000 characters): the agent's
+  first message. Den types it into the agent's session once the session is
+  ready (it has printed and gone quiet, or after 30 s), through the session
+  host, as a bracketed paste when the runtime asked for one, then Enter. It
+  is never a command-line argument and never stored; the audit log records
+  its length only.
+- **Advanced** (collapsed): **Model** and **Version** (the runtime's own
+  list; "Persona default" first), the **Permission mode** (Ask for
+  everything, Auto-approve edits in the worktree, Auto-approve all), the
+  role's command preset as chips, **Extra allowed commands** (plain command
+  prefixes, one per line, no patterns), and a preview of exactly what the
+  runtime will be given. A command a runtime can't take says "not supported
+  on <runtime>", and a pattern says "use a plain prefix"; neither is ever
+  dropped silently. "Edit raw runtime config…" is not there yet.
+
+What you change in Advanced applies to that launch only, and the session's
+row is tagged: "model: haiku", "pinned claude-opus-4-8", "auto-approve
+edits", "custom tools", the runtime, and always "auto-approve all" for an
+agent started so. An agent pinned to an older version says "newer
+available".
+
+Every field is checked on the server, not only in the page. The model and
+version must be ones the runtime lists, the permission one of `ask`,
+`edits` or `all`, and `allow` a list of at most 32 plain prefixes (letters,
+digits, single spaces and `. _ / : = @ % + , -`, at most 120 characters
+each). An unknown field is refused. A person's start only: an agent's
+token gets 403.
+
+**How each runtime takes the choices.** den-claude (Claude Code): a model is
+`--model <alias>` (`opus`, `sonnet`, `haiku`), a pinned version is `--model
+<full id>`. The model list is a catalog shipped with each Den release,
+because `claude` can't list its models. The permission mode is
+`--permission-mode` (`default`, `acceptEdits`, `bypassPermissions`), and
+each command prefix becomes two allow rules, `Bash(<prefix>)` and
+`Bash(<prefix> *)`, in the agent's settings file beside Den's deny rules
+(deny wins). Codex CLI, Gemini CLI, Grok Build and generic take no model,
+mode or commands from Den yet: the dialog says "not supported on <runtime>"
+and the start is refused if you set one.
+
 ### The Agents tab
 
 "Agents" in the rail (Develop, after Graph) is `/agents`: every session and
@@ -2132,15 +2212,78 @@ 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 `sessionTitle`
+  (0.4.12: `sessionName`, which is the record's session handle). A
+  `/rename "api spike"` shows as api spike: one pair of quotes around the
+  whole name is dropped, for display only.
+  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
@@ -2326,13 +2469,18 @@ a Claude Code agent file, read as it is, plus a few keys of Den's own:
 ```markdown
 ---
 name: planner # the id (or `id:`; default: the file name)
-description: Writes stories and their acceptance criteria. # or `role:`
+display_name: Rita # optional; shown as "Rita (reviewer)"
+role: planner # a role (see Roles); a sentence here is the description
+category: engineering # see Categories; default: the role's
+description: Writes stories and their acceptance criteria. # one line
 model: some-model # optional; `inherit` means none
+version: latest # or a pinned version of the model
+allowed_commands: [npm test] # extra plain prefixes allowed without asking
 tools: Read, Grep # hints for the runtime; Den restricts nothing with them
 standing: true # starts with its workspace (later slices)
 context: [docs/specs, the design system] # what to read first
 runtime: generic # default den-claude
-permission_mode: plan # den-claude only; default `default`
+permission_mode: ask # ask, edits or all (Claude Code's own modes still read)
 den_hooks: false # Den's guardrail hooks for this persona (see Guardrails)
 den_instructions: false # Den's shared instructions for this persona
 argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
@@ -2342,8 +2490,9 @@ You are the planner. …
 ```
 
 Den ships a default pack: `planner` and `orchestrator` (standing), `fe-dev`,
-`be-dev`, `devops`, `reviewer` and `ux-designer`. Add your own packs, read in
-order after Den's; a persona with the same id replaces the earlier one:
+`be-dev` and `devops` (role `sde`), `reviewer`, `tester` and `ux-designer`
+(role `designer`, category Design). Add your own packs, read in order after
+Den's; a persona with the same id replaces the earlier one:
 
 ```yaml
 agents:
@@ -2356,6 +2505,53 @@ used without converting them. Files without front matter (a README) are
 skipped; two files with one id in a pack, or a pack that isn't a directory,
 are errors naming the file or the key.
 
+**Your own personas** live in `<stateDir>/personas/<id>.md` (0600), in the
+same format, read last: one wins over a pack's persona of the same id.
+Settings › Personas lists every persona with the Start dialog's search and
+chips: **View** (or **Edit** for your own), **Duplicate**, **Delete** (your
+own only) and **+ New persona**. A built-in or distribution persona is
+read-only; Duplicate makes your own copy to edit. "newer available" marks a
+persona pinned to an older version, with **Use latest** for your own. The
+routes: `GET /api/personas/<id>` (with its instructions), `POST
+/api/personas` (new), `POST /api/personas/<id>` (edit; 409 `read_only` for
+one that isn't yours) and `DELETE /api/personas/<id>`. Each field is
+checked: the role, category, runtime, model and version must be registered,
+the description one line of at most 200 characters, the name at most 40,
+the instructions at most 20000 characters with no control characters but
+newlines and tabs. An agent's token can't create, change or delete a
+persona (403); a person sets what agents may do.
+
+**Roles.** A role is a template and a key: default instructions, a
+permission mode and a command preset (read-only commands, allowed without
+asking). Den's roles are `planner`, `orchestrator`, `sde`, `reviewer`,
+`tester` and `designer`. Picking a role in New persona fills the form in,
+never over text you typed; a role adds nothing hidden to an agent's prompt.
+A distribution adds roles, and may extend a Den role's preset but not
+redefine it:
+
+```yaml
+agents:
+  roles:
+    copywriter:
+      description: Drafts release notes and site copy.
+      instructions: Draft copy in the house voice. Leave drafts for review.
+      mode: ask # ask, edits or all
+      preset: [vale]
+      category: marketing
+    reviewer:
+      preset: [semgrep] # added to Den's preset
+```
+
+**Categories** group personas in the Start list and Settings › Personas.
+Den's are Engineering, Design, Product, Marketing and Operations; a
+distribution adds more:
+
+```yaml
+agents:
+  categories:
+    - { id: legal, label: Legal }
+```
+
 ### Guardrails: hooks, shared instructions, hand-backs
 
 Every persona in Den's default pack gets two things with no setup: Den's
@@ -2626,6 +2822,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.11",
+  "version": "0.4.13",
   "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,
   };
 }