@ouro.bot/cli 0.1.0-alpha.884 → 0.1.0-alpha.887

package/dist/a2a/trust-commands.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeDelegatedCommandsCommand = executeDelegatedCommandsCommand;
+exports.executeEscalationCommand = executeEscalationCommand;
+const runtime_1 = require("../nerves/runtime");
+const delegated_command_grants_1 = require("./delegated-command-grants");
+const escalation_grants_1 = require("./escalation-grants");
+const replay_grant_holders_1 = require("./replay-grant-holders");
+const operator_trust_1 = require("./operator-trust");
+const resolution_proof_1 = require("./resolution-proof");
+const NEEDS_ROOT = "refusing: this command writes root-owned files the agent cannot forge, so it must run as root on the agent's host (for example docker exec as root, or sudo). Nothing was written.";
+function requireRoot(ctx) {
+    if (!ctx.isRoot)
+        throw new Error(NEEDS_ROOT);
+}
+async function requireFriend(ctx, friendId) {
+    const friend = await ctx.store.get(friendId);
+    if (!friend)
+        throw new Error(`friend not found: ${friendId}`);
+    return friend;
+}
+/** The --did rules shared by both grant commands. Returns the DID to pin (equal to the record's). */
+function checkedDid(friend, did) {
+    if (!did || !did.startsWith("did:"))
+        throw new Error(`refusing: --did ${did ?? "(missing)"} is not a DID (it starts with did:). Copy it from the sender's own host with: ouro a2a identity --json. Nothing was written.`);
+    const recorded = (0, resolution_proof_1.friendDid)(friend);
+    if (!recorded)
+        throw new Error(`refusing: ${friend.name} has no DID on record, so there is nothing to check --did against. Onboard it with its DID first (ouro a2a onboard --did <did> --name "${friend.name}"). Nothing was written.`);
+    if (recorded !== did)
+        throw new Error(`refusing: --did ${did} does not match the DID on ${friend.name}'s record (${recorded}). If the sender's key really changed, onboard it again; otherwise you copied the wrong DID. Nothing was written.`);
+    return did;
+}
+/**
+ * The checks both grant commands share before they pin a DID. It may not be this agent's own, and it may not already be pinned by
+ * another holder's grant in the same file. When this agent's own DID cannot be read (a one-off root container has no vault) the
+ * own-DID check cannot run, so the command instead refuses any DID that a second friend record also carries (a sender's key is on
+ * exactly one record), and says so in its output.
+ */
+async function vetPinnedDid(ctx, friend, did, held) {
+    const own = await ctx.ownDid();
+    if (own === did)
+        throw new Error("refusing: that is this agent's own DID. A grant must pin the sender's key, not this agent's. Nothing was written.");
+    const holder = Object.entries(held).find(([id, existing]) => id !== friend.id && existing.did === did);
+    if (holder)
+        throw new Error(`refusing: that DID is already pinned by ${holder[0]}'s grant. Revoke it first if the sender really moved to a different friend record. Nothing was written.`);
+    if (own !== null)
+        return [];
+    // The own DID is not available from the machine config here. A DID the agent published in its bundle is only a hint (the agent can write
+    // that file), so the friend-record comparison always runs as well, and the published value is reported with its source.
+    const published = await ctx.publishedDid?.() ?? null;
+    const records = await ctx.store.listAll?.() ?? [];
+    const twin = records.find((record) => record.id !== friend.id && (0, resolution_proof_1.friendDid)(record) === did);
+    if (twin)
+        throw new Error(`refusing: this agent's own DID could not be read from its machine config here, and another friend record (${twin.name}, ${twin.id}) carries that same DID, so it may be this agent's own key. Check it with: ouro a2a identity --agent ${ctx.agentName} --json. Nothing was written.`);
+    const notes = ["note: could not read this agent's own DID from its machine config here, so the own-DID check was skipped; compared --did with every DID in the friend records instead, and no other record carries it"];
+    if (published === did)
+        notes.push("warning: --did equals the DID published in the agent's bundle (source: bundle-published, which the agent itself can write, so this is advisory). Granting it would pin the agent's own key; check with ouro a2a identity --agent " + ctx.agentName + " --json before relying on this grant");
+    else if (published !== null)
+        notes.push(`note: the DID published in the agent's bundle (source: bundle-published, advisory) is ${published}, which differs from --did`);
+    return notes;
+}
+function notActiveFamilyNote(friend, what) {
+    return friend.trustLevel === "family" && friend.admissionState === "active"
+        ? []
+        : [`note: ${friend.name} is ${friend.trustLevel}, ${friend.admissionState}, so the grant stays suspended until it is active family${what}`];
+}
+function parseExpiry(expires, now) {
+    if (expires === undefined)
+        return undefined;
+    const at = Date.parse(expires);
+    if (!Number.isFinite(at) || at <= now.getTime())
+        throw new Error(`refusing: --expires ${expires} is not a time in the future (use an ISO date such as 2027-01-01T00:00:00Z). Nothing was written.`);
+    return new Date(at).toISOString();
+}
+async function executeDelegatedCommandsCommand(command, ctx) {
+    if (command.action === "list")
+        return listDelegatedCommands(ctx, command.json === true);
+    requireRoot(ctx);
+    if (command.action === "revoke")
+        return revokeDelegatedCommands(command.friendId, ctx);
+    const expiresAt = parseExpiry(command.expires, ctx.now);
+    const friend = await requireFriend(ctx, command.friendId);
+    if (expiresAt === undefined && (0, replay_grant_holders_1.isReplayGrantHolder)(ctx.agentRoot, friend.id))
+        throw new Error(`refusing: ${friend.name} is a replay peer (it is on the replay gate's list in ${(0, operator_trust_1.operatorTrustDir)(ctx.agentRoot)}), or that list is present but not trustworthy, and a replay peer's grant must expire. Pass --expires <ISO date>. Nothing was written.`);
+    const did = checkedDid(friend, command.did);
+    const selfNotes = await vetPinnedDid(ctx, friend, did, (0, delegated_command_grants_1.readDelegatedCommandGrants)(ctx.agentRoot));
+    const change = (0, delegated_command_grants_1.setDelegatedCommandGrant)(ctx.agentRoot, friend.id, { grant: true, did, source: command.source ?? `ouro a2a delegated-commands grant, ${ctx.now.toISOString()}`, ...(expiresAt ? { expiresAt } : {}) }, ctx.now);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "grant", scope: "delegated_commands" } });
+    return [
+        `granted delegated commands: ${friend.name} (${friend.id})${change.changed ? "" : " (no change)"}`,
+        `pinned DID: ${did}`,
+        `expires: ${expiresAt ?? "never"}`,
+        `trust directory: ${(0, operator_trust_1.operatorTrustDir)(ctx.agentRoot)}`,
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+        ...selfNotes,
+        ...((0, delegated_command_grants_1.readDelegatedCommandGrants)(ctx.agentRoot)[friend.id] === undefined ? [`WARNING: the grant is written but will not be honoured: ${(0, delegated_command_grants_1.delegatedCommandGrantsPath)(ctx.agentRoot)} and every directory above it must be owned by root and writable by no one else. Run \`ouro a2a delegated-commands list\` for what the harness sees.`] : []),
+        ...notActiveFamilyNote(friend, ""),
+    ].join("\n");
+}
+/** The follow-up that clears the legacy record field as the resident user: the record is the Butler's own file, and this command runs as root, so it never writes it. */
+function clearLegacyGrantCommand(agentRoot, friendId) {
+    const file = `${agentRoot}/friends/${friendId}.json`;
+    const script = `const fs=require("fs");const f=${JSON.stringify(file)};const r=JSON.parse(fs.readFileSync(f,"utf8"));delete r.delegationGrant;fs.writeFileSync(f,JSON.stringify(r,null,2)+"\\n")`;
+    return [
+        "REQUIRED FOLLOW-UP: the trusted grant is removed, but the legacy delegationGrant on the friend record is still there (friend records are never written as root). An older harness would honour it after a rollback. Clear it as the resident user:",
+        `  docker exec -u 10001 ouro-butler node -e '${script}'`,
+    ].join("\n");
+}
+async function revokeDelegatedCommands(friendId, ctx) {
+    const friend = await ctx.store.get(friendId);
+    const change = (0, delegated_command_grants_1.setDelegatedCommandGrant)(ctx.agentRoot, friendId, { grant: false }, ctx.now);
+    // A rollback to an older harness reads the legacy record grant. This command runs as root and must not write the Butler's friend record, so it prints the resident-user follow-up instead.
+    const legacyFollowUp = friend?.delegationGrant !== undefined ? clearLegacyGrantCommand(ctx.agentRoot, friend.id) : null;
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "revoke", scope: "delegated_commands" } });
+    return [
+        `revoked delegated commands: ${friend ? `${friend.name} (${friend.id})` : `${friendId} (no friend record)`}${change.changed || legacyFollowUp ? "" : " (no change)"}`,
+        ...(legacyFollowUp ? [legacyFollowUp] : []),
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+    ].join("\n");
+}
+function statusOf(friendId, grant, friend, ctx) {
+    if (!friend)
+        return { status: "not_honoured", reason: "no_friend_record", text: `no friend record for ${friendId}` };
+    const check = (0, delegated_command_grants_1.checkDelegatedCommandGrant)(ctx.agentRoot, friend, (0, resolution_proof_1.friendDid)(friend), ctx.now.getTime());
+    if (check.ok)
+        return { status: "honoured" };
+    switch (check.reason) {
+        case "not_family":
+            return { status: "suspended", reason: check.reason, text: `${friend.name} is trust ${friend.trustLevel}, admission ${friend.admissionState}; the grant is kept and applies again once it is family and active` };
+        case "grant_did_mismatch":
+            return { status: "not_honoured", reason: check.reason, text: `the friend record names ${(0, resolution_proof_1.friendDid)(friend) ?? "no DID"}, but the grant pins ${grant.did}` };
+        default:
+            return { status: "not_honoured", reason: check.reason, text: "the grant is not in force: it expired, this is a replay identity outside its window, or the grant file stopped being trusted" };
+    }
+}
+async function listDelegatedCommands(ctx, json) {
+    const file = (0, delegated_command_grants_1.delegatedCommandGrantsPath)(ctx.agentRoot);
+    const view = (0, delegated_command_grants_1.viewDelegatedCommandGrants)(ctx.agentRoot);
+    const friends = await ctx.store.listAll?.() ?? [];
+    const byId = new Map(friends.map((friend) => [friend.id, friend]));
+    const entries = Object.entries(view.grants).map(([friendId, grant]) => {
+        const friend = byId.get(friendId) ?? null;
+        return { friendId, name: friend?.name ?? null, grant, ...statusOf(friendId, grant, friend, ctx) };
+    });
+    const legacy = friends.filter((friend) => friend.delegationGrant !== undefined);
+    if (json) {
+        return JSON.stringify({
+            agent: ctx.agentName,
+            file: { path: file, state: view.state, ...(view.state === "untrusted" ? { reason: view.reason } : {}) },
+            grants: entries.map(({ friendId, name, grant, ...status }) => ({ friendId, name, did: grant.did, grantedAt: grant.grantedAt, source: grant.source, expiresAt: grant.expiresAt ?? null, ...status })),
+            ignoredEntries: view.ignored,
+            legacyRecordGrants: legacy.map((friend) => ({ friendId: friend.id, name: friend.name })),
+        }, null, 2);
+    }
+    const header = view.state === "trusted" ? `trusted: ${file}` : view.state === "missing" ? `not present: ${file}` : `NOT TRUSTED: ${file} (${view.reason}); no grant in it is honoured`;
+    const lines = [`delegated-command grants for ${ctx.agentName}`, header];
+    if (entries.length === 0)
+        lines.push("no delegated-command grants");
+    for (const entry of entries) {
+        lines.push(`${entry.friendId}  ${entry.name ?? "(no friend record)"}`, `  DID ${entry.grant.did}; granted ${entry.grant.grantedAt} (${entry.grant.source}); expires ${entry.grant.expiresAt ?? "never"}`, entry.status === "honoured" ? "  HONOURED" : entry.status === "suspended" ? `  SUSPENDED: ${entry.text}` : `  NOT HONOURED: ${entry.text}`);
+    }
+    if (view.ignored.length > 0)
+        lines.push(`ignored (malformed) entries: ${view.ignored.join(", ")}`);
+    if (legacy.length > 0)
+        lines.push(`legacy friend-record grants (not honoured): ${legacy.map((friend) => `${friend.name} (${friend.id})`).join(", ")}`);
+    return lines.join("\n");
+}
+async function executeEscalationCommand(command, ctx) {
+    if (command.action === "list") {
+        const grants = Object.entries((0, escalation_grants_1.readEscalationGrants)(ctx.agentRoot));
+        const view = (0, escalation_grants_1.viewEscalationGrants)(ctx.agentRoot);
+        const note = view.state === "untrusted" ? `\nNOT TRUSTED: ${(0, escalation_grants_1.escalationGrantsPath)(ctx.agentRoot)} (${view.reason}); no grant in it is honoured` : "";
+        return (grants.length === 0 ? "no escalation grants" : grants.map(([id, grant]) => `${id}  granted ${grant.grantedAt}  ${grant.did}  ${grant.source}`).join("\n")) + note;
+    }
+    requireRoot(ctx);
+    if (command.action === "revoke")
+        return revokeEscalation(command.friendId, ctx);
+    const friend = await requireFriend(ctx, command.friendId);
+    if ((0, replay_grant_holders_1.isReplayGrantHolder)(ctx.agentRoot, friend.id))
+        throw new Error(`refusing: ${friend.name} is a replay peer (it is on the replay gate's list in ${(0, operator_trust_1.operatorTrustDir)(ctx.agentRoot)}). Only the replay gate grants it escalation, and only while a run is open. Nothing was written.`);
+    const did = checkedDid(friend, command.did);
+    const selfNotes = await vetPinnedDid(ctx, friend, did, (0, escalation_grants_1.readEscalationGrants)(ctx.agentRoot));
+    const change = (0, escalation_grants_1.setEscalationGrant)(ctx.agentRoot, friend.id, { grant: true, source: command.source ?? `ouro a2a escalation grant, ${ctx.now.toISOString()}`, did }, ctx.now);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "grant", scope: "escalation" } });
+    return [
+        `granted escalation: ${friend.name} (${friend.id})${change.changed ? "" : " (no change)"}`,
+        `pinned DID: ${did}`,
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+        ...selfNotes,
+        ...((0, escalation_grants_1.readEscalationGrants)(ctx.agentRoot)[friend.id] === undefined ? [`WARNING: the grant is written but will not be honoured: ${(0, escalation_grants_1.escalationGrantsPath)(ctx.agentRoot)} and every directory above it must be owned by root and writable by no one else.`] : []),
+        ...(friend.trustLevel !== "family" || friend.admissionState !== "active" ? [`note: ${friend.name} only holds the grant while it is active family (now ${friend.trustLevel}, ${friend.admissionState})`] : []),
+    ].join("\n");
+}
+/** Revoke needs no friend record: a grant for a friend that was deleted must still be removable by its id. */
+async function revokeEscalation(friendId, ctx) {
+    const friend = await ctx.store.get(friendId);
+    const change = (0, escalation_grants_1.setEscalationGrant)(ctx.agentRoot, friendId, { grant: false }, ctx.now);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "revoke", scope: "escalation" } });
+    return [
+        `revoked escalation: ${friend ? `${friend.name} (${friend.id})` : `${friendId} (no friend record)`}${change.changed ? "" : " (no change)"}`,
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+    ].join("\n");
+}

