@ouro.bot/cli 0.1.0-alpha.836 → 0.1.0-alpha.839

package/changelog.json

@@ -1,6 +1,25 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.839",
+      "changes": [
+        "CLI: provision A2A peers without editing files. ouro connect a2a --host/--port/--public-url stores this machine's A2A bind address and advertised URL (D-038); ouro a2a onboard --did <did:key> --name <name> onboards a card-less client such as a coding harness, keyed on its DID; ouro friend update sets --admission, --initiative and --profile as well as --trust (D-039).",
+        "CLI: a2a onboard keeps the card and DID paths in one command block so its coverage exemptions stay attached to the right code."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.838",
+      "changes": [
+        "Upgrade orchestrator: pausing host supervision first installs this version's keeper scripts and raises the shutdown flag every watchdog honours, so an older keeper can no longer restart the resident mid-upgrade (found by the first 830 to 835 rehearsal, which rolled back cleanly). A rehearsal now reports an unplanned failure as a failure instead of as the planned stop."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.837",
+      "changes": [
+        "Sanctuary: the root authority keeps a permanent empty child cgroup (ouro-keep), so Unraid's cgroup2-unraid can no longer remove the authority cgroup (D-026). The host keeper now lets the reaper run and pauses it only while the keep child is missing; every reader of the authority cgroup ignores the keep child."
+      ]
+    },
     {
       "version": "0.1.0-alpha.836",
       "changes": [

package/deploy/unraid/sanctuary-butler-upgrade.mjs

@@ -59,6 +59,8 @@ const UPGRADE_JOURNAL = `${ROOT}/upgrade.json`
 // Host supervision skips its work while this flag is fresh (< 30 min), so a crashed
 // upgrade can never leave self-heal off for longer than that.
 const MAINTENANCE = "/run/ouro-authority-maintenance"
+// The stop hook's flag: every keeper watchdog version stands down while it exists.
+const SHUTDOWN_FLAG = "/run/ouro-authority-shutdown"
 const UPGRADE_STEPS = ["stop", "switch", "resident", "migrate", "start"]
 
 const sh = (file, args, opts = {}) => execFileSync(file, args, { encoding: "utf8", maxBuffer: 64 << 20, ...opts })
@@ -428,12 +430,13 @@ const GATEWAY_SUPERVISOR = `${AUTHORITY_CUSTOM}/gateway-supervisor.sh`
 const GATEWAY_WATCHDOG = `${AUTHORITY_CUSTOM}/gateway-keeper-watchdog.sh`
 const UNRAID_STOP_HOOK = "/boot/config/stop"
 const GATEWAY_SUPERVISOR_SH = String.raw`#!/bin/sh
-# Ouro authority gateway keeper for Unraid (D-026 workaround).
-# The .830 root-authority gateway needs /sys/fs/cgroup/ouro-authority to persist while it
-# runs, but Unraid's cgroup2-unraid reaps empty cgroups and the gateway never populates it,
-# so the reaper deletes the cgroup and kills the gateway. A FIRM (not per-loop-racing) reaper
-# pause is required for the gateway to reach readiness. This keeper:
-#   - firmly pauses the reaper and keeps it paused,
+# Ouro authority gateway keeper for Unraid.
+# The root-authority gateway needs /sys/fs/cgroup/ouro-authority to persist, and Unraid's
+# cgroup2-unraid removes every top-level cgroup that reports populated 0. The kernel will not
+# remove a cgroup that has a child cgroup, so the authority keeps an empty ouro-keep child
+# (D-026). This keeper:
+#   - creates that keep child and lets the reaper run; it pauses the reaper only while the
+#     keep child is missing (a fresh boot, or an authority older than the keep child),
 #   - keeps the gateway process alive,
 #   - reconnects the resident (docker restart) if it is unhealthy while the gateway is ready
 #     (handles reboot ordering, where Docker autostarts the resident before the gateway).
@@ -443,15 +446,17 @@ R=/mnt/user/appdata/ouro-authority
 GW=$R/package/dist/heart/daemon/sanctuary-telegram-authority-entry.js
 CFG=$R/active.json
 LOG=/var/log/ouro-gateway.log
-pause_reaper() {
+reaper_policy() {
   P=$(cat /run/cgroup2-unraid.pid 2>/dev/null) || return 0
   [ -n "$P" ] || return 0
+  if [ -d "$CG/ouro-keep" ]; then kill -CONT "$P" 2>/dev/null; return 0; fi
   S=$(ps -o stat= -p "$P" 2>/dev/null | tr -d ' ')
   case "$S" in T*) : ;; *) kill -STOP "$P" 2>/dev/null ;; esac
 }
 ensure_cg() {
   [ -d "$CG" ] || { mkdir -m 700 "$CG" 2>/dev/null; chown 0:0 "$CG" 2>/dev/null
     for c in cpu memory pids; do echo "+$c" > "$CG/cgroup.subtree_control" 2>/dev/null; done; }
+  [ -d "$CG/ouro-keep" ] || mkdir -m 700 "$CG/ouro-keep" 2>/dev/null
 }
 ensure_sock() {
   # Docker autostarts the resident before us and auto-creates its missing bind
@@ -475,12 +480,12 @@ start_gw() {
 }
 # An in-place upgrade pauses us with a flag; a stale flag (> 30 min) is ignored.
 maintenance() { [ -n "$(find /run/ouro-authority-maintenance -mmin -30 2>/dev/null)" ]; }
-pause_reaper; ensure_cg; ensure_sock
+ensure_cg; reaper_policy; ensure_sock
 last_res=0
 while true; do
   if maintenance; then sleep 15; continue; fi
-  pause_reaper
   ensure_cg
+  reaper_policy
   ensure_sock
   [ -n "$(gw_pid)" ] || { start_gw; sleep 8; }
   rd=$(jq -rc .status "$R"/epochs/*/readiness.json 2>/dev/null)
@@ -779,13 +784,25 @@ function buildFinalProof(version, out) {
 
 // ---- upgrade (in place, installed authority) --------------------------------
 
+// A host still running an older keeper has a cron watchdog that ignores the maintenance
+// flag: it resurrected the paused supervisor, which restarted the resident mid-upgrade
+// (the first 830 -> 835 rehearsal). So put this version's keeper scripts in place first
+// (they honour the flag) and also raise the shutdown flag every watchdog version honours;
+// resumeSupervision clears both.
 function pauseSupervision() {
   writeFileSync(MAINTENANCE, `${new Date().toISOString()} ${process.pid}\n`)
+  writeFileSync(SHUTDOWN_FLAG, `upgrade ${process.pid}\n`)
+  for (const [path, body] of [[GATEWAY_SUPERVISOR, GATEWAY_SUPERVISOR_SH], [GATEWAY_WATCHDOG, GATEWAY_WATCHDOG_SH]]) {
+    writeFileSync(path, body)
+    sh("/bin/chown", ["0:0", path]); chmodSync(path, 0o700)
+  }
   sh("/bin/sh", ["-c", "for p in $(pgrep -f '^/bin/sh /boot/config/custom/ouro-authority/[g]ateway-supervisor' || true); do kill $p; done"])
-  ok("host supervision paused (its flag expires on its own after 30 min)")
+  if (sh("/bin/sh", ["-c", "pgrep -fc '^/bin/sh /boot/config/custom/ouro-authority/[g]ateway-supervisor' || true"]).trim() !== "0") fail("a gateway supervisor survived the pause")
+  ok("host supervision paused (keeper scripts current; flags expire on their own)")
 }
 function resumeSupervision() {
   rmSync(MAINTENANCE, { force: true })
+  rmSync(SHUTDOWN_FLAG, { force: true })
   installGatewaySupervisor()
 }
 
@@ -836,8 +853,12 @@ function upgrade(version, rehearse) {
     say("lifecycle upgrade (stop → switch → resident → migrate → start)")
     ok(sh("/usr/local/bin/node", [lifecycle, "upgrade", id, image(version), ...(rehearse ? ["--fail-after", rehearse] : [])], { stdio: ["ignore", "pipe", "pipe"] }).trim())
   } catch (e) { failure = e }
+  // Only the lifecycle's own rehearsal stop is planned; anything else is a real failure,
+  // even during a rehearsal (the first 830 -> 835 rehearsal was mislabelled "as planned").
+  const reason = failure ? lifecycleFailure(failure) : ""
+  const planned = Boolean(failure && rehearse && reason.includes(`rehearsal stopped after ${rehearse}`))
   if (failure) {
-    console.log(`\n!! ${rehearse ? "rehearsal stopped as planned" : "upgrade failed"}: ${lifecycleFailure(failure)}\n!! rolling back to the predecessor`)
+    console.log(`\n!! ${planned ? "rehearsal stopped as planned" : "upgrade FAILED"}: ${reason}\n!! rolling back to the predecessor`)
     try { ok(`rollback: ${sh("/usr/local/bin/node", [lifecycle, "upgrade-rollback"], { stdio: ["ignore", "pipe", "pipe"] }).trim()}`) }
     catch (e) {
       resumeSupervision()
@@ -850,8 +871,8 @@ function upgrade(version, rehearse) {
   sha12(POLICY) === policyBefore ? ok("steward policy unchanged") : fail("STEWARD POLICY CHANGED")
   const live = docker(["inspect", CONTAINER, "--format", "{{.Config.Image}} {{.State.Status}}/{{.State.Health.Status}}"]).trim()
   ok(`butler: ${live}`)
-  if (failure && !rehearse) fail("upgrade rolled back; the Butler is on its prior version (see above)")
-  console.log(rehearse ? "\nREHEARSAL done — the rollback restored the predecessor." : `\nUPGRADE done — ${version} live. Run verify.`)
+  if (failure && !planned) fail("upgrade rolled back; the Butler is on its prior version (see above)")
+  console.log(rehearse ? "\nREHEARSAL done — the upgrade reached the planned step and the rollback restored the predecessor." : `\nUPGRADE done — ${version} live. Run verify.`)
 }
 
 // ---- verify ---------------------------------------------------------------

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.836",
+  "runtimeVersion": "0.1.0-alpha.839",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.836</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.839</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/a2a/onboarding.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.onboardA2APeer = onboardA2APeer;
+exports.onboardA2AClientByDid = onboardA2AClientByDid;
 const path = __importStar(require("node:path"));
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
@@ -108,3 +109,25 @@ async function onboardA2APeer(options) {
     });
     return record;
 }
+/**
+ * Onboard a client that serves no agent card (for example a coding harness with a
+ * file-backed identity) by its did:key alone. The record is keyed on the DID, so its
+ * signed, sealed messages resolve to this friend; the key must parse, or nothing is written.
+ */
+async function onboardA2AClientByDid(options) {
+    if ((0, a2a_client_1.parseDidKey)(options.did) === null)
+        throw new Error(`not a valid did:key: ${options.did}`);
+    const record = await (0, friends_1.upsertAgentPeer)(storeFor(options), {
+        name: options.name,
+        agentId: options.did,
+        ...(options.trustLevel ? { trustLevel: options.trustLevel } : {}),
+        a2a: { did: options.did, agentId: options.did },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.a2a_client_onboarded",
+        message: "onboarded card-less A2A client into friend model",
+        meta: { agentName: options.agentName, friendId: record.id, peerName: record.name, trustLevel: record.trustLevel, did: options.did },
+    });
+    return record;
+}

package/dist/heart/daemon/cli-exec.js

@@ -5053,13 +5053,23 @@ async function executeConnectVoice(agent, deps) {
     deps.writeStdout(message);
     return message;
 }
-async function executeConnectA2A(agent, deps) {
+async function executeConnectA2A(agent, deps, bind = {}) {
     const { defaultA2APort } = await Promise.resolve().then(() => __importStar(require("../../a2a/config")));
     enableAgentSense(agent, "a2a", deps);
     const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
-    const port = defaultA2APort(agent);
+    // Bind address, port and advertised URL are per machine (D-038): a tailnet IP on one
+    // host means nothing on another, so they live in this machine's runtime config.
+    const a2a = {
+        ...(bind.host !== undefined ? { host: bind.host } : {}),
+        ...(bind.port !== undefined ? { port: bind.port } : {}),
+        ...(bind.publicUrl !== undefined ? { publicUrl: bind.publicUrl } : {}),
+    };
+    if (Object.keys(a2a).length > 0)
+        await (0, runtime_credentials_1.mergeMachineRuntimeCredentialConfig)(agent, currentMachineId(deps), { a2a }, providerCliNow(deps));
+    const port = bind.port ?? defaultA2APort(agent);
     const message = [
         `A2A connected for ${agent}`,
+        ...(Object.keys(a2a).length > 0 ? [`This machine's A2A listener: ${bind.host ?? "127.0.0.1"}:${port}${bind.publicUrl ? `, advertised as ${bind.publicUrl}` : ""} (applies on the next \`ouro up\`).`] : []),
         `The daemon-managed A2A sense will listen locally on port ${port} after \`ouro up\`.`,
         `Local agent card: http://127.0.0.1:${port}/.well-known/agent-card.json`,
         `Local JSON-RPC endpoint: http://127.0.0.1:${port}/a2a`,
@@ -5184,7 +5194,7 @@ async function executeConnect(command, deps) {
     if (command.target === "voice")
         return executeConnectVoice(command.agent, deps);
     if (command.target === "a2a")
-        return executeConnectA2A(command.agent, deps);
+        return executeConnectA2A(command.agent, deps, { host: command.a2aHost, port: command.a2aPort, publicUrl: command.a2aPublicUrl });
     if (command.target === "telegram")
         return executeConnectTelegram(command.agent, deps);
     if (command.target === "workbench")
@@ -6034,10 +6044,26 @@ async function executeFriendCommand(command, store) {
         return `created: ${id} (${command.name}, ${trustLevel})`;
     }
     if (command.kind === "friend.update") {
-        const result = await (0, friends_1.setFriendTrust)(store, command.friendId, command.trustLevel);
-        if (result.status === "not_found")
+        if (!await store.get(command.friendId))
             return `friend not found: ${command.friendId}`;
-        return `updated: ${command.friendId} → trust=${command.trustLevel}`;
+        if (command.trustLevel)
+            await (0, friends_1.setFriendTrust)(store, command.friendId, command.trustLevel);
+        const relationship = {
+            ...(command.admissionState ? { admissionState: command.admissionState } : {}),
+            ...(command.initiativePolicy ? { initiativePolicy: command.initiativePolicy } : {}),
+            ...(command.capabilityProfileId ? { capabilityProfileId: command.capabilityProfileId } : {}),
+        };
+        if (Object.keys(relationship).length > 0) {
+            const current = (await store.get(command.friendId));
+            await store.put(command.friendId, { ...current, ...relationship, updatedAt: new Date().toISOString() });
+        }
+        const changed = [
+            command.trustLevel ? `trust=${command.trustLevel}` : "",
+            command.admissionState ? `admission=${command.admissionState}` : "",
+            command.initiativePolicy ? `initiative=${command.initiativePolicy}` : "",
+            command.capabilityProfileId ? `profile=${command.capabilityProfileId}` : "",
+        ].filter(Boolean).join(", ");
+        return `updated: ${command.friendId} → ${changed}`;
     }
     if (command.kind === "friend.link") {
         const result = await (0, friends_1.linkExternalId)(store, command.friendId, {
@@ -6107,6 +6133,27 @@ async function executeA2ACommand(command, deps) {
     }
     /* v8 ignore next -- false branch is foreground serve, intentionally ignored below because it waits for signals @preserve */
     if (command.kind === "a2a.onboard") {
+        if (command.did) {
+            const { onboardA2AClientByDid } = await Promise.resolve().then(() => __importStar(require("../../a2a/onboarding")));
+            const record = await onboardA2AClientByDid({
+                agentName: command.agent,
+                did: command.did,
+                name: command.name,
+                ...(command.trustLevel ? { trustLevel: command.trustLevel } : {}),
+                /* v8 ignore next -- production CLI falls back to the canonical bundle root; tests inject isolated roots @preserve */
+                ...(deps.bundlesRoot ? { bundlesRoot: deps.bundlesRoot } : {}),
+            });
+            const message = [
+                `onboarded A2A client: ${record.name}`,
+                `friend id: ${record.id}`,
+                /* v8 ignore next -- upsertAgentPeer always writes an explicit TrustLevel @preserve */
+                `trust: ${record.trustLevel ?? "unknown"}`,
+                `did: ${command.did}`,
+                `Next: ouro friend update ${record.id} --agent ${command.agent} --admission active --initiative reactive_only --profile <capability-profile-id>`,
+            ].join("\n");
+            deps.writeStdout(message);
+            return message;
+        }
         const { onboardA2APeer } = await Promise.resolve().then(() => __importStar(require("../../a2a/onboarding")));
         const record = await onboardA2APeer({
             agentName: command.agent,

package/dist/heart/daemon/cli-help.js

@@ -448,7 +448,7 @@ const SUBCOMMAND_HELP = {
     },
     "connect a2a": {
         description: "Enable the agent-to-agent A2A sense",
-        usage: "ouro connect a2a [--agent <name>]",
+        usage: "ouro connect a2a [--agent <name>] [--host <address>] [--port <port>] [--public-url <url>]",
         example: "ouro connect a2a --agent <agent>",
     },
     "connect telegram": {
@@ -468,7 +468,7 @@ const SUBCOMMAND_HELP = {
     },
     "a2a onboard": {
         description: "Onboard an A2A peer into the existing friend model",
-        usage: "ouro a2a onboard [--agent <name>] --card-url <url> [--trust <level>] [--name <name>]",
+        usage: "ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]",
         example: "ouro a2a onboard --agent <agent> --card-url https://peer.example/.well-known/agent-card.json --trust friend",
     },
     "a2a serve": {

package/dist/heart/daemon/cli-parse.js

@@ -141,7 +141,7 @@ function usage() {
         "  ouro friend list [--agent <name>]",
         "  ouro friend show <id> [--agent <name>]",
         "  ouro friend create --name <name> [--trust <level>] [--agent <name>]",
-        "  ouro friend update <id> --trust <level> [--agent <name>]",
+        "  ouro friend update <id> [--trust <level>] [--admission <state>] [--initiative <policy>] [--profile <id>] [--agent <name>]",
         "  ouro thoughts [--last <n>] [--json] [--follow] [--agent <name>]",
         "  ouro private decisions [--agent <name>] [--limit <n>] [--json]",
         "  ouro private status [--agent <name>] [--json]",
@@ -150,7 +150,7 @@ function usage() {
         "  ouro friend link <agent> --friend <id> --provider <p> --external-id <eid>",
         "  ouro friend unlink <agent> --friend <id> --provider <p> --external-id <eid>",
         "  ouro a2a card [--agent <name>] [--base-url <url>] [--json]",
-        "  ouro a2a onboard [--agent <name>] --card-url <url> [--trust <level>] [--name <name>]",
+        "  ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]",
         "  ouro a2a serve [--agent <name>] [--host <host>] [--port <port>] [--base-url <url>] [--path <path>]",
         "  ouro a2a identity [--identity-file <path>] [--json]",
         "  ouro a2a message --to <card-url> --text <text> [--context <id>] [--identity-file <path>] [--json]",
@@ -1099,20 +1099,58 @@ function extractMailSourceFlags(args, usageText) {
         hasMailSourceFlags,
     };
 }
+// `ouro connect a2a` bind flags: where the listener binds and the URL its card advertises (D-038).
+function extractA2AConnectFlags(args) {
+    const rest = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const value = args[i + 1];
+        if (args[i] === "--host" && value) {
+            flags.host = value;
+            i += 1;
+            continue;
+        }
+        if (args[i] === "--public-url" && value) {
+            const url = new URL(value);
+            if (url.protocol !== "http:" && url.protocol !== "https:")
+                throw new Error("A2A public URL must be http(s)");
+            flags.publicUrl = value.replace(/\/+$/u, "");
+            i += 1;
+            continue;
+        }
+        if (args[i] === "--port" && value) {
+            const port = Number(value);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new Error("A2A port must be 1-65535");
+            flags.port = port;
+            i += 1;
+            continue;
+        }
+        rest.push(args[i]);
+    }
+    return { rest, ...flags };
+}
 function parseConnectCommand(args) {
-    const usageText = "Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]";
+    const usageText = "Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys] [a2a: --host <address> --port <port> --public-url <url>]";
     const { agent, rest: afterAgent } = extractAgentFlag(args);
-    const mailFlags = extractMailSourceFlags(afterAgent, usageText);
+    const a2aFlags = extractA2AConnectFlags(afterAgent);
+    const mailFlags = extractMailSourceFlags(a2aFlags.rest, usageText);
     if (mailFlags.rest.length > 1)
         throw new Error(usageText);
     const target = normalizeConnectTarget(mailFlags.rest[0]);
     if (mailFlags.hasMailSourceFlags && target !== "mail") {
         throw new Error("Mail source flags require `ouro connect mail`.");
     }
+    const hasA2AFlags = a2aFlags.host !== undefined || a2aFlags.port !== undefined || a2aFlags.publicUrl !== undefined;
+    if (hasA2AFlags && target !== "a2a")
+        throw new Error("--host, --port and --public-url require `ouro connect a2a`.");
     return {
         kind: "connect",
         ...(agent ? { agent } : {}),
         ...(target ? { target } : {}),
+        ...(a2aFlags.host !== undefined ? { a2aHost: a2aFlags.host } : {}),
+        ...(a2aFlags.port !== undefined ? { a2aPort: a2aFlags.port } : {}),
+        ...(a2aFlags.publicUrl !== undefined ? { a2aPublicUrl: a2aFlags.publicUrl } : {}),
         ...(mailFlags.ownerEmail !== undefined ? { ownerEmail: mailFlags.ownerEmail } : {}),
         ...(mailFlags.source !== undefined ? { source: mailFlags.source } : {}),
         ...(mailFlags.noDelegatedSource ? { noDelegatedSource: true } : {}),
@@ -1405,25 +1443,30 @@ function parseFriendCommand(args) {
     }
     if (sub === "update") {
         const friendId = rest[0];
+        const usage = "Usage: ouro friend update <id> [--trust <stranger|acquaintance|friend|family>] [--admission <unverified|active|revoked>] [--initiative <none|reactive_only|request_follow_up_only|proactive>] [--profile <capability-profile-id>]";
         if (!friendId)
-            throw new Error(`Usage: ouro friend update <id> --trust <level>`);
-        let trustLevel;
-        /* v8 ignore start -- flag parsing loop: tested via CLI parsing tests @preserve */
-        for (let i = 1; i < rest.length; i++) {
-            if (rest[i] === "--trust" && rest[i + 1]) {
-                trustLevel = rest[i + 1];
-                i += 1;
-            }
-        }
-        /* v8 ignore stop */
-        const VALID_TRUST_LEVELS = new Set(["stranger", "acquaintance", "friend", "family"]);
-        if (!trustLevel || !VALID_TRUST_LEVELS.has(trustLevel)) {
-            throw new Error(`Usage: ouro friend update <id> --trust <stranger|acquaintance|friend|family>`);
+            throw new Error(usage);
+        // Every relationship field an owner provisions, not just trust (D-039).
+        const choices = {
+            "--trust": { key: "trustLevel", values: ["stranger", "acquaintance", "friend", "family"] },
+            "--admission": { key: "admissionState", values: ["unverified", "active", "revoked"] },
+            "--initiative": { key: "initiativePolicy", values: ["none", "reactive_only", "request_follow_up_only", "proactive"] },
+            "--profile": { key: "capabilityProfileId" },
+        };
+        const fields = {};
+        for (let i = 1; i < rest.length; i += 2) {
+            const choice = choices[rest[i]];
+            const value = rest[i + 1];
+            if (!choice || !value || (choice.values && !choice.values.includes(value)))
+                throw new Error(usage);
+            fields[choice.key] = value;
         }
+        if (Object.keys(fields).length === 0)
+            throw new Error(usage);
         return {
             kind: "friend.update",
             friendId,
-            trustLevel: trustLevel,
+            ...fields,
             ...(agent ? { agent } : {}),
         };
     }
@@ -1504,6 +1547,7 @@ function parseA2ACommand(args) {
     }
     if (sub === "onboard") {
         let cardUrl;
+        let did;
         let trustLevel;
         let name;
         const VALID_TRUST_LEVELS = new Set(["stranger", "acquaintance", "friend", "family"]);
@@ -1512,10 +1556,14 @@ function parseA2ACommand(args) {
                 cardUrl = rest[++i];
                 continue;
             }
+            if (rest[i] === "--did" && rest[i + 1]) {
+                did = rest[++i];
+                continue;
+            }
             if (rest[i] === "--trust" && rest[i + 1]) {
                 const raw = rest[++i];
                 if (!VALID_TRUST_LEVELS.has(raw))
-                    throw new Error("Usage: ouro a2a onboard [--agent <name>] --card-url <url> [--trust <stranger|acquaintance|friend|family>] [--name <name>]");
+                    throw new Error("Usage: ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <stranger|acquaintance|friend|family>] [--name <name>]");
                 trustLevel = raw;
                 continue;
             }
@@ -1523,11 +1571,12 @@ function parseA2ACommand(args) {
                 name = rest[++i];
                 continue;
             }
-            throw new Error("Usage: ouro a2a onboard [--agent <name>] --card-url <url> [--trust <level>] [--name <name>]");
+            throw new Error("Usage: ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]");
         }
-        if (!cardUrl)
-            throw new Error("Usage: ouro a2a onboard [--agent <name>] --card-url <url> [--trust <level>] [--name <name>]");
-        return { kind: "a2a.onboard", cardUrl, ...(agent ? { agent } : {}), ...(trustLevel ? { trustLevel } : {}), ...(name ? { name } : {}) };
+        // A client that serves no card (a coding harness) is onboarded by its did:key alone.
+        if (!cardUrl === !did || (did && !name))
+            throw new Error("Usage: ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]");
+        return { kind: "a2a.onboard", ...(cardUrl ? { cardUrl } : { did: did }), ...(agent ? { agent } : {}), ...(trustLevel ? { trustLevel } : {}), ...(name ? { name } : {}) };
     }
     if (sub === "serve") {
         let host;

package/dist/heart/daemon/sanctuary-authority-installation.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANCTUARY_CGROUP_KEEP = void 0;
+exports.sanctuaryCgroupChildren = sanctuaryCgroupChildren;
 exports.verifySanctuaryAuthorityInstallation = verifySanctuaryAuthorityInstallation;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
@@ -70,6 +72,16 @@ function readOwned(filePath, uid, gid, mode) {
         fs.closeSync(descriptor);
     }
 }
+/**
+ * Unraid's cgroup2-unraid removes every top-level cgroup that reports `populated 0`,
+ * and the kernel refuses to remove a cgroup that has child cgroups. So the authority
+ * keeps one permanent empty child, and every reader of its cgroup ignores it (D-026).
+ */
+exports.SANCTUARY_CGROUP_KEEP = "ouro-keep";
+/** The authority cgroup's execution children: directories other than the keep child. */
+function sanctuaryCgroupChildren(cgroupRoot) {
+    return fs.readdirSync(cgroupRoot).filter((name) => name !== exports.SANCTUARY_CGROUP_KEEP && fs.lstatSync(path.join(cgroupRoot, name)).isDirectory());
+}
 function verifySanctuaryAuthorityInstallation(input) {
     const { expectedUid: uid, expectedGid: gid } = input;
     for (const root of [input.packageRoot, input.stateRoot, input.stagingRoot, input.cgroupRoot])

package/dist/heart/daemon/sanctuary-authority-root-lifecycle.js

@@ -151,7 +151,7 @@ class SanctuaryAuthorityRootLifecycle {
                     throw new Error("Resolve pending execution state before re-pinning");
             }
         }
-        if (fs.readdirSync(this.#p(CGROUP)).some(name => fs.lstatSync(this.#p(`${CGROUP}/${name}`)).isDirectory()))
+        if ((0, sanctuary_authority_installation_1.sanctuaryCgroupChildren)(this.#p(CGROUP)).length !== 0)
             throw new Error("Resolve pending cgroups before re-pinning");
         this.#verifyPrimitive("/usr/bin/prlimit", prlimitDigest);
         this.#verifyPrimitive("/usr/bin/setsid", setsidDigest);
@@ -294,9 +294,26 @@ class SanctuaryAuthorityRootLifecycle {
             throw new Error("Sanctuary installed boot lifecycle changed");
         return true;
     }
+    /** Create the authority cgroup with its keep child. The reaper can remove a freshly
+     * made (still empty) cgroup before the child exists, so retry that race a few times. */
+    #cgroup() {
+        const keep = this.#p(`${CGROUP}/${sanctuary_authority_installation_1.SANCTUARY_CGROUP_KEEP}`);
+        for (let attempt = 1; !fs.existsSync(keep); attempt += 1) {
+            try {
+                this.#directory(CGROUP);
+                fs.mkdirSync(keep, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== "ENOENT" || attempt >= 5)
+                    throw error;
+            }
+        }
+        this.#directory(CGROUP);
+    }
     #runtimeDirectories() {
-        for (const directory of [this.#epochRoot(), STAGING, CGROUP])
+        for (const directory of [this.#epochRoot(), STAGING])
             this.#directory(directory);
+        this.#cgroup();
         this.#directory(SOCKET, 0o750, this.#socketGid);
         // Add only the required controllers; never replace another owner's controls.
         for (const root of ["/sys/fs/cgroup", CGROUP]) {
@@ -546,7 +563,7 @@ class SanctuaryAuthorityRootLifecycle {
         const epoch = this.#epoch();
         if (proof.schemaVersion !== 1 || proof.keyId !== epoch.epochId || proof.publicKeyDigest !== epoch.publicKeyDigest || proof.quiescent !== true
             || !Number.isSafeInteger(proof.cursor) || proof.cursor < epoch.predecessorCursor
-            || fs.readdirSync(this.#p(CGROUP)).some((entry) => fs.lstatSync(this.#p(`${CGROUP}/${entry}`)).isDirectory()))
+            || (0, sanctuary_authority_installation_1.sanctuaryCgroupChildren)(this.#p(CGROUP)).length !== 0)
             throw new Error("Sanctuary gateway retirement cleanup is unproven");
         return true;
     }
@@ -854,6 +871,7 @@ class SanctuaryAuthorityRootLifecycle {
     }
     /** Start the gateway, then the resident, and prove both. */
     async #startUpgraded() {
+        this.#runtimeDirectories();
         await this.#startGateway();
         this.#docker(["start", "ouro-butler"]);
         await this.#wait(async () => this.#target().State.Running && this.#target().State.Health?.Status === "healthy" && await this.#ready(), 300_000);

package/dist/heart/daemon/sanctuary-host-detached-supervisor.js

@@ -39,6 +39,7 @@ const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const runtime_1 = require("../../nerves/runtime");
+const sanctuary_authority_installation_1 = require("./sanctuary-authority-installation");
 const SCHEMA_VERSION = 1;
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const PERMIT_ID = /^permit-[A-Za-z0-9_-]{43}$/u;
@@ -183,10 +184,8 @@ class DetachedSanctuaryHostSupervisor {
                 throw new Error("Sanctuary host supervisor state is unmatched");
             }
         }
-        for (const permitId of fs.readdirSync(this.#options.cgroupRoot)) {
+        for (const permitId of (0, sanctuary_authority_installation_1.sanctuaryCgroupChildren)(this.#options.cgroupRoot)) {
             const cgroupPath = path.join(this.#options.cgroupRoot, permitId);
-            if (!fs.lstatSync(cgroupPath).isDirectory())
-                continue;
             if (!PERMIT_ID.test(permitId))
                 throw new Error("Sanctuary host cgroup entry is invalid");
             if (!known.has(permitId) && !await this.#reconcileCgroup(cgroupPath)) {

package/dist/heart/daemon/sanctuary-telegram-authority-entry.js

@@ -346,7 +346,7 @@ async function startSanctuaryTelegramAuthority(options) {
                 hostAuthority.retireRegistrations(ledger);
                 await reconcileExecutions();
                 if (hostAuthority.retireRegistrations(ledger).length !== 0
-                    || fs.readdirSync(config.hostCgroupRoot).some((entry) => fs.lstatSync(path.join(config.hostCgroupRoot, entry)).isDirectory()))
+                    || (0, sanctuary_authority_installation_1.sanctuaryCgroupChildren)(config.hostCgroupRoot).length !== 0)
                     throw new Error("Sanctuary authority retirement cleanup is unproven");
                 writePrivateJson(path.join(config.epochRoot, "retirement.json"), {
                     schemaVersion: 1, keyId: config.keyId, publicKeyDigest: config.publicKeyDigest,

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.836",
+  "version": "0.1.0-alpha.839",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.836",
+      "version": "0.1.0-alpha.839",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.836",
+  "version": "0.1.0-alpha.839",
   "engines": {
     "node": ">=22"
   },