@monster-orange/den 0.4.22 → 0.4.24

package/CHANGELOG.md

@@ -4,6 +4,79 @@ 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.24] - 2026-11-10
+
+### Fixed
+
+- **Visit opens in Safari (D27).** Visit, in the service panel and the
+  rail's ↗, is now a real link (`target=_blank`) instead of a button that
+  called `window.open`, which Safari's popup blocker stopped. The panel
+  also holds its 5 s repaint while a pointer is down in it, so a click
+  is never lost to a repaint between press and release.
+- **Signing in from another machine (D29).** On an unclaimed Den with
+  `web.owner_github` set, "Sign in as @login" is the primary button. The
+  button that only works on the Den machine says so: "On <host> itself:
+  connect GitHub". With only `web.allowed_github_org`, the page says to
+  open it on that machine, or to set `web.owner_github`.
+- **Rotation overrides are picked by name (D30).** Settings › Agents ›
+  Rotation's Add override form has searchable pickers (type to filter,
+  arrow keys, Enter) for the agent, persona, workspace or service, and a
+  choice for each value, never a typed id. The overrides table shows
+  names; an override for something that is gone is greyed, with Remove.
+  At 375 px the table stacks into cards, so no word breaks mid-letter.
+- **doctor, where it runs.** In login mode (as installed), the server and
+  session host in the desktop session show ℹ, not ⚠. An older session
+  host still serving, with the service's own host standing by, is ℹ
+  "Nothing to do", not "unknown ✓". The version-manager node warning at
+  `service install` prints once, for the web job.
+
+## [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

package/docs/distributions.md

@@ -1969,6 +1969,14 @@ terminal and agent) as launchd jobs, restarted if they exit:
 ./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                            |
@@ -3296,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
@@ -3332,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.22",
+  "version": "0.4.24",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/service/install.sh

@@ -110,8 +110,9 @@ pick_node() {
   done
   # Warn when installing; `print` writes the plist and nothing else.
   if [ "${1:-}" = install ]; then
-    echo "⚠ the service will run $node, a version manager's node: it stops starting" >&2
-    echo "  when that version is removed. Re-run install after switching, or set DEN_SERVICE_NODE." >&2
+    echo "⚠ the web job will run $node, a version manager's node: it stops starting" >&2
+    echo "  when that version is removed (the session host runs Den's own copy of node)." >&2
+    echo "  Re-run install after switching, or set DEN_SERVICE_NODE." >&2
   fi
   echo "$node"
 }