package/dist/a2a/trusted-files.js

@@ -35,17 +35,28 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TRUSTED_UID = void 0;
 exports.overrideTrustedUidForTests = overrideTrustedUidForTests;
+exports.overrideTrustChainRootForTests = overrideTrustChainRootForTests;
+exports.overrideOwnerForTests = overrideOwnerForTests;
+exports.__resetRejectionRateLimitForTests = __resetRejectionRateLimitForTests;
 exports.isTrustedDirectory = isTrustedDirectory;
+exports.inspectTrustedDirectory = inspectTrustedDirectory;
+exports.inspectTrustedJson = inspectTrustedJson;
 exports.readTrustedJson = readTrustedJson;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const runtime_1 = require("../nerves/runtime");
 /**
- * Operator-set state lives in the agent bundle, which the agent's own process (and anything a prompt-injected model can
- * run through its shell) can write. Such state only counts when root owns it and nobody else can write it, the same
- * rule the replay window follows. Anything else reads as "not there", so every consumer fails closed.
+ * Operator-set state is only honoured when the agent's own process (and anything a prompt-injected model can run
+ * through its shell) cannot have written it. The rule is the one sshd calls StrictModes: the file and EVERY directory
+ * above it, up to `/`, must be real (no symlinks), owned by the trusted uid (root), and closed to group and other
+ * writes. A check on the file's own directory alone is not enough: an agent that owns the parent can rename the
+ * root-owned directory away and put one of its own making in its place (rename-then-rebless). Anything that fails reads
+ * as "not there", so every consumer fails closed.
  */
 exports.TRUSTED_UID = 0;
 let uidOverride;
