@monster-orange/den 0.4.21 → 0.4.22

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.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,88 @@ 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
+```
+
+### 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 +2083,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 +2569,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

package/package.json

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

package/service/install.sh

@@ -1,24 +1,42 @@
 #!/usr/bin/env bash
-# Run the web UI as a long-lived macOS service (a launchd LaunchAgent):
-# started at login, restarted if it exits, not tied to any terminal.
+# Run the web UI and the session host as long-lived macOS launchd jobs:
+# started at boot or login, restarted if they exit, not tied to a terminal.
 #
-#   service/install.sh            install (or refresh) and start it
-#   service/install.sh uninstall  stop it and remove the LaunchAgent
-#   service/install.sh status     launchd's view of it
-#   service/install.sh print      write the LaunchAgent plist to stdout only
+#   service/install.sh            install (or refresh) and start them
+#   service/install.sh uninstall  stop them and remove their plists
+#   service/install.sh status     launchd's view of them
+#   service/install.sh print      write the web plist to stdout only
+#   service/install.sh print-host write the session host plist to stdout only
+#
+# Two modes (D18), DEN_SERVICE_MODE:
+#   login   (default) LaunchAgents in the desktop session (gui/<uid>): they
+#           start at login and stop at logout, with every agent.
+#   always  LaunchDaemons that run as you (UserName): they start at boot and
+#           keep running across logout, so agents do too. One sudo writes
+#           and loads them. No login keychain, no GUI there: agents use the
+#           1Password service-account token, headless browsers, and Full
+#           Disk Access for protected folders.
+#
+# The session host job runs DEN_SERVICE_HOST_EXE, a copy of node Den owns
+# (<stateDir>/bin/<cli>-sessions-host): Full Disk Access is granted to that
+# path, so it never goes to the shared node. A node change replaces the
+# copy; the grant holds when the code signature's requirement is the same
+# (an official node build), and install says to grant it again when not.
 #
 # Works from Den's checkout and from a distribution, where it lives in
 # node_modules/@monster-orange/den/service/. The distribution root is
-# DEN_ROOT, else this checkout when it holds den.yml. The agent runs the
-# engine's server with the node found on PATH now, from the distribution
-# root; re-run install after changing node versions.
+# DEN_ROOT, else this checkout when it holds den.yml.
 #
-#   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
-#   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
-#   DEN_SERVICE_NODE   the node the agent runs (default: see pick_node)
+#   DEN_SERVICE_LABEL       web job label (default local.<dist dir name>.web)
+#   DEN_SERVICE_HOST_LABEL  host job label (default: the web label's .web → .sessions)
+#   DEN_SERVICE_LOGS        log directory (default ~/Library/Logs/<dist dir name>)
+#   DEN_SERVICE_NODE        the node the jobs run (default: see pick_node)
+#   DEN_SERVICE_HOST_EXE    the host's node copy (default: none, the host runs that node)
 #   DEN_SERVICE_READY_CHECK=external  install does not print "running": the
 #                      caller (`<cli> service install`) checks the server
 #                      answers first.
+#   DEN_SERVICE_DAEMON_DIR, DEN_SERVICE_SUDO  (tests) where LaunchDaemons go
+#                      and what runs as root (default /Library/LaunchDaemons, sudo)
 set -euo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
@@ -34,9 +52,31 @@ fi
 [ -f "$DIST/den.yml" ] || { echo "✗ $DIST has no den.yml" >&2; exit 1; }
 NAME="$(basename "$DIST")"
 LABEL="${DEN_SERVICE_LABEL:-local.$NAME.web}"
+HOST_LABEL="${DEN_SERVICE_HOST_LABEL:-${LABEL%.web}.sessions}"
 LOGS="${DEN_SERVICE_LOGS:-$HOME/Library/Logs/$NAME}"
-PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
-DOMAIN="gui/$(id -u)"
+SVC_MODE="${DEN_SERVICE_MODE:-login}"
+case "$SVC_MODE" in
+  login|always) ;;
+  *) echo "✗ DEN_SERVICE_MODE must be login or always, not \"$SVC_MODE\"" >&2; exit 2 ;;
+esac
+UID_N="$(id -u)"
+USER_N="$(id -un)"
+AGENT_DIR="$HOME/Library/LaunchAgents"
+DAEMON_DIR="${DEN_SERVICE_DAEMON_DIR:-/Library/LaunchDaemons}"
+SUDO="${DEN_SERVICE_SUDO-sudo}"
+GUI="gui/$UID_N"
+
+# The plist and domain for a label in a mode.
+plist_for() { # $1 label $2 mode
+  if [ "$2" = always ]; then echo "$DAEMON_DIR/$1.plist"; else echo "$AGENT_DIR/$1.plist"; fi
+}
+domain_for() { if [ "$1" = always ]; then echo system; else echo "$GUI"; fi; }
+other_mode() { if [ "$1" = always ]; then echo login; else echo always; fi; }
+# Root runs it in the system domain (a LaunchDaemon); else as you.
+as_mode() { # $1 mode, then the command
+  local m="$1"; shift
+  if [ "$m" = always ] && [ -n "$SUDO" ]; then "$SUDO" "$@"; else "$@"; fi
+}
 
 # tsx: the nearest node_modules/tsx at or above the engine (hoisted installs).
 find_tsx() {
@@ -76,20 +116,75 @@ pick_node() {
   echo "$node"
 }
 
-write_plist() { # $1 = output file
+# The code signature's designated requirement, or "" (unsigned, no codesign).
+requirement() { codesign -d -r- "$1" 2>&1 | sed -n 's/^designated => //p' || true; }
+
+# The host's node copy (D18): refreshed when node changed. Prints the path
+# the host job runs: the copy, or node itself when it cannot be copied.
+# A node linked to libraries beside it (Homebrew's) does not run copied.
+self_contained() {
+  ! { command -v otool >/dev/null 2>&1 && otool -L "$1" 2>/dev/null | grep -q '@rpath/\|/opt/homebrew/\|/usr/local/opt/'; }
+}
+
+host_exe() { # $1 node
+  local node="$1" exe="${DEN_SERVICE_HOST_EXE:-}" c src=""
+  if [ -z "$exe" ]; then echo "$node"; return; fi
+  # The node the jobs run, else (unless DEN_SERVICE_NODE names one) the
+  # PATH's: a version manager's is fine here, since the copy outlives it.
+  for c in "$node" $([ -z "${DEN_SERVICE_NODE:-}" ] && command -v node 2>/dev/null); do
+    if self_contained "$c"; then src="$c"; break; fi
+  done
+  if [ -z "$src" ]; then
+    echo "⚠ $node is not self-contained (it loads libraries beside it), so the session host" >&2
+    echo "  runs it directly: grant Full Disk Access to $node, and again after each node" >&2
+    echo "  upgrade. An official node build (nodejs.org, nvm) avoids that: set DEN_SERVICE_NODE." >&2
+    echo "$node"; return
+  fi
+  node="$src"
+  if [ -f "$exe" ] && cmp -s "$node" "$exe"; then echo "$exe"; return; fi
+  local before="" after
+  [ -f "$exe" ] && before="$(requirement "$exe")"
+  mkdir -p "$(dirname "$exe")"
+  chmod 700 "$(dirname "$exe")"
+  cp "$node" "$exe.new"
+  chmod 700 "$exe.new"
+  mv -f "$exe.new" "$exe"
+  after="$(requirement "$exe")"
+  case "$after" in
+    "" | cdhash*)
+      echo "⚠ $exe is a copy of $node, which has no stable code signature: Full Disk" >&2
+      echo "  Access must be granted to it again after every node change. An official" >&2
+      echo "  node build (nodejs.org, nvm) keeps the grant: set DEN_SERVICE_NODE." >&2 ;;
+    *)
+      if [ -n "$before" ] && [ "$before" != "$after" ]; then
+        echo "⚠ $exe changed signer: grant it Full Disk Access again" >&2
+        echo "  (System Settings → Privacy & Security → Full Disk Access)." >&2
+      fi ;;
+  esac
+  echo "$exe"
+}
+
+write_plist() { # $1 = output file, $2 = web|host, $3 = mode
   NODE="$(pick_node "$MODE")"
   TSX="$(find_tsx)" || { echo "✗ tsx not installed: run npm ci in $DIST" >&2; exit 1; }
+  local exe="$NODE" label="$LABEL" log="web.log"
+  if [ "$2" = host ]; then
+    if [ "$MODE" = install ]; then exe="$(host_exe "$NODE")"; else exe="${DEN_SERVICE_HOST_EXE:-$NODE}"; fi
+    label="$HOST_LABEL"; log="sessions-host.log"
+  fi
   DOCKER_DIR="$(dirname "$(command -v docker || echo /usr/local/bin/docker)")"
   SVC_PATH="$(dirname "$NODE"):$DOCKER_DIR:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-  python3 -I - "$1" "$LABEL" "$NODE" "$TSX" "$ENGINE" "$DIST" "$SVC_PATH" "$HOME" "$LOGS" <<'PY'
+  python3 -I - "$1" "$2" "$3" "$label" "$exe" "$TSX" "$ENGINE" "$DIST" "$SVC_PATH" "$HOME" "$LOGS/$log" "$USER_N" <<'PY'
 import plistlib, sys
-out, label, node, tsx, engine, dist, path, home, logs = sys.argv[1:]
+out, kind, mode, label, exe, tsx, engine, dist, path, home, log, user = sys.argv[1:]
+entry = (f"{engine}/src/ui/server/index.ts", "--silent") if kind == "web" \
+    else (f"{engine}/src/ui/cli/index.ts", "sessions", "host", "--stand-by")
 data = {
     "Label": label,
-    "ProgramArguments": [node, "--import", f"{tsx}/dist/loader.mjs",
-                         f"{engine}/src/ui/server/index.ts", "--silent"],
+    "ProgramArguments": [exe, "--import", f"{tsx}/dist/loader.mjs", *entry],
     "WorkingDirectory": dist,
-    "EnvironmentVariables": {"PATH": path, "HOME": home,
+    "EnvironmentVariables": {"PATH": path, "HOME": home, "USER": user,
+                             "LOGNAME": user,
                              "DEN_ROOT": dist, "DEN_ENGINE_ROOT": engine},
     "RunAtLoad": True,
     "KeepAlive": True,
@@ -97,9 +192,12 @@ data = {
     # Interactive, not Background: macOS gives Background agents efficiency
     # cores and throttled I/O, and the UI stalled for seconds under load.
     "ProcessType": "Interactive",
-    "StandardOutPath": f"{logs}/web.log",
-    "StandardErrorPath": f"{logs}/web.log",
+    "StandardOutPath": log,
+    "StandardErrorPath": log,
 }
+if mode == "always":
+    # A LaunchDaemon runs as root unless told otherwise: run as the person.
+    data["UserName"] = user
 if out == "-":
     sys.stdout.buffer.write(plistlib.dumps(data))
 else:
@@ -108,58 +206,110 @@ else:
 PY
 }
 
+# Stop and remove a job (any mode), quietly when it is not there.
+remove_job() { # $1 label $2 mode
+  local plist; plist="$(plist_for "$1" "$2")"
+  if [ "$2" = always ]; then
+    [ -f "$plist" ] || return 0
+  fi
+  as_mode "$2" launchctl bootout "$(domain_for "$2")/$1" 2>/dev/null || true
+  [ -f "$plist" ] && as_mode "$2" rm -f "$plist"
+  return 0
+}
+
+# Install and start one job in SVC_MODE.
+load_job() { # $1 label $2 web|host
+  local label="$1" plist domain tmp
+  plist="$(plist_for "$label" "$SVC_MODE")"
+  domain="$(domain_for "$SVC_MODE")"
+  tmp="$(mktemp "${TMPDIR:-/tmp}/den-plist.XXXXXX")"
+  write_plist "$tmp" "$2" "$SVC_MODE"
+  plutil -lint "$tmp" >/dev/null
+  # The other mode's job is the same service: never both.
+  remove_job "$label" "$(other_mode "$SVC_MODE")"
+  as_mode "$SVC_MODE" launchctl bootout "$domain/$label" 2>/dev/null || true
+  # bootout returns before launchd has let go of the label; a bootstrap
+  # straight after fails ("Bootstrap failed: 5") and leaves NO service.
+  # Wait for it to go, then retry bootstrap a few times.
+  for _ in $(seq 1 50); do
+    as_mode "$SVC_MODE" launchctl print "$domain/$label" >/dev/null 2>&1 || break
+    sleep 0.2
+  done
+  if [ "$SVC_MODE" = always ]; then
+    as_mode always install -o root -g wheel -m 644 "$tmp" "$plist"
+    rm -f "$tmp"
+  else
+    mkdir -p "$(dirname "$plist")"
+    mv "$tmp" "$plist"
+  fi
+  local loaded=0
+  for _ in 1 2 3 4 5; do
+    if as_mode "$SVC_MODE" launchctl bootstrap "$domain" "$plist" 2>/dev/null; then loaded=1; break; fi
+    sleep 1
+  done
+  [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $label (plist: $plist)" >&2; exit 1; }
+  as_mode "$SVC_MODE" launchctl kickstart -k "$domain/$label"
+}
+
+# The job's state, as status shows it.
+job_status() { # $1 label
+  local m plist domain svc_node out
+  for m in always login; do
+    plist="$(plist_for "$1" "$m")"
+    [ -f "$plist" ] || continue
+    domain="$(domain_for "$m")"
+    # The node it was installed with may be gone (a removed nvm version):
+    # launchd then restarts it forever with no useful message.
+    if command -v plutil >/dev/null 2>&1; then
+      svc_node="$(plutil -extract ProgramArguments.0 raw -o - "$plist" 2>/dev/null || true)"
+      if [ -n "$svc_node" ] && [ ! -x "$svc_node" ]; then
+        echo "✗ $1 runs $svc_node, which no longer exists: re-run service install" >&2
+        return 1
+      fi
+    fi
+    echo "$1 ($m: $domain)"
+    if out="$(launchctl print "$domain/$1" 2>/dev/null)"; then
+      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs|spawn type)'
+    else
+      echo "  plist present, job not loaded: $([ "$m" = always ] && echo "sudo ")launchctl bootstrap $domain $plist"
+    fi
+    return 0
+  done
+  # launchctl's own "Could not find service" is noise when it isn't loaded.
+  echo "$1 is not loaded"
+}
+
 MODE="${1:-install}"
 case "$MODE" in
   install)
-    mkdir -p "$LOGS" "$(dirname "$PLIST")"
-    write_plist "$PLIST.new"
-    plutil -lint "$PLIST.new" >/dev/null
-    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
-    # bootout returns before launchd has let go of the label; a bootstrap
-    # straight after fails ("Bootstrap failed: 5") and leaves NO service.
-    # Wait for it to go, then retry bootstrap a few times.
-    for _ in $(seq 1 50); do
-      launchctl print "$DOMAIN/$LABEL" >/dev/null 2>&1 || break
-      sleep 0.2
-    done
-    mv "$PLIST.new" "$PLIST"
-    loaded=0
-    for _ in 1 2 3 4 5; do
-      if launchctl bootstrap "$DOMAIN" "$PLIST" 2>/dev/null; then loaded=1; break; fi
-      sleep 1
-    done
-    [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $LABEL (plist: $PLIST)" >&2; exit 1; }
-    launchctl kickstart -k "$DOMAIN/$LABEL"
+    mkdir -p "$LOGS"
+    if [ "$SVC_MODE" = always ] && [ -n "$SUDO" ]; then
+      echo "… $SVC_MODE: LaunchDaemons running as $USER_N need your admin password once (sudo)"
+    fi
+    load_job "$HOST_LABEL" host
+    load_job "$LABEL" web
     if [ "${DEN_SERVICE_READY_CHECK:-}" = external ]; then
-      echo "… $LABEL started; waiting for it to answer"
+      echo "… $LABEL started ($SVC_MODE); waiting for it to answer"
     else
-      echo "✓ $LABEL running (logs: $LOGS/web.log)"
+      echo "✓ $LABEL running ($SVC_MODE; logs: $LOGS/web.log)"
     fi
     ;;
   uninstall)
-    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
-    rm -f "$PLIST"
-    echo "✓ $LABEL removed"
+    for m in login always; do
+      remove_job "$LABEL" "$m"
+      remove_job "$HOST_LABEL" "$m"
+    done
+    echo "✓ $LABEL and $HOST_LABEL removed"
     ;;
   print)
-    write_plist -
+    write_plist - web "$SVC_MODE"
+    ;;
+  print-host)
+    write_plist - host "$SVC_MODE"
     ;;
   status)
-    # The node the agent was installed with may be gone (a removed nvm
-    # version): launchd then restarts it forever with no useful message.
-    if [ -f "$PLIST" ] && command -v plutil >/dev/null 2>&1; then
-      svc_node="$(plutil -extract ProgramArguments.0 raw -o - "$PLIST" 2>/dev/null || true)"
-      if [ -n "$svc_node" ] && [ ! -x "$svc_node" ]; then
-        echo "✗ $LABEL runs $svc_node, which no longer exists: re-run service install" >&2
-        exit 1
-      fi
-    fi
-    # launchctl's own "Could not find service" is noise when it isn't loaded.
-    if out="$(launchctl print "$DOMAIN/$LABEL" 2>/dev/null)"; then
-      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs|spawn type)'
-    else
-      echo "$LABEL is not loaded"
-    fi
+    job_status "$LABEL"
+    job_status "$HOST_LABEL"
     ;;
-  *) echo "usage: $0 [install|uninstall|status|print]" >&2; exit 2 ;;
+  *) echo "usage: $0 [install|uninstall|status|print|print-host]" >&2; exit 2 ;;
 esac

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

@@ -455,6 +455,11 @@ export function firstPromptArg(text: string | undefined): string[] {
   return [t.startsWith("-") ? `Prompt: ${t}` : t];
 }
 
+/** D24: `--name <label>`, so peers tell Den's agents apart; or nothing. */
+function nameArg(label: string | undefined): string[] {
+  return label ? ["--name", label] : [];
+}
+
 const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 
 /**
@@ -503,6 +508,7 @@ export const denClaude: Runtime = {
         bin,
         "--session-id",
         id,
+        ...nameArg(input.sessionLabel),
         ...c.argv,
         ...firstPromptArg(input.firstPrompt),
       ],
@@ -517,7 +523,13 @@ export const denClaude: Runtime = {
     const bin = binFor(input);
     const c = common(input);
     return {
-      argv: [bin, "--resume", input.resumeToken, ...c.argv],
+      argv: [
+        bin,
+        "--resume",
+        input.resumeToken,
+        ...nameArg(input.sessionLabel),
+        ...c.argv,
+      ],
       env: {},
       files: c.files,
       warnings: c.warnings,

package/src/shared/agents/records.ts

@@ -86,6 +86,12 @@ export interface AgentRecord {
   displayName?: string;
   /** When displayName was given (ISO 8601): the latest rename wins (AG-4b). */
   displayNameAt?: string;
+  /**
+   * D24: the name Den last gave its runtime session (Claude Code's
+   * `--name`, peerSessionName), so reading it back is never taken for a
+   * rename.
+   */
+  peerName?: string;
   /**
    * The model version it runs (AG-12.3): "latest" (the model's newest), or
    * a pinned version. Absent: before AG-12, `model` as given.

package/src/shared/agents/runtime.ts

@@ -120,6 +120,12 @@ export interface LaunchInput {
    * Only a runtime with `firstPrompt: true` is given one.
    */
   firstPrompt?: string;
+  /**
+   * D24: the name other sessions see this one by (peerSessionName:
+   * `<cli>-<ws>:<name>`). A runtime that can name its session (den-claude:
+   * `--name`) does, at launch and at resume.
+   */
+  sessionLabel?: string;
 }
 
 export interface LaunchOutput {

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

@@ -12,7 +12,10 @@
  *     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.
+ * D24: Den names the runtime's session for other sessions to see
+ * (peerSessionName: `<cli>-<ws>:<name>`, Claude Code's `--name`) at launch
+ * and resume. That name read back is Den's own (the record's peerName),
+ * never a rename.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -71,6 +74,8 @@ function runtimeName(
   } catch {
     name = null;
   }
+  // D24: Den's own --name, read back, is not the runtime's rename.
+  if (name && name === rec.peerName) name = null;
   // null: nothing new (not caught up, not found); the last name stays.
   if (name && name !== seen?.name) {
     seen = { token, name, at: now() };
@@ -83,6 +88,21 @@ function runtimeName(
   return seen;
 }
 
+/**
+ * D24: the name other sessions (ListAgents) see agent `rec` by:
+ * `<cli>-<ws>:<its name, else its id>`. No control characters: it is a
+ * process argument.
+ */
+export function peerSessionName(
+  cli: string,
+  ws: string,
+  rec: Pick<AgentRecord, "id" | "displayName">,
+): string {
+  // eslint-disable-next-line no-control-regex
+  const name = (rec.displayName ?? "").replace(/[\u0000-\u001f\u007f]/g, "");
+  return `${cli}-${ws}:${name.trim() || rec.id}`;
+}
+
 /**
  * The agent's session name: the latest of Den's rename and the runtime's,
  * or undefined when neither has one. Never throws.