grant manage_root_agent by stored permission only, not by the name ruth

Permission::default_for and hive-sh4re's MANAGER_AGENT are gone: every
agent with no permissions key holds Permission::DEFAULT, ruth included.
The agent-name parameters that only fed default_for go with it
(permissions::effective, HiveCopy::before_read/after_read and their
callers).

swarm-controller seeds the grant ruth held by name: at start, a declared
ruth whose permissions are unset gets DEFAULT plus manage_root_agent
written into her key, once, logged. A set key is never touched. It is a
one-shot to delete once every swarm has passed it.

The swarm UI setup assistant opens the create form with
manage_root_agent checked, so a new ruth is created with the grant.
permissions_import no longer adds ruth to the import or splits her
default. Docs and help text no longer say ruth holds the grant by
default; swarmctl-cli.md regenerated.

frontend/packages/swarm-ui/src/pages/CreateAgentForm.tsx

@@ -26,8 +26,8 @@
 // shared `ui/` form kit (`TextField`/`SelectField`/`Button`) rather than
 // page-scoped input/button chrome — see that kit's own comments for why.
 //
-// Permissions: checkboxes from `GET /api/permissions`, on the default set;
-// sent only when changed, so an untouched agent follows the default.
+// Permissions: checkboxes from `GET /api/permissions`, on the default set plus
+// `extraPermissions`; sent only when that differs from the default.
 import { useEffect, useState } from "preact/hooks";
 import { Link } from "wouter-preact";
 import { ApiErrorPanel } from "@hive/shared/api-error-panel.js";
@@ -50,6 +50,7 @@ import {
 import { FormField } from "../ui/form-field/FormField.js";
 import { MultiselectFilterOptions } from "../ui/multiselect-filter/MultiselectFilter.js";
 import {
+  initialSelection,
   requestPermissions,
   togglePermission,
 } from "./CreateAgentPermissions.js";
@@ -98,9 +99,12 @@ const NAME_PATTERN = "[a-z0-9\\-]{1,63}";
 export function CreateAgentForm({
   onClose,
   initialName = "",
+  extraPermissions = [],
 }: {
   /** The name field's starting value, for a caller that suggests one. */
   initialName?: string;
+  /** Permissions checked on top of the default set when the form opens. */
+  extraPermissions?: string[];
   /** Rendered as the form panel's own close button — this form always
    * mounts inside a `plain` `Dialog` (see `AgentsPage`), which no longer
    * floats its own. */
@@ -157,7 +161,7 @@ export function CreateAgentForm({
       }
       const data = (await r.json()) as PermissionCatalogue;
       setCatalogue(data);
-      setSelected(data.default);
+      setSelected(initialSelection(data.all, data.default, extraPermissions));
     })().catch((e: unknown) => setCatalogueError({ detail: String(e) }));
   }, []);
 
