@ouro.bot/cli 0.1.0-alpha.886 → 0.1.0-alpha.888

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,
@@ -1206,6 +1208,38 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         rejectedAttempt = [structuredClone(assistant)];
         nextAttemptControls = controls;
     };
+    // Answer gates run only for agents that opt in (ToolContext.answerGates), on every reply the person would receive: a settle answer
+    // and a plain-text reply with no tool call alike (alpha.886 replay: a plain-text reply skipped them and an invented cast went out).
+    // A request-specific contract (options.requiredToolCalls) already validates its own terminal answer. Each gate has its own bounded
+    // retry, and none spends the last provider iteration.
+    const answerGateVerdict = (answer, intent) => {
+        const gates = options?.requiredToolCalls ? undefined : options?.toolContext?.answerGates;
+        const retriesLeft = providerIterations < stepBudget - 1;
+        let groundingError = null;
+        let unverifiedNames = null;
+        const grounding = gates?.sourceGrounding ? (0, source_grounding_1.sourceGroundingFinding)({ answer, userText: userTexts(messages).join("\n"), latestUserText: latestUserMessageText(messages.slice(0, turnStartLength)), knownText: priorTurnsText(messages.slice(0, turnStartLength)), tools: turnToolRecords }) : null;
+        if (grounding) {
+            if (groundingRejections < ANSWER_GATE_MAX_REJECTIONS && retriesLeft) {
+                groundingRejections += 1;
+                groundingError = grounding.message;
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.answer_gate_rejected", message: "answer named things from a work that the turn did not look up; sending the model back", meta: { gate: "source_grounding", rejection: groundingRejections, cap: ANSWER_GATE_MAX_REJECTIONS, lookupsRun: grounding.lookups } });
+            }
+            else {
+                unverifiedNames = grounding.names;
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.answer_gate_disclosed", message: "unsourced names survived the retries; delivering with a disclosure", meta: { gate: "source_grounding", names: grounding.names.length } });
+            }
+        }
+        let brevityError = null;
+        if (!groundingError && gates?.brevity && !options?.toolContext?.context?.isGroupChat && brevityRejections < ANSWER_GATE_MAX_REJECTIONS && retriesLeft
+            && (0, reply_style_1.briefStyleRequested)(userTexts(messages), (0, reply_style_1.savedCommunicationPreference)(options?.toolContext?.context?.friend))) {
+            brevityError = (0, reply_style_1.briefStyleViolation)(answer, intent);
+            if (brevityError) {
+                brevityRejections += 1;
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.answer_gate_rejected", message: "answer broke the person's brevity request; sending the model back", meta: { gate: "brevity", rejection: brevityRejections, cap: ANSWER_GATE_MAX_REJECTIONS } });
+            }
+        }
+        return { error: groundingError ?? brevityError, unverifiedNames };
+    };
     const rejectToolBatch = (assistant, reasons) => {
         rejectAttempt(assistant, assistant.tool_calls.map((call, index) => ({
             role: "tool", tool_call_id: call.id, content: reasons[index],
@@ -1772,6 +1806,24 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                             }]);
                         continue;
                     }
+                    // A plain-text reply reaches the person just as a settle answer does, so the answer gates hold it too.
+                    const textAnswer = isPrivateRuntimeChannel ? "" : stripThinkBlocksForViolationCheck(result.content).trim();
+                    const textVerdict = textAnswer ? answerGateVerdict(textAnswer) : null;
+                    if (textVerdict?.error) {
+                        streamCallbackBuffer?.discard();
+                        callbacks.onClearText?.();
+                        rejectAttempt(msg, [{ role: "user", content: textVerdict.error }]);
+                        continue;
+                    }
+                    if (textVerdict?.unverifiedNames) {
+                        const disclosed = (0, source_grounding_1.withUnverifiedDisclosure)(textAnswer, textVerdict.unverifiedNames);
+                        streamCallbackBuffer?.discard();
+                        callbacks.onClearText?.();
+                        callbacks.onTextChunk(disclosed);
+                        pushGenerated({ ...msg, content: disclosed });
+                        done = true;
+                        continue;
+                    }
                     // Legitimate text-only response, or cap reached — accept as-is.
                     await streamCallbackBuffer?.flush();
                     pushGenerated(msg);
@@ -1903,8 +1955,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";
@@ -1973,34 +2026,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                             sawSettleContentMismatch = true;
                             (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.settle_content_mismatch", message: "settle answer differs from the reply text written beside it; asking once for the reply as the answer", meta: { answerLength: deliveredAnswer.length, contentLength: msg.content.length } });
                         }
-                        // Answer gates run only for agents that opt in (ToolContext.answerGates). A request-specific contract (options.requiredToolCalls)
-                        // already validates its own terminal answer. Each gate has its own bounded retry, and none spends the last provider iteration.
-                        const gates = options?.requiredToolCalls ? undefined : options?.toolContext?.answerGates;
-                        const retriesLeft = providerIterations < stepBudget - 1;
-                        let groundingError = null;
-                        let unverifiedNames = null;
-                        const grounding = gates?.sourceGrounding ? (0, source_grounding_1.sourceGroundingFinding)({ answer: deliveredAnswer, userText: userTexts(messages).join("\n"), latestUserText: latestUserMessageText(messages.slice(0, turnStartLength)), knownText: priorTurnsText(messages.slice(0, turnStartLength)), tools: turnToolRecords }) : null;
-                        if (grounding) {
-                            if (groundingRejections < ANSWER_GATE_MAX_REJECTIONS && retriesLeft) {
-                                groundingRejections += 1;
-                                groundingError = grounding.message;
-                                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.answer_gate_rejected", message: "settle answer named things from a work that the turn did not look up; sending the model back", meta: { gate: "source_grounding", rejection: groundingRejections, cap: ANSWER_GATE_MAX_REJECTIONS, lookupsRun: grounding.lookups } });
-                            }
-                            else {
-                                unverifiedNames = grounding.names;
-                                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.answer_gate_disclosed", message: "unsourced names survived the retries; delivering with a disclosure", meta: { gate: "source_grounding", names: grounding.names.length } });
-                            }
-                        }
-                        let brevityError = null;
-                        if (!groundingError && gates?.brevity && !options?.toolContext?.context?.isGroupChat && brevityRejections < ANSWER_GATE_MAX_REJECTIONS && retriesLeft
-                            && (0, reply_style_1.briefStyleRequested)(userTexts(messages), (0, reply_style_1.savedCommunicationPreference)(options?.toolContext?.context?.friend))) {
-                            brevityError = (0, reply_style_1.briefStyleViolation)(deliveredAnswer, intent);
-                            if (brevityError) {
-                                brevityRejections += 1;
-                                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "engine", event: "engine.answer_gate_rejected", message: "settle answer broke the person's brevity request; sending the model back", meta: { gate: "brevity", rejection: brevityRejections, cap: ANSWER_GATE_MAX_REJECTIONS } });
-                            }
-                        }
-                        const answerGateError = groundingError ?? brevityError;
+                        const { error: answerGateError, unverifiedNames } = answerGateVerdict(deliveredAnswer, intent);
                         const retryError = contentMismatch
                             ?? answerGateError
                             ?? privateReturnAckLeakError(deliveredAnswer, privateReturnHeldTokens)
@@ -2469,8 +2495,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 +2535,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)