+let chainRootOverride;
+let ownerOverride;
 /** Only a test runner sets VITEST; the running Butler (and its prompt-injected shell) cannot reach this process's environment. */
 const underTestRunner = () => process.env.VITEST !== undefined;
 /** Tests run as an ordinary user, so they declare that user trusted. Refused outside a test runner, and ignored there too. */
@@ -54,45 +65,121 @@ function overrideTrustedUidForTests(uid) {
         throw new Error("overrideTrustedUidForTests is for tests only");
     uidOverride = uid;
 }
+/**
+ * Tests keep their files under a private temp root whose ancestors (`/tmp`, `/private`) are not the test user's. A test
+ * names that root here, and the ancestor walk stops there (the root itself and everything above it are skipped).
+ */
+function overrideTrustChainRootForTests(root) {
+    if (!underTestRunner())
+        throw new Error("overrideTrustChainRootForTests is for tests only");
+    chainRootOverride = root;
+}
+/** Tests are not root, so they cannot hand a path to another owner: this reports the owner a test wants for a path (`undefined` keeps the real one). */
+function overrideOwnerForTests(lookup) {
+    if (!underTestRunner())
+        throw new Error("overrideOwnerForTests is for tests only");
+    ownerOverride = lookup;
+}
+const ownerOf = (target, stat) => (underTestRunner() ? ownerOverride?.(target) : undefined) ?? stat.uid;
 const effectiveTrustedUid = () => (underTestRunner() ? uidOverride : undefined) ?? exports.TRUSTED_UID;