@@ -165,7 +166,8 @@ host_exe() { # $1 node
 }
 
 write_plist() { # $1 = output file, $2 = web|host, $3 = mode
-  NODE="$(pick_node "$MODE")"
+  # Warned once, for the web job: the host job runs Den's node copy.
+  NODE="$(pick_node "$([ "$2" = web ] && echo "$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

package/src/shared/agents/guardrails/rotation-hook.ts

@@ -59,6 +59,11 @@ export function rotationHookOutput(
   now: Date = new Date(),
 ): string {
   if (!input || typeof input !== "object") return "";
+  // D28: the limit in force is the one Den keeps in rotation.json (it
+  // follows the settings); the launch's --after is the first one.
+  const stored = readRotation(args.files);
+  if (stored && stored.after !== args.after)
+    args = { ...args, after: stored.after };
   const i = input as Record<string, unknown>;
   const event = i.hook_event_name;
   const conversation =

package/src/shared/agents/rotate-settings.ts

@@ -0,0 +1,309 @@
+/**
+ * D28: session-rotation settings and where each comes from.
+ *
+ *   after_compactions  a whole number (1–100), or "never"; default 3
+ *   on_due             auto | ask | off; default auto
+ *                        auto: Den asks the agent for its handoff at its next
+ *                              idle and relaunches it from it by itself
+ *                        ask:  the callout's buttons (Relaunch now, Write
+ *                              handoff, Keep this conversation, Settings)
+ *                        off:  nothing happens; the count is still shown
+ *   on_pr_merged       true | false; default true
+ *
+ * Scopes, the most specific wins, each key on its own:
+ *   agent › persona in a workspace › persona › workspace › service (the
+ *   workspace service whose folder holds the agent's) › install (Settings ›
+ *   Agents › Rotation, this machine) › org (`agents.rotate` in the org
+ *   config) › Den's default.
+ *
+ * The install value and every override live in
+ * `<stateDir>/agent-rotation.json` (0600; never under agents/, where every
+ * file is an agent's record). The org value is the org config's.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { writePrivate } from "./records.js";
+
+export type OnDue = "auto" | "ask" | "off";
+
+/** One scope's settings, as written: any key may be absent. */
+export interface RotateValues {
+  after_compactions?: number | "never";
+  on_due?: OnDue;
+  on_pr_merged?: boolean;
+}
+
+export type RotateKey = keyof RotateValues;
+export const ROTATE_KEYS: readonly RotateKey[] = [
+  "after_compactions",
+  "on_due",
+  "on_pr_merged",
+];
+
+/** The scopes an override can be set at (most specific first). */
+export const OVERRIDE_SCOPES = [
+  "agent",
+  "persona-workspace",
+  "persona",
+  "workspace",
+  "service",
+] as const;
+export type OverrideScope = (typeof OVERRIDE_SCOPES)[number];
+export type RotateScope = OverrideScope | "install" | "org" | "default";
+
+export const ROTATE_DEFAULTS: Required<RotateValues> = {
+  after_compactions: 3,
+  on_due: "auto",
+  on_pr_merged: true,
+};
+
+/** `<stateDir>/agent-rotation.json`. */
+export interface RotateFile {
+  install?: RotateValues;
+  overrides?: Partial<Record<OverrideScope, Record<string, RotateValues>>>;
+}
+
+/** Who an agent is, for resolving its settings. */
+export interface RotateSubject {
+  agent: string;
+  persona: string;
+  workspace: string;
+  /** The workspace service whose folder holds the agent's, if any. */
+  service?: string;
+  /** A standing persona (planner, orchestrator): `standing: false` in the org config keeps it from rotating. */
+  standing?: boolean;
+}
+
+/** Where a value came from: "default", or a scope and its target. */
+export interface RotateSource {
+  scope: RotateScope;
+  /** The agent id, persona, "persona@workspace", workspace or service. */
+  target?: string;
+}
+
+export interface EffectiveRotate {
+  /** 0: never rotates. */
+  afterCompactions: number;
+  onDue: OnDue;
+  onPrMerged: boolean;
+  source: Record<RotateKey, RotateSource>;
+}
+
+/** The org config's `agents.rotate`, checked (den-config.ts). */
+export interface OrgRotate extends RotateValues {
+  /** Dropped by D28 (persona scope replaces it); still honoured. */
+  standing?: boolean;
+}
+
+export const rotateFilePath = (stateDir: string) =>
+  path.join(stateDir, "agent-rotation.json");
+
+/**
+ * One value checked: the problem in words, or null. `after_compactions`
+ * takes 1–100 or "never" (0 also means never, from the CLI).
+ */
+export function checkRotateValue(key: string, v: unknown): string | null {
+  if (key === "after_compactions")
+    return v === "never" ||
+      (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 100)
+      ? null
+      : `after_compactions: a whole number from 1 to 100, or never (got ${JSON.stringify(v)})`;
+  if (key === "on_due")
+    return v === "auto" || v === "ask" || v === "off"
+      ? null
+      : `on_due: auto, ask or off (got ${JSON.stringify(v)})`;
+  if (key === "on_pr_merged")
+    return typeof v === "boolean"
+      ? null
+      : `on_pr_merged: true or false (got ${JSON.stringify(v)})`;
+  return `${key}: unknown key (takes ${ROTATE_KEYS.join(", ")})`;
+}
+
+/** A command-line value as the key takes it ("3", "never", "ask", "false"). */
+export function parseRotateValue(key: string, raw: string): unknown {
+  if (key === "after_compactions")
+    return raw === "never" || raw === "0"
+      ? "never"
+      : /^\d+$/.test(raw)
+        ? Number(raw)
+        : raw;
+  if (key === "on_pr_merged")
+    return raw === "true" ? true : raw === "false" ? false : raw;
+  return raw;
+}
+
+/** Only the valid keys of `v` (a bad file never breaks an agent). */
+function cleanValues(v: unknown): RotateValues {
+  const out: RotateValues = {};
+  if (!v || typeof v !== "object" || Array.isArray(v)) return out;
+  for (const k of ROTATE_KEYS) {
+    const x = (v as Record<string, unknown>)[k];
+    if (x !== undefined && checkRotateValue(k, x) === null)
+      (out as Record<string, unknown>)[k] = x;
+  }
+  return out;
+}
+
+/** agent-rotation.json, cleaned; {} when absent or unreadable. */
+export function readRotateFile(stateDir: string): RotateFile {
+  let v: unknown;
+  try {
+    v = JSON.parse(fs.readFileSync(rotateFilePath(stateDir), "utf-8"));
+  } catch {
+    return {};
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v)) return {};
+  const o = v as Record<string, unknown>;
+  const out: RotateFile = {};
+  const inst = cleanValues(o.install);
+  if (Object.keys(inst).length) out.install = inst;
+  if (o.overrides && typeof o.overrides === "object") {
+    const ov: RotateFile["overrides"] = {};
+    for (const scope of OVERRIDE_SCOPES) {
+      const byTarget = (o.overrides as Record<string, unknown>)[scope];
+      if (!byTarget || typeof byTarget !== "object") continue;
+      for (const [target, vals] of Object.entries(byTarget)) {
+        const c = cleanValues(vals);
+        if (Object.keys(c).length) (ov[scope] ??= {})[target] = c;
+      }
+    }
+    if (Object.keys(ov).length) out.overrides = ov;
+  }
+  return out;
+}
+
+export function writeRotateFile(stateDir: string, f: RotateFile): void {
+  fs.mkdirSync(path.dirname(rotateFilePath(stateDir)), {
+    recursive: true,
+    mode: 0o700,
+  });
+  writePrivate(rotateFilePath(stateDir), JSON.stringify(f, null, 2) + "\n");
+}
+
+/**
+ * Set (or with `value` undefined, clear) one key at one scope. `scope`
+ * "install" takes no target. Throws, naming the problem, on a bad key or
+ * value. Returns the file as written.
+ */
+export function setRotateValue(
+  stateDir: string,
+  scope: OverrideScope | "install",
+  target: string | undefined,
+  key: string,
+  value: unknown,
+): RotateFile {
+  if (value !== undefined) {
+    const bad = checkRotateValue(key, value);
+    if (bad) throw new Error(bad);
+  } else if (!(ROTATE_KEYS as readonly string[]).includes(key))
+    throw new Error(checkRotateValue(key, undefined)!);
+  if (scope !== "install" && !target)
+    throw new Error(`a ${scope} override needs the ${scope} it is for`);
+  const f = readRotateFile(stateDir);
+  const k = key as RotateKey;
+  const apply = (vals: RotateValues | undefined): RotateValues => {
+    const next: RotateValues = { ...(vals ?? {}) };
+    if (value === undefined) delete next[k];
+    else (next as Record<string, unknown>)[k] = value;
+    return next;
+  };
+  if (scope === "install") {
+    const next = apply(f.install);
+    if (Object.keys(next).length) f.install = next;
+    else delete f.install;
+  } else {
+    const ov = (f.overrides ??= {});
+    const byTarget = (ov[scope] ??= {});
+    const next = apply(byTarget[target!]);
+    if (Object.keys(next).length) byTarget[target!] = next;
+    else delete byTarget[target!];
+    if (!Object.keys(byTarget).length) delete ov[scope];
+    if (!Object.keys(ov).length) delete f.overrides;
+  }
+  writeRotateFile(stateDir, f);
+  return f;
+}
+
+/** The target an override scope uses for `s`, or undefined. */
+export function targetFor(
+  scope: OverrideScope,
+  s: RotateSubject,
+): string | undefined {
+  switch (scope) {
+    case "agent":
+      return s.agent;
+    case "persona-workspace":
+      return `${s.persona}@${s.workspace}`;
+    case "persona":
+      return s.persona;
+    case "workspace":
+      return s.workspace;
+    case "service":
+      return s.service;
+  }
+}
+
+/** Agent `s`'s settings, each key from the most specific scope that sets it. */
+export function resolveRotate(
+  s: RotateSubject,
+  file: RotateFile,
+  org: OrgRotate | undefined,
+): EffectiveRotate {
+  const layers: { source: RotateSource; values: RotateValues }[] = [];
+  for (const scope of OVERRIDE_SCOPES) {
+    const target = targetFor(scope, s);
+    const values = target ? file.overrides?.[scope]?.[target] : undefined;
+    if (values) layers.push({ source: { scope, target }, values });
+  }
+  if (file.install)
+    layers.push({ source: { scope: "install" }, values: file.install });
+  if (org) {
+    const values: RotateValues = { ...org };
+    delete (values as OrgRotate).standing;
+    // den#4's `standing: false`: standing personas never rotate.
+    if (org.standing === false && s.standing)
+      values.after_compactions = "never";
+    layers.push({ source: { scope: "org" }, values });
+  }
+  const pick = <K extends RotateKey>(k: K) => {
+    for (const l of layers)
+      if (l.values[k] !== undefined)
+        return {
+          v: l.values[k] as Required<RotateValues>[K],
+          source: l.source,
+        };
+    return {
+      v: ROTATE_DEFAULTS[k],
+      source: { scope: "default" } as RotateSource,
+    };
+  };
+  const a = pick("after_compactions");
+  const o = pick("on_due");
+  const p = pick("on_pr_merged");
+  return {
+    afterCompactions: a.v === "never" ? 0 : a.v,
+    onDue: o.v,
+    onPrMerged: p.v,
+    source: {
+      after_compactions: a.source,
+      on_due: o.source,
+      on_pr_merged: p.source,
+    },
+  };
+}
+
+/** "persona planner", "agent art", "this install", "org config", "default". */
+export function sourceText(src: RotateSource): string {
+  switch (src.scope) {
+    case "default":
+      return "default";
+    case "install":
+      return "this install";
+    case "org":
+      return "org config";
+    case "persona-workspace":
+      return `persona ${src.target!.replace("@", " in ")}`;
+    default:
+      return `${src.scope} ${src.target}`;
+  }
+}