@@ -195,7 +199,10 @@ export function CreateAgentForm({
       const data = (await r.json()) as CreateAgentResponse;
       setResult({ status: "done", nodeId: data.node_id });
       setName("");
-      if (catalogue) setSelected(catalogue.default);
+      if (catalogue)
+        setSelected(
+          initialSelection(catalogue.all, catalogue.default, extraPermissions),
+        );
     } catch (err) {
       setResult({ status: "error", problem: { detail: String(err) } });
     }

frontend/packages/swarm-ui/src/pages/CreateAgentPermissions.ts

@@ -22,3 +22,19 @@ export function requestPermissions(
     selected.every((p) => defaults.includes(p));
   return same ? undefined : selected;
 }
+
+/**
+ * The form's starting selection: `defaults` plus each of `extra` the
+ * catalogue lists (`all`), so a name the controller does not know is not
+ * sent.
+ */
+export function initialSelection(
+  all: string[],
+  defaults: string[],
+  extra: string[],
+): string[] {
+  return [
+    ...defaults,
+    ...extra.filter((p) => all.includes(p) && !defaults.includes(p)),
+  ];
+}

frontend/packages/swarm-ui/src/pages/SetupAssistant.tsx

@@ -1,11 +1,15 @@
 // <SetupAssistant> - the start page's first-time helper: a paperclip with a
 // speech bubble offering to set up an agent. It renders only while the swarm
 // has no `ruth` (see `ruthIsMissing`), and a click opens the create-agent
-// form with her name filled in; the form already selects the default
-// permissions and the only hive. No dismiss: once ruth exists it goes away.
+// form with her name filled in and `manage_root_agent` checked on top of the
+// default permissions (`RUTH_EXTRA_PERMISSIONS`); the form already selects
+// the only hive. No dismiss: once ruth exists it goes away.
 import { useEffect, useState } from "preact/hooks";
 import { Dialog } from "../ui/dialog/Dialog.js";
-import { ruthIsMissing } from "../shell/ruth-missing.js";
+import {
+  RUTH_EXTRA_PERMISSIONS,
+  ruthIsMissing,
+} from "../shell/ruth-missing.js";
 import { CreateAgentForm } from "./CreateAgentForm.js";
 import "./SetupAssistant.css";
 
@@ -70,7 +74,11 @@ export function SetupAssistant() {
         label="create agent"
         plain
       >
-        <CreateAgentForm initialName="ruth" onClose={() => setOpen(false)} />
+        <CreateAgentForm
+          initialName="ruth"
+          extraPermissions={RUTH_EXTRA_PERMISSIONS}
+          onClose={() => setOpen(false)}
+        />
       </Dialog>
     </>
   );

frontend/packages/swarm-ui/src/shell/ruth-missing.ts

@@ -20,3 +20,7 @@ export async function ruthIsMissing(fetchImpl: Fetch): Promise<boolean> {
     return false;
   }
 }
+
+/** What the setup assistant's create form checks on top of the default set:
+ * ruth recovers the other agents, which takes `manage_root_agent`. */
+export const RUTH_EXTRA_PERMISSIONS = ["manage_root_agent"];

frontend/packages/swarm-ui/test/create-agent-permissions.test.mjs

@@ -3,6 +3,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import {
+  initialSelection,
   requestPermissions,
   togglePermission,
 } from "../src/pages/CreateAgentPermissions.ts";
@@ -29,3 +30,17 @@ test("a changed set is sent, an empty one included", () => {
     "web_tools",
   ]);
 });
+
+const all = [...defaults, "web_tools", "manage_root_agent"];
+
+test("the starting selection is the default plus the known extras", () => {
+  assert.deepEqual(initialSelection(all, defaults, []), defaults);
+  assert.deepEqual(initialSelection(all, defaults, ["manage_root_agent"]), [
+    ...defaults,
+    "manage_root_agent",
+  ]);
+  assert.deepEqual(
+    initialSelection(all, defaults, ["meta", "fly_to_the_moon"]),
+    defaults,
+  );
+});

frontend/packages/swarm-ui/test/ruth-missing.test.mjs

@@ -1,7 +1,15 @@
-// The setup assistant's "is ruth missing" check. Run by `npm test`.
+// The setup assistant: its "is ruth missing" check and the permissions it
+// creates her with. Run by `npm test`.
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { ruthIsMissing } from "../src/shell/ruth-missing.ts";
+import {
+  RUTH_EXTRA_PERMISSIONS,
+  ruthIsMissing,
+} from "../src/shell/ruth-missing.ts";
+import {
+  initialSelection,
+  requestPermissions,
+} from "../src/pages/CreateAgentPermissions.ts";
 
 const answering =
   (body, ok = true) =>
@@ -35,3 +43,21 @@ test("anything but a clear answer is not missing", async () => {
     false,
   );
 });
+
+// The assistant's create form sends `manage_root_agent` with the default
+// set, so a new ruth holds it from her first start; the default alone does not.
+test("the assistant creates ruth with manage_root_agent", () => {
+  const defaults = ["messaging", "meta", "inbox", "execution"];
+  const all = [...defaults, "web_tools", "manage_root_agent"];
+  assert.deepEqual(
+    requestPermissions(
+      initialSelection(all, defaults, RUTH_EXTRA_PERMISSIONS),
+      defaults,
+    ),
+    [...defaults, "manage_root_agent"],
+  );
+  assert.equal(
+    requestPermissions(initialSelection(all, defaults, []), defaults),
+    undefined,
+  );
+});