-/** A real directory (no symlink), owned by the trusted uid, writable by neither group nor other. */
-function isTrustedDirectory(target, trustedUid = effectiveTrustedUid()) {
-    let stat;
-    try {
-        stat = fs.lstatSync(target);
-    }
-    catch {
-        return false;
-    }
-    const trusted = stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === trustedUid && (stat.mode & 0o022) === 0;
-    if (!trusted)
-        rejected(target, "directory is not a real directory owned by the trusted uid and closed to group and other writes");
-    return trusted;
+const effectiveChainRoot = () => (underTestRunner() ? chainRootOverride : undefined);
+const REJECTION_WINDOW_MS = 60_000;
+const lastRejection = new Map();
+/** Test hook: the rate limiter is module state. */
+function __resetRejectionRateLimitForTests() {
+    lastRejection.clear();
 }
+/** One warn per target and reason per minute: a rejected file is re-read on every inbound message. */
 function rejected(target, reason) {
+    const key = `${target}\u0000${reason}`;
+    const now = Date.now();
+    const last = lastRejection.get(key);
+    if (last !== undefined && now - last < REJECTION_WINDOW_MS)
+        return;
+    lastRejection.set(key, now);
     (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_trusted_file_rejected", message: "ignored operator-set state the agent could have written", meta: { target, reason } });
 }
+/** Every directory from `target` up to `/` (or the test chain root): a real directory, trusted owner, closed to group and other writes. */
+function inspectChain(target, trustedUid) {
+    const stop = effectiveChainRoot();
+    let current = path.resolve(target);
+    for (;;) {
+        if (stop !== undefined && current === stop)
+            return { state: "trusted" };
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            return error.code === "ENOENT" || error.code === "ENOTDIR"
+                ? { state: "missing" }
+                : { state: "untrusted", reason: `cannot inspect ${current}` };
+        }
+        if (stat.isSymbolicLink())
+            return { state: "untrusted", reason: `${current} is a symlink` };
+        if (!stat.isDirectory())
+            return { state: "untrusted", reason: `${current} is not a directory` };
+        if (ownerOf(current, stat) !== trustedUid)
+            return { state: "untrusted", reason: `${current} is not owned by the trusted uid` };
+        if ((stat.mode & 0o022) !== 0)
+            return { state: "untrusted", reason: `${current} is writable by group or other` };
+        const parent = path.dirname(current);
+        if (parent === current)
+            return { state: "trusted" };
+        current = parent;
+    }
+}
+/** A real directory (no symlink) owned by the trusted uid and closed to group and other writes, with every ancestor up to `/` the same. */
+function isTrustedDirectory(target, trustedUid = effectiveTrustedUid()) {
+    const result = inspectChain(target, trustedUid);
+    if (result.state === "trusted")
+        return true;
+    rejected(target, result.state === "missing" ? "directory does not exist" : result.reason);
+    return false;
+}
+/** Same chain check, without the warning: for callers that probe before they decide whether the state is wrong. */
+function inspectTrustedDirectory(target, trustedUid = effectiveTrustedUid()) {
+    return inspectChain(target, trustedUid);
+}
 /**
- * Parses a JSON file only if the file actually opened is trusted. The path is opened once with O_NOFOLLOW, then the
- * descriptor itself is checked (regular file, trusted owner, not group- or other-writable) and read, so a rename loop
- * cannot swap a different file in between the check and the read. Any error is `undefined`.
+ * Reads a JSON file only if the whole chain above it is trusted and the file actually opened is trusted. The path is
+ * opened once with O_NOFOLLOW, then the descriptor itself is checked (regular file, trusted owner, not group- or
+ * other-writable) and read, so a rename loop cannot swap a different file in between the check and the read.
+ * `missing` means the file or a directory above it does not exist; everything else that fails is `untrusted`.
  */
-function readTrustedJson(file, trustedUid = effectiveTrustedUid()) {
+function inspectTrustedJson(file, trustedUid = effectiveTrustedUid()) {
+    const chain = inspectChain(path.dirname(file), trustedUid);
+    if (chain.state === "missing")
+        return { state: "missing" };
+    if (chain.state === "untrusted") {
+        rejected(file, chain.reason);
+        return chain;
+    }
     let fd;
     try {
         fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
         const stat = fs.fstatSync(fd);
-        if (!stat.isFile() || stat.uid !== trustedUid || (stat.mode & 0o022) !== 0) {
-            rejected(file, "file is not a regular file owned by the trusted uid and closed to group and other writes");
-            return undefined;
+        if (!stat.isFile() || ownerOf(file, stat) !== trustedUid || (stat.mode & 0o022) !== 0) {
+            const reason = "file is not a regular file owned by the trusted uid and closed to group and other writes";
+            rejected(file, reason);
+            return { state: "untrusted", reason };
         }
-        return JSON.parse(fs.readFileSync(fd, "utf8"));
+        return { state: "trusted", value: JSON.parse(fs.readFileSync(fd, "utf8")) };
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { state: "missing" };
+        const reason = error instanceof SyntaxError ? "file is not valid JSON" : "file could not be opened without following links";
+        rejected(file, reason);
+        return { state: "untrusted", reason };
     }
     finally {
         if (fd !== undefined)
             fs.closeSync(fd);
     }
 }
+/** The parsed JSON of a trusted file, or `undefined` for anything else. */
+function readTrustedJson(file, trustedUid = effectiveTrustedUid()) {
+    const result = inspectTrustedJson(file, trustedUid);
+    return result.state === "trusted" ? result.value : undefined;
+}

package/dist/heart/core.js

@@ -62,6 +62,7 @@ const obligations_1 = require("../arc/obligations");
 const tool_loop_1 = require("./tool-loop");
 const packets_1 = require("../arc/packets");
 const tool_friction_1 = require("./tool-friction");
+const delegated_command_1 = require("../a2a/delegated-command");
 const provider_models_1 = require("./provider-models");
 const provider_credentials_1 = require("./provider-credentials");
 const habit_session_1 = require("./habits/habit-session");
@@ -1101,6 +1102,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 relationshipProfileId: options?.toolContext?.relationshipAuthorization?.profileId,
                 relationshipToolNames: options?.toolContext?.relationshipAuthorization?.advertisedToolNames,
                 orientationFrame: turnOrientationFrame,
+                ...(options?.toolContext?.delegatedCommand ? { delegatedCommand: options.toolContext.delegatedCommand } : {}),
                 resumePriorWork: options?.resumePriorWork === true,
                 providerCapabilities: providerRuntime.capabilities,
                 supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
@@ -1903,8 +1905,9 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         }
                         callbacks.onToolEnd(soleTerminalCall.name, (0, tools_1.summarizeArgs)(soleTerminalCall.name, terminalArgs, toolSelection), terminalSucceeded);
                         pushGenerated(msg);
-                        pushGenerated({ role: "tool", tool_call_id: soleTerminalCall.id, content: terminalResult });
-                        providerRuntime.appendToolOutput(soleTerminalCall.id, terminalResult);
+                        const shieldedTerminalResult = (0, delegated_command_1.shieldDelegatedBanner)(terminalResult);
+                        pushGenerated({ role: "tool", tool_call_id: soleTerminalCall.id, content: shieldedTerminalResult });
+                        providerRuntime.appendToolOutput(soleTerminalCall.id, shieldedTerminalResult);
                         callbacks.onTextChunk(terminalResult);
                         completion = { answer: terminalResult, intent: terminalSucceeded ? "complete" : "blocked" };
                         outcome = terminalSucceeded ? "settled" : "blocked";
@@ -2469,8 +2472,9 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                                 toolResult = error instanceof Error ? error.message : String(error);
                             }
                             callbacks.onToolEnd(tc.name, argSummary, success);
-                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: toolResult });
-                            providerRuntime.appendToolOutput(tc.id, toolResult);
+                            const shieldedToolResult = (0, delegated_command_1.shieldDelegatedBanner)(toolResult);
+                            pushGenerated({ role: "tool", tool_call_id: tc.id, content: shieldedToolResult });
+                            providerRuntime.appendToolOutput(tc.id, shieldedToolResult);
                             continue;
                         }
                         /* v8 ignore next -- flag tested via truth-check integration tests @preserve */
@@ -2508,7 +2512,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         if (invoked && requiredToolCallNames.includes(tc.name) && !options?.requiredToolCalls?.requireSuccessfulResults)
                             dispatchedRequiredToolCalls.add(tc.name);
                         turnToolRecords.push({ name: tc.name, args, result: toolResult });
-                        const modelResult = (0, tool_friction_1.rewriteToolResultForModel)(tc.name, toolResult, toolFrictionLedger);
+                        const modelResult = (0, delegated_command_1.shieldDelegatedBanner)((0, tool_friction_1.rewriteToolResultForModel)(tc.name, toolResult, toolFrictionLedger));
                         pushGenerated({ role: "tool", tool_call_id: tc.id, content: modelResult });
                         providerRuntime.appendToolOutput(tc.id, modelResult);
                         if (!success)

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

@@ -526,6 +526,7 @@ function agentResolutionFailureMode(command) {
         case "a2a.onboard":
         case "a2a.serve":
         case "a2a.escalation":
+        case "a2a.delegatedCommands":
             return "throw";
         case "provider.use":
         case "provider.check":
@@ -6119,16 +6120,28 @@ async function executeA2AClientCommand(command, deps) {
         deps.writeStdout(message);
         return message;
     }
-    const { sendSealedA2AChat } = await Promise.resolve().then(() => __importStar(require("../../a2a/client")));
-    const reply = await sendSealedA2AChat({
-        cardUrl: command.to,
-        text: command.text,
-        ...(command.conversationId ? { conversationId: command.conversationId } : {}),
-        ...(command.delegated ? { onBehalfOf: "principal" } : {}),
-        identity,
-        /* v8 ignore next -- production CLI uses global fetch; tests inject fetch for a hermetic peer @preserve */
-        ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
-    });
+    const { sendSealedA2AChat, A2ARpcError } = await Promise.resolve().then(() => __importStar(require("../../a2a/client")));
+    let reply;
+    try {
+        reply = await sendSealedA2AChat({
+            cardUrl: command.to,
+            text: command.text,
+            ...(command.conversationId ? { conversationId: command.conversationId } : {}),
+            ...(command.delegated ? { onBehalfOf: "principal" } : {}),
+            identity,
+            /* v8 ignore next -- production CLI uses global fetch; tests inject fetch for a hermetic peer @preserve */
+            ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+        });
+    }
+    catch (error) {
+        // A refused delegated command is an answer, not a crash: with --json the caller gets the reason and the next step.
+        const data = error instanceof A2ARpcError ? error.data : undefined;
+        if (!command.json || typeof data?.reason !== "string")
+            throw error;
+        return returnCliFailure(deps, JSON.stringify({
+            ok: false, reason: data.reason, nothingRan: data.nothingRan, message: error.message, retry: data.retry, next: data.next,
+        }));
+    }
     const message = command.json ? JSON.stringify(reply) : `${reply.peerName}: ${reply.text}\n[conversation: ${reply.conversationId}]`;
     deps.writeStdout(message);
     return message;
@@ -6153,34 +6166,22 @@ async function executeA2ACommand(command, deps) {
         deps.writeStdout(message);
         return message;
     }
-    if (command.kind === "a2a.escalation") {
-        const { readEscalationGrants, setEscalationGrant } = await Promise.resolve().then(() => __importStar(require("../../a2a/escalation-grants")));
+    if (command.kind === "a2a.escalation" || command.kind === "a2a.delegatedCommands") {
+        const { executeDelegatedCommandsCommand, executeEscalationCommand } = await Promise.resolve().then(() => __importStar(require("../../a2a/trust-commands")));
         /* v8 ignore next -- production default bundles root; tests inject bundlesRoot @preserve */
         const agentRoot = path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${command.agent}.ouro`);
-        if (command.action === "list") {
-            const grants = Object.entries(readEscalationGrants(agentRoot));
-            const message = grants.length === 0 ? "no escalation grants" : grants.map(([id, grant]) => `${id}  granted ${grant.grantedAt}  ${grant.did}  ${grant.source}`).join("\n");
-            deps.writeStdout(message);
-            return message;
-        }
-        const friend = await new friends_1.FileFriendStore(path.join(agentRoot, "friends")).get(command.friendId);
-        if (!friend)
-            throw new Error(`friend not found: ${command.friendId}`);
-        const at = new Date(deps.now?.() ?? Date.now());
-        const { friendDid } = await Promise.resolve().then(() => __importStar(require("../../a2a/resolution-proof")));
-        const holderDid = command.action === "grant" ? friendDid(friend) : null;
-        if (command.action === "grant" && !holderDid)
-            throw new Error(`${friend.name} has no pinned DID yet; onboard it with a DID before granting escalation`);
-        const change = command.action === "grant"
-            ? setEscalationGrant(agentRoot, friend.id, { grant: true, source: command.source ?? `ouro a2a escalation grant, ${at.toISOString()}`, did: holderDid }, at)
-            : setEscalationGrant(agentRoot, friend.id, { grant: false }, at);
-        const message = [
-            `${command.action === "grant" ? "granted" : "revoked"} escalation: ${friend.name} (${friend.id})${change.changed ? "" : " (no change)"}`,
-            ...(holderDid ? [`pinned DID: ${holderDid} (compare it with the holder's real DID)`] : []),
-            ...(change.backup ? [`backup: ${change.backup}`] : []),
-            ...(command.action === "grant" && readEscalationGrants(agentRoot)[friend.id] === undefined ? [`WARNING: the grant is written but will not be honoured: ${path.join(agentRoot, "state", "a2a")} and escalation-grants.json must be owned by root and writable by no one else. Run this command as root (docker exec as root) or chown root:root and chmod 755/644 them.`] : []),
-            ...(command.action === "grant" && (friend.trustLevel !== "family" || friend.admissionState !== "active") ? [`note: ${friend.name} only holds the grant while it is active family (now ${friend.trustLevel}, ${friend.admissionState})`] : []),
-        ].join("\n");
+        const context = {
+            agentName: command.agent,
+            agentRoot,
+            store: new friends_1.FileFriendStore(path.join(agentRoot, "friends")),
+            now: new Date(deps.now?.() ?? Date.now()),
+            /* v8 ignore next -- production reads the real euid; tests inject isRoot @preserve */
+            isRoot: deps.isRoot ? deps.isRoot() : process.geteuid?.() === 0,
+            /* v8 ignore next -- production reads the stored identity; tests inject ownA2ADid @preserve */
+            ownDid: async () => deps.ownA2ADid ? deps.ownA2ADid(command.agent) : (await Promise.resolve().then(() => __importStar(require("../../a2a/identity")))).readOwnA2ADid(command.agent),
+            publishedDid: async () => (await Promise.resolve().then(() => __importStar(require("../../a2a/identity")))).readPublishedA2ADid(agentRoot),
+        };
+        const message = command.kind === "a2a.escalation" ? await executeEscalationCommand(command, context) : await executeDelegatedCommandsCommand(command, context);
         deps.writeStdout(message);
         return message;
     }
@@ -7962,7 +7963,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         deps.writeStdout(message);
         return message;
     }
-    if (command.kind === "a2a.card" || command.kind === "a2a.onboard" || command.kind === "a2a.serve" || command.kind === "a2a.escalation") {
+    if (command.kind === "a2a.card" || command.kind === "a2a.onboard" || command.kind === "a2a.serve" || command.kind === "a2a.escalation" || command.kind === "a2a.delegatedCommands") {
         return executeA2ACommand(command, deps);
     }
     // ── provider commands (local, no daemon socket needed) ──

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

@@ -157,8 +157,12 @@ function usage() {
         "  ouro a2a outbox list --to <card-url> [--since <cursor>] [--identity-file <path>] [--json]",
         "  ouro a2a outbox ack --to <card-url> --ids <id,id,...> [--identity-file <path>] [--json]",
         "  ouro a2a outbox resolve --to <card-url> --report <id> --version <version> --note <text> [--identity-file <path>] [--json]",
-        "  ouro a2a escalation <grant|revoke> --friend <id> [--source <text>] [--agent <name>]",
+        "  ouro a2a escalation grant --friend <id> --did <did:key> [--source <text>] [--agent <name>]   (run as root)",
+        "  ouro a2a escalation revoke --friend <id> [--agent <name>]   (run as root)",
         "  ouro a2a escalation list [--agent <name>]",
+        "  ouro a2a delegated-commands grant --friend <id> --did <did:key> [--expires <ISO date>] [--source <text>] [--agent <name>]   (run as root)",
+        "  ouro a2a delegated-commands revoke --friend <id> [--agent <name>]   (run as root)",
+        "  ouro a2a delegated-commands list [--json] [--agent <name>]",
         "  ouro whoami [--agent <name>]",
         "  ouro session list [--agent <name>]",
         "  ouro mcp list",
@@ -1593,12 +1597,13 @@ function parseA2ACommand(args) {
         };
     }
     if (sub === "escalation") {
-        const usageText = "Usage: ouro a2a escalation <grant|revoke> --friend <id> [--source <text>] [--agent <name>] | ouro a2a escalation list [--agent <name>]";
+        const usageText = "Usage: ouro a2a escalation grant --friend <id> --did <did:key> [--source <text>] [--agent <name>] | ouro a2a escalation revoke --friend <id> [--agent <name>] | ouro a2a escalation list [--agent <name>]";
         const action = rest[0];
         if (action !== "grant" && action !== "revoke" && action !== "list")
             throw new Error(usageText);
         let friendId;
         let source;
+        let did;
         for (let i = 1; i < rest.length; i += 1) {
             if (rest[i] === "--friend" && rest[i + 1]) {
                 friendId = rest[++i];
@@ -1608,11 +1613,46 @@ function parseA2ACommand(args) {
                 source = rest[++i];
                 continue;
             }
+            if (rest[i] === "--did" && rest[i + 1]) {
+                did = rest[++i];
+                continue;
+            }
+            throw new Error(usageText);
+        }
+        if ((action === "list") === Boolean(friendId) || ((source || did) && action !== "grant") || (action === "grant" && !did))
+            throw new Error(usageText);
+        return { kind: "a2a.escalation", action, ...(agent ? { agent } : {}), ...(friendId ? { friendId } : {}), ...(did ? { did } : {}), ...(source ? { source } : {}) };
+    }
+    if (sub === "delegated-commands") {
+        const usageText = "Usage: ouro a2a delegated-commands grant --friend <id> --did <did:key> [--expires <ISO date>] [--source <text>] [--agent <name>] | ouro a2a delegated-commands revoke --friend <id> [--agent <name>] | ouro a2a delegated-commands list [--json] [--agent <name>]";
+        const action = rest[0];
+        if (action !== "grant" && action !== "revoke" && action !== "list")
+            throw new Error(usageText);
+        const values = {};
+        let json = false;
+        for (let i = 1; i < rest.length; i += 1) {
+            if (rest[i] === "--json") {
+                json = true;
+                continue;
+            }
+            if (["--friend", "--did", "--expires", "--source"].includes(rest[i]) && rest[i + 1]) {
+                values[rest[i]] = rest[++i];
+                continue;
+            }
             throw new Error(usageText);
         }
-        if ((action === "list") === Boolean(friendId) || (source && action !== "grant"))
+        const allowed = { grant: ["--friend", "--did", "--expires", "--source"], revoke: ["--friend"], list: [] };
+        const required = { grant: ["--friend", "--did"], revoke: ["--friend"], list: [] };
+        if (Object.keys(values).some((flag) => !allowed[action].includes(flag)) || required[action].some((flag) => !values[flag]) || (json && action !== "list"))
             throw new Error(usageText);
-        return { kind: "a2a.escalation", action, ...(agent ? { agent } : {}), ...(friendId ? { friendId } : {}), ...(source ? { source } : {}) };
+        return {
+            kind: "a2a.delegatedCommands", action, ...(agent ? { agent } : {}),
+            ...(values["--friend"] ? { friendId: values["--friend"] } : {}),
+            ...(values["--did"] ? { did: values["--did"] } : {}),
+            ...(values["--expires"] ? { expires: values["--expires"] } : {}),
+            ...(values["--source"] ? { source: values["--source"] } : {}),
+            ...(json ? { json: true } : {}),
+        };
     }
     if (sub === "onboard") {
         let cardUrl;
@@ -1676,7 +1716,7 @@ function parseA2ACommand(args) {
         }
         return { kind: "a2a.serve", ...(agent ? { agent } : {}), ...(host ? { host } : {}), ...(port ? { port } : {}), ...(baseUrl ? { baseUrl } : {}), ...(path ? { path } : {}) };
     }
-    throw new Error("Usage: ouro a2a card|onboard|serve|message|identity|outbox|escalation ...");
+    throw new Error("Usage: ouro a2a card|onboard|serve|message|identity|outbox|escalation|delegated-commands ...");
 }
 function parseConfigCommand(args) {
     const { agent, rest: afterAgent } = extractAgentFlag(args);