@monster-orange/den 0.4.21 → 0.4.23

package/CHANGELOG.md

@@ -4,6 +4,121 @@ 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.23] - 2026-11-10
+
+### Added
+
+- **Agents relaunch from their handoff by themselves (D28).** When an
+  agent's rotation is due (after `after_compactions` compactions, or its
+  pull request merged), Den asks it for its handoff at its next idle,
+  never mid-turn, and relaunches it once the handoff passes: a fresh
+  conversation with the same name, persona, workspace and folder. A toast
+  and the audit log say so, and the old conversation is kept. Den asks
+  twice at most, then falls back to asking you.
+- **The rotation callout has buttons, running or stopped**, on the row and
+  in the pane bar: Relaunch now (asking for the handoff first if needed),
+  Write handoff, Keep this conversation (with "Don't ask again for this
+  agent") and Settings. It says what happens next and where the settings
+  come from. Before, a running agent got a message and nothing to press,
+  and Stop then Start showed the same message again.
+- **Rotation settings at every scope.** `after_compactions` (a number or
+  `never`), `on_due` (`auto`, the default, `ask` or `off`) and
+  `on_pr_merged`. The most specific wins: agent, persona in a workspace,
+  persona, workspace, service, this install, org config. Settings › Agents
+  › Rotation and `<cli> agents rotate` set them; `<cli> agents rotate <id>
+  --show` names where each value comes from. `<cli> agents keep` and
+  `<cli> agents handoff` are the callout's buttons. A change applies to
+  running agents too.
+- Resume (or Start) on a due agent follows `on_due`: `auto` relaunches it
+  from its handoff, `ask` refuses with the callout's choices, `off` goes
+  on with the same conversation.
+
+### Fixed
+
+- **`web restart` with the service installed** restarts the launchd job
+  and names its pid and the service's log. Before, it started a plain
+  server, said "started", and that server died seconds later because
+  launchd had brought the job back onto the port. `web up` starts a job
+  that isn't answering; `web down` refuses and names `service uninstall`.
+- The "port in use" message no longer says to kill whatever holds the
+  port, which killed the service. It names `service status` and `web
+  restart`.
+
+### Migrations
+
+- None required. Rotation now relaunches by itself (`on_due: auto`). To
+  keep den#4's behavior (a person relaunches), set `on_due: ask` under
+  `agents.rotate` in the org config, or `<cli> agents rotate on_due ask`.
+  `agents.rotate.standing` still works; a persona override replaces it.
+
+## [0.4.22] - 2026-11-10
+
+### Added
+
+- **Opt-in: agents meant to keep running across logout (D18, D20).**
+  `service install --mode always` installs the web server and the session
+  host as LaunchDaemons that run as you (`UserName`): they start at boot
+  and are meant to keep running when you log out of the desktop, and so
+  every terminal and agent. It is not yet proven across a logout: `service
+  help`, `--plan`, install, `doctor` and the agents page say so. It takes your admin password once (sudo); `--mode login`, the
+  default, keeps LaunchAgents in the desktop session (they stop at
+  logout). Without `--mode`, install keeps the mode already installed.
+  Switching removes the other mode's jobs.
+- **The session host is its own launchd job** (`<label>` with `.web` →
+  `.sessions`), in both modes, so it runs in the mode's session whoever
+  starts the first terminal: before, it inherited the launchd session of
+  whatever started it, and one started from the desktop ended at logout
+  with every agent in it. `<cli> sessions` and agents wait for the job.
+- **Full Disk Access for Den, not for every node program.** The host job
+  runs a copy of node Den owns, `<stateDir>/bin/<cli>-sessions-host`
+  (0700), the path to grant Full Disk Access to (protected folders: other
+  volumes, Desktop, Documents); agents inherit it. Install refreshes the
+  copy when node changes and says when the grant must be given again (a
+  new signer, an ad-hoc signed node). A node that can't be copied
+  (Homebrew's) is run directly, and install says so.
+- **Where it runs, shown honestly.** Every session records the launchd
+  session its host ran in (`launchctl managername`). The Agents page tags
+  each agent **Stops at logout** (the desktop session; tap for the fix) or
+  **No GUI** (kept across logout: no login keychain, no GUI apps; 1Password
+  through the service-account token, headless browsers, Full Disk Access
+  for protected folders). `doctor` ends with **where it runs**: the
+  server's and the host's session, Full Disk Access and the path to grant,
+  and the service's mode. `web up` from an ssh (Background) shell says what
+  a server started there means.
+- **Rename, visible (D25).** **Rename…** in an agent pane's ⋯ menu and
+  **Rename** on a stopped agent's row, by touch or keyboard, and
+  `<cli> agents rename <id> <name>` (`--clear`: back to its id). Before,
+  only a double-click on an open tab renamed one.
+- **Agents tell apart in a list of sessions (D24).** Den names each
+  Claude Code agent's session `<cli>-<ws>:<name, else id>` (`--name`) at
+  start and resume, so another session listing its peers sees which agent
+  is which, not a generic name. A rename shows at its next start or resume.
+
+### Fixed
+
+- **`service install` said running while its job crash-looped (D26).** A
+  plain `web up` server of the same install on the port answered the
+  check, while the job failed to start on the taken port. Install now
+  stops a plain server of this install first, and says running only when
+  the server answering is the job's own process; `service status` says
+  when another process holds the port. `--plan` says when install would
+  stop one.
+- **`service status` names a job whose plist is present but not loaded**,
+  with the `launchctl bootstrap` that loads it (`sudo` for a LaunchDaemon);
+  `doctor` shows it too.
+- **Tests never reach this machine's launchctl, gh or vendor CLIs**, even
+  through a spawn without `env`: the inert stand-ins are now first on the
+  real PATH (jest's globalSetup), not only on each test file's sandboxed
+  `process.env`.
+
+### Migrations
+
+- None required. An existing install keeps its mode (login). To try
+  keeping agents running across logout (not yet proven), run
+  `<cli> service install --mode always` once (one sudo), then grant Full
+  Disk Access to the path `doctor` names if agents read protected folders.
+- `<cli> service` with no subcommand prints its help (before, an error).
+
 ## [0.4.21] - 2026-11-09
 
 ### Added

package/docs/distributions.md

@@ -1957,16 +1957,96 @@ Apps › New GitHub App):
 
 ## Running the web UI as a service (macOS)
 
-Den ships a launchd installer that runs the web UI at login and restarts it if
-it exits:
+Den ships a launchd installer that runs the web UI and the session host (every
+terminal and agent) as launchd jobs, restarted if they exit:
 
 ```bash
-./bin/acme service install     # install (or refresh) and start it
+./bin/acme service install                # install (or refresh) and start them
+./bin/acme service install --mode always  # meant to keep them running across logout (opt-in, not yet proven)
 ./bin/acme service install --plan  # what install would do; writes and loads nothing
 ./bin/acme service status      # launchd's view: state, pid, last exit code
-./bin/acme service print       # the LaunchAgent plist it would install; installs nothing
-./bin/acme service uninstall   # stop it and remove the LaunchAgent
-```
+./bin/acme service print       # the web plist it would install; installs nothing
+./bin/acme service uninstall   # stop them and remove their plists
+```
+
+With the service installed, `web` works through launchd. `web restart`
+restarts the job (`launchctl kickstart -k`) and names its new pid and the
+service's log. `web up` starts the job when it isn't answering. `web down`
+refuses, because launchd would only start it again: use `service
+uninstall` to stop it. Under `always`, restarting needs sudo, so `web
+restart` prints the `sudo launchctl kickstart -k system/<label>` line for
+you to run.
+
+### Login or always
+
+| `--mode`          | Jobs                                                  | At logout                            |
+| ----------------- | ----------------------------------------------------- | ------------------------------------ |
+| `login` (default) | LaunchAgents in the desktop session (`gui/<uid>`)     | stop, with every agent               |
+| `always`          | LaunchDaemons that run as you (`UserName`), from boot | meant to keep running, and so agents |
+
+`always` is opt-in and not yet proven across a logout: no logout has
+shown it keeping an agent on the same conversation yet. Use `login` unless
+you are testing it.
+
+`always` takes your admin password once (sudo writes and loads the
+LaunchDaemons in `/Library/LaunchDaemons`); it is never asked for again.
+Without `--mode`, install keeps the mode already installed, so re-running it
+after an upgrade never changes it. Switching mode removes the other mode's
+jobs: never both. Use `always` on a machine you reach from elsewhere (ssh, a
+browser on another machine); `login` on a laptop.
+
+A process outside the desktop session has no login keychain and no GUI. So
+under `always`, agents use:
+
+- **1Password**: the service-account token (`secrets.onepassword.token`),
+  not the desktop app. `doctor` warns when this process has none.
+- **Browsers**: headless Chromium and Firefox. WebKit on macOS needs a
+  desktop session; run it from Playwright's Linux image instead
+  (CONTRIBUTING.md, `DEN_PW_WS`).
+- **Protected folders** (other volumes, Desktop, Documents): Full Disk
+  Access, granted once (below).
+
+Each session records the launchd session its host ran in, and the Agents page
+tags it: **Stops at logout** (the desktop session; tap it for the fix) or
+**No GUI** (kept across logout). `web up` from an ssh shell (a Background
+session) says the same before it starts a server there.
+
+### The session host job and Full Disk Access
+
+Both modes install the session host as its own job, `<label>` with `.web`
+replaced by `.sessions` (`local.acme.sessions`), so it runs in the mode's
+session whoever starts the first terminal; `<cli> sessions` and agents then
+wait for it rather than starting a host in the caller's session. It runs a
+copy of node Den owns, `<stateDir>/bin/<cli>-sessions-host` (0700), and
+macOS grants Full Disk Access to that path: never to the shared node, which
+would give it to every node program. To grant it: System Settings → Privacy &
+Security → Full Disk Access → + → that path (⌘⇧G to type it), then
+`<cli> sessions host --stop` (it restarts with the grant). Agents inherit it.
+
+Install refreshes the copy when node changes. An official node build
+(nodejs.org, nvm) is signed by the Node.js project, so the grant holds across
+upgrades; install says when the signer changed and it must be granted again.
+An ad-hoc signed node needs a new grant after every change, and Homebrew's
+node loads libraries beside it and can't be copied: install then runs it
+directly and says so. `doctor` shows whether the host has Full Disk Access,
+and the path to grant.
+
+### What doctor shows
+
+`doctor` ends with **where it runs**: the web server's and the session host's
+launchd session (a warning with the fix when it stops at logout), Full Disk
+Access, and the service: its mode, or `plist present, job not loaded:
+launchctl bootstrap <domain> <plist>` (`sudo` for a LaunchDaemon) when launchd
+has dropped a job whose plist is still there.
+
+### Running means the job's own process
+
+A plain `web up` server of the same install on the port would answer for the
+job, which then fails to start on the taken port and restarts forever. So
+install stops a plain server of this install first (and says so), and says
+`running` only when the server answering is the job's own process (its pid is
+launchd's). Otherwise it says `port <N> is served by pid <P>, not the job`
+and exits 1; `status` says the same.
 
 The label and log directory come from the org config:
 
@@ -2011,12 +2091,14 @@ node_modules/@monster-orange/den/service/install.sh uninstall
 node_modules/@monster-orange/den/service/install.sh print       # the plist only
 ```
 
-| Variable            | Default                                  |
-| ------------------- | ---------------------------------------- |
-| `DEN_ROOT`          | required in a distribution               |
-| `DEN_SERVICE_LABEL` | `local.<distribution dir name>.web`      |
-| `DEN_SERVICE_LOGS`  | `~/Library/Logs/<distribution dir name>` |
-| `DEN_SERVICE_NODE`  | see below                                |
+| Variable               | Default                                                                 |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `DEN_ROOT`             | required in a distribution                                              |
+| `DEN_SERVICE_LABEL`    | `local.<distribution dir name>.web`                                     |
+| `DEN_SERVICE_LOGS`     | `~/Library/Logs/<distribution dir name>`                                |
+| `DEN_SERVICE_NODE`     | see below                                                               |
+| `DEN_SERVICE_MODE`     | `login` (or `always`)                                                   |
+| `DEN_SERVICE_HOST_EXE` | none: the host runs that node (`<cli> service install` sets Den's copy) |
 
 The service runs the engine's server, from the distribution root, with the
 `node` on your `PATH` at install time. A version manager's node (nvm, fnm,
@@ -2495,6 +2577,15 @@ server scoped to its workspace.
   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.
+- **Renaming.** `agents rename <id> <name>` (or `--clear`, back to its
+  id) names an agent; so do **Rename…** in its pane's ⋯ menu and **Rename**
+  on a stopped agent's row, by touch or keyboard, as well as a double-click
+  on its tab. The id never changes.
+- **The name other sessions see.** Den names a Claude Code agent's session
+  `<cli>-<ws>:<name, else id>` (`--name`) at every start and resume, so
+  another session listing its peers tells Den's agents apart. A rename
+  shows at its next start or resume. The record's `peerName` is the name
+  last given, so reading it back is never taken for a `/rename`.
 - `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
@@ -3213,10 +3304,12 @@ report. It works on den-claude for personas with Den's hooks on.
    the turn once while the handoff is missing or fails the check. The
    instruction: write `handoff.md` in the agent's files folder, then end
    the turn.
-4. Den relaunches the role. **Relaunch from handoff** starts a fresh
-   conversation (a new conversation id) with the same persona, workspace,
-   folder and grants. Its first prompt is the handoff. The handoff moves to
-   `agent-files/<id>/handoffs/`, and the record notes the rotation.
+4. Den relaunches the role, by itself unless the settings say otherwise
+   (`on_due`, below). A relaunch starts a fresh conversation (a new
+   conversation id) with the same name, persona, workspace, folder and
+   grants. Its first prompt is the handoff. The handoff moves to
+   `agent-files/<id>/handoffs/`, the record notes the rotation, and the
+   old conversation is kept.
 
 **The handoff** has five parts, each a heading, each filled in. Write it
 plainly, and explain every ID, as in a hand-back. It must stay under 20,000
@@ -3249,38 +3342,89 @@ agent's `handoff.md` (by its id), a file, or stdin: exit 0 when
 it passes, 1 with each missing or empty part and each unexplained ID. A
 part can also be a line such as `Next step: open the PR`.
 
-**Resume after a rotation.** Once a rotation is due and `handoff.md`
-passes, Den declines a plain Resume of that conversation:
-
-- The Agents page shows the row as "Ready to relaunch (3 compactions)" or
-  "Ready to relaunch (PR merged)". Its buttons are Relaunch from handoff
-  (the primary one), Start fresh and Remove.
-- `<cli> agents resume <id>` refuses (exit 1) and prints
-  `Relaunch from handoff: <cli> agents relaunch <id>`. The resume route
-  answers 409 with code `rotated`.
-- `<cli> agents relaunch <id> [-w <ws>]` and
-  `POST /api/workspaces/<ws>/agents/<id>/relaunch` relaunch it. A running
-  rotated agent is stopped first.
-- With `handoff.md` missing or failing the check, the row says so, and
-  Resume and Start fresh stay. Resume the agent to write or fix it.
-  Relaunch says what is wrong (409 `no_handoff`) and names Start fresh.
-- After a restart, a standing persona that rotated relaunches on its own,
-  as a standing persona resumes on its own.
-
-**Settings**, in the org config:
+**What happens when a rotation is due** (`on_due`):
+
+- `auto` (the default). At the agent's next idle, never mid-turn, Den
+  types the instruction into its session: write the handoff. Once the
+  handoff passes the check and the agent is idle, Den relaunches it. The
+  page shows a toast ("Relaunched <id> from its handoff after 3
+  compactions. The old conversation <id> is kept.") and the audit log
+  records it. Den asks at most twice, two minutes apart. If the handoff
+  still fails, it falls back to `ask`.
+- `ask`. Nothing happens by itself. The agent's callout has the buttons.
+- `off`. Nothing happens, and no callout shows. Resume goes on with the
+  same conversation.
+
+**The callout** shows on a due agent's row (running or stopped) and in its
+pane bar. It says what happens next and where the settings come from
+("Rotates after 3 compactions (persona planner); when due: relaunch by
+itself (default)"). Its buttons:
+
+- **Relaunch now**: from the handoff when it passes. Otherwise Den asks
+  for it first (a stopped agent resumes to write it) and relaunches it
+  once it passes, whatever `on_due` says.
+- **Write handoff**: on a running agent without one, types the
+  instruction. It is refused mid-turn.
+- **Keep this conversation**: the compaction count starts again. With
+  "Don't ask again for this agent", that agent's `after_compactions` is
+  set to `never`. A person's only.
+- **Settings**: Settings › Agents › Rotation.
+
+**Resume and Start on a due agent** follow `on_due`. Under `auto`, Resume
+relaunches it from its handoff once the handoff passes. Under `ask`,
+`<cli> agents resume <id>` refuses (exit 1) and names
+`<cli> agents relaunch <id>`, and the resume route answers 409 with code
+`rotated`. `<cli> agents relaunch <id> [-w <ws>]` and
+`POST /api/workspaces/<ws>/agents/<id>/relaunch` relaunch it at any time
+(a running agent is stopped first; a missing or failing handoff is a 409
+`no_handoff`). After a restart, a standing persona that rotated relaunches
+on its own.
+
+**Settings.** Three keys:
+
+| Key                 | Values                 | Default |
+| ------------------- | ---------------------- | ------- |
+| `after_compactions` | 1 to 100, or `never`   | 3       |
+| `on_due`            | `auto`, `ask` or `off` | `auto`  |
+| `on_pr_merged`      | `true` or `false`      | `true`  |
+
+Each key comes from the most specific scope that sets it: the agent, the
+persona in a workspace, the persona, the workspace, the service (the
+workspace service whose folder holds the agent's folder), this install,
+the org config, then Den's default. A change applies to running agents
+too, at their next look (about every 15 seconds).
+
+The org's values go in the org config:
 
 ```yaml
 agents:
   rotate:
-    after_compactions: 3 # 1 to 100; the default is 3
-    standing: true # standing personas rotate too (the default)
+    after_compactions: 3 # 1 to 100, or never
+    on_due: auto # auto, ask or off
+    on_pr_merged: true
 ```
 
-`standing` is for standing personas, such as the planner and the
-orchestrator. With `true` (the default), they rotate like the rest: only
-their context resets, and they keep their id and workspace. With `false`,
-they never rotate. A setting takes effect at the agent's next start or
-relaunch. An unknown key, or a bad value, is an error naming the key.
+This install's values and every override are set in Settings › Agents ›
+Rotation, or from the command line, and kept in
+`<stateDir>/agent-rotation.json`:
+
+```bash
+<cli> agents rotate                                  # every value and override
+<cli> agents rotate on_due ask                       # this install
+<cli> agents rotate --persona planner after_compactions never
+<cli> agents rotate --persona planner -w notes after_compactions 5  # that persona in notes
+<cli> agents rotate --workspace notes on_due off
+<cli> agents rotate --service shop on_pr_merged false
+<cli> agents rotate --agent art --unset after_compactions
+<cli> agents rotate art --show                       # its values, and where each comes from
+<cli> agents keep <id> [--never]                     # Keep this conversation
+<cli> agents handoff <id>                            # Write handoff
+```
+
+`agents rotate` and `agents keep` are refused inside an agent's session.
+den#4's `standing: false` still works: standing personas never rotate,
+unless a persona or agent override says otherwise. Set it per persona
+instead (`--persona planner after_compactions never`).
 
 ### Runtimes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.21",
+  "version": "0.4.23",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {