create-metamynd-agent 0.14.10 → 0.14.18

package/index.mjs

@@ -61,7 +61,11 @@ const GUARD_PKG = '@metamynd/agentsafe-guard';
 // 0.18.0 exports keepAliveFetch. No template change.
 // 0.18.1 parks a local-first ESCALATE at the gate. Required: every scaffold's demo says "approve it in the dashboard and
 // the action resumes", and below this the escalation never reached the owner's queue (decided in-process, no escalationId).
-const GUARD_VERSION = '^0.18.1';
+// 0.19.0: a handshake signs only a plain-token nonce (a malicious Service could otherwise obtain this agent's signature on an
+// authorize request of its choosing, MAGP §8.2). Required for every scaffolded agent.
+// 0.20.0: guard.capture() signs as the agent (MAGP-SETTLE-v1) — a hold nobody claimed is settled only by its agent, a
+// counterparty the owner registered, or (an open testnet owner) anyone (MAGP §8.7.4).
+const GUARD_VERSION = '^0.20.0';
 /** The harness entry point's config load, shared by both harness templates: a fresh clone has no
  *  agent.metamynd.json (it is gitignored), so say what to do instead of a bare ENOENT (BR-004). */
 function harnessConfigLoad() {
@@ -128,7 +132,20 @@ const MCP_GUARD_PKG = '@metamynd/agentsafe-mcp-guard';
 // 0.19.0: a request the gateway's own policy escalates, carrying an authorization a PERSON approved, is executed (once,
 // with every claim binding) instead of refused RISK_REVIEW (MAGP §8.7.18). Required: the scaffold tells the developer
 // "approve it in the dashboard and the action resumes" — below this the gateway refused exactly that.
-const MCP_GUARD_VERSION = '^0.19.0';
+// 0.20.0: `allowedAgents` pins a Service to the agents it acts for (MAGP §16.3) — refused AGENT_NOT_ADMITTED otherwise.
+// Required: every scaffolded gateway now sets it, and an older guard would ignore the option and serve ANY agent whose
+// own owner granted it the same action, with this owner's credentials (XT-1, pre-beta evaluation 2026-10-03).
+// 0.21.0: guard.reportOutcome(). Required: the scaffolded gateways report what they ran or refused (MAGP §16.4), and
+// agentsafe-http-gateway's reportOutcomes needs it.
+// 0.22.0: allowedAgents is required, gatewayOwnerPrincipal binds the gateway to the owner of its credentials (an admitted
+// agent of any other owner: GATEWAY_OWNER_MISMATCH), per-route admission (CREDENTIAL_PROFILE_NOT_PERMITTED), the refusal is
+// AGENT_NOT_ADMITTED, and a handshake signs only a plain-token nonce. Required: every scaffolded gateway sets the owner.
+// 0.23.0: acceptCounterpartyChallenge() — a Service signs its acceptance of an owner's registration (MAGP §8.7.6). No
+// template change; required with GATEWAY_VERSION below so the gateway never resolves a second guard of its own.
+// 0.24.0: reportOutcome() signs a reportId and an occurrence count (aggregated refusals, a durable spool).
+const MCP_GUARD_VERSION = '^0.24.0';
+/** A DID as it may appear inside a generated string literal (the gateway's allowedAgents pin): no quote, backslash or space. */
+const SAFE_DID = /^did:[a-z0-9]+:[A-Za-z0-9._:%-]+$/;
 const GATEWAY_PKG = '@metamynd/agentsafe-http-gateway';
 // 0.2.0 fixes a confused-deputy gap (payload not bound to the signed request) — the CLI must
 // never scaffold a range that could resolve below it.
@@ -151,7 +168,13 @@ const GATEWAY_PKG = '@metamynd/agentsafe-http-gateway';
 // 0.17.0: depends on agentsafe-mcp-guard ^0.18.0 and exports keepAliveFetch. No template change.
 // 0.18.0: depends on agentsafe-mcp-guard ^0.19.0 (an approved escalation executes). Required with MCP_GUARD_VERSION
 // above, so the gateway never resolves a second, older guard of its own.
-const GATEWAY_VERSION = '^0.18.0';
+// 0.19.0: depends on agentsafe-mcp-guard ^0.20.0 (allowedAgents) and reads AGENTSAFE_ALLOWED_AGENTS. Required with
+// MCP_GUARD_VERSION above, so the gateway never resolves a second, older guard of its own.
+// 0.20.0: `reportOutcomes`, which both hosted gateway templates set; depends on agentsafe-mcp-guard ^0.21.0.
+// 0.21.0: per-route allowedAgents; depends on agentsafe-mcp-guard ^0.22.0.
+// 0.22.0: depends on agentsafe-mcp-guard ^0.23.0.
+// 0.23.0: refusals aggregated with their count, and `reportSpool` (both hosted templates set it); depends on agentsafe-mcp-guard ^0.24.0.
+const GATEWAY_VERSION = '^0.23.0';
 
 /** Appended to every scaffolded gateway server: give hold settlements still running a bounded moment on shutdown. */
 const DRAIN_ON_SHUTDOWN = `
@@ -995,12 +1018,27 @@ async function resolveHostedRulePack(base, key, { financial, perTxnMax, maxAmoun
  * dashboard registration shows its own dialog before setting the flag); see the printed message
  * either way.
  */
-async function registerGatewayCounterparty(base, token, did, label) {
+async function registerGatewayCounterparty(base, token, did, label, purpose = 'claim', privateKeyHex = null) {
   try {
+    // The gateway accepts its own registration (MAGP §8.7.6): ask for a challenge naming this owner, sign it with the gateway's
+    // key (generated here, so this process holds it), and register with that proof. A DID is never registered on its text.
+    let proof;
+    if (privateKeyHex) {
+      const ch = await fetch(`${base}/policy/counterparties/challenge`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ did, purpose }),
+      });
+      const chJson = await ch.json().catch(() => null);
+      if (!ch.ok || !chJson?.data?.message) return { ok: false, message: chJson?.message ?? `challenge HTTP ${ch.status}` };
+      proof = { challengeToken: chJson.data.challengeToken, signature: signChallengeHex(privateKeyHex, chJson.data.message) };
+    }
     const res = await fetch(`${base}/policy/counterparties`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
-      body: JSON.stringify({ did, label, confirmEnforcementChange: true }),
+      // `report` (a non-financial gateway, which never claims): it may only report to this owner, and it changes nothing about
+      // who may claim their holds, so it needs no enforcement confirmation (MAGP §8.7.6, §16.4).
+      body: JSON.stringify({ did, label, purpose, ...(proof ? { proof } : {}), ...(purpose === 'claim' ? { confirmEnforcementChange: true } : {}) }),
     });
     const json = await res.json().catch(() => null);
     if (!res.ok || json?.success === false) return { ok: false, message: json?.message ?? `HTTP ${res.status}` };
@@ -1033,6 +1071,30 @@ async function ensurePolicyKey(config, base) {
   return config.issuer.policyKey;
 }
 
+/**
+ * The principal DID that owns this agent (and so its gateway's credentials), read from the agent's own policy bundle
+ * (`ownerPrincipal`, MAGP §16.3) on the API it was just provisioned through, and saved into the config. A gateway is bound
+ * to it: an admitted agent of any other owner is refused. Returns it, or null when the bundle names none.
+ */
+async function ensureOwnerPrincipal(config, base) {
+  if (typeof config.ownerPrincipal === 'string' && SAFE_DID.test(config.ownerPrincipal)) return config.ownerPrincipal;
+  let owner = null;
+  try {
+    const res = await fetch(`${String(base).replace(/\/+$/, '')}/policy/bundle/${encodeURIComponent(config.agentDid)}`);
+    owner = (await res.json().catch(() => null))?.data?.ownerPrincipal ?? null;
+  } catch {
+    owner = null;
+  }
+  if (typeof owner !== 'string' || !SAFE_DID.test(owner)) return null;
+  config.ownerPrincipal = owner;
+  return owner;
+}
+
+const NO_OWNER_PRINCIPAL = (base) =>
+  `Could not read the principal that owns this agent from its policy bundle (GET ${base}/policy/bundle/<agent DID>, ownerPrincipal). ` +
+  'A gateway is bound to the owner of its credentials, so none was scaffolded. Retry when the API is reachable (it needs a ' +
+  'backend that names the owner), or pass --no-gateway for the single-process example (not an enforcement boundary).';
+
 const NO_POLICY_KEY = (base) =>
   `Could not get MetaMynd's policy-signing key: the provisioning response carried none, and GET ${base}/magp/policy/pubkey ` +
   'did not return one. A gateway without it would trust whatever policy bundle its network fetch returns, so none was ' +
@@ -1148,7 +1210,7 @@ const WHY = {
   // gate, and neither of them depends on the amount.
   NO_PERMISSION_FOR_ACTION: 'the mandate never granted this action - at any amount',
   NO_MANDATE: 'there is no mandate for this action at all',
-  MANDATE_REVOKED: 'the owner revoked the mandate for this action',
+  MANDATE_REVOKED: 'the owner revoked the mandate for this action',
 };
 
 // ---------------------------------------------------------------- 1. CONTEXT
@@ -1168,7 +1230,9 @@ console.log('');
 console.log(dim('   1. this project holds an agent identity (a DID) and its signing key'));
 console.log(dim('   2. that agent has a mandate - a scope it may act in, and a spend cap'));
 console.log(dim('   3. guardTool() wraps your tool, so nothing calls the raw handler'));
-console.log(dim('   4. each attempt is signed here, then decided by MetaMynd remotely'));
+console.log(dim('   4. each attempt is signed here and checked against your signed rules: what'));
+console.log(dim('      they refuse stops HERE, with no network call; what could run is decided'));
+console.log(dim('      by the MetaMynd gate, which records it'));
 console.log(dim('   5. your tool runs ONLY if that decision is ALLOW'));
 console.log('');
 console.log(dim('  scope  ${scope}'));
@@ -1178,7 +1242,7 @@ console.log(dim('  cap    ${currency} ${perTxnMax} per transaction, set by your
 async function attempt(n, intent, args, tool = gatedBookFlight) {
   console.log('');
   console.log(bold('  Step ' + n + ' of 4') + ' - ' + intent);
-  console.log(dim('     signing the request locally, then asking the gate to decide...'));
+  console.log(dim('     signing the request here, checking it against your signed rules...'));
   try {
     const r = await tool(args);
     console.log('\\x1b[32m     ALLOWED\\x1b[0m  your tool ran and returned ' + (r.pnr ?? 'ok'));
@@ -1193,7 +1257,7 @@ async function attempt(n, intent, args, tool = gatedBookFlight) {
     } else {
       console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? 'refused'));
       console.log(dim('     ' + why));
-      console.log(dim('     your tool never ran - the gate refused before execution.'));
+      console.log(dim(g.eventId ? '     decided by the MetaMynd gate - your tool never ran.' : '     decided right here from your signed rules (no network call), and reported for audit - your tool never ran.'));
     }
   }
 }
@@ -1352,7 +1416,7 @@ const WHY = {
   // gate, and neither of them depends on the amount.
   NO_PERMISSION_FOR_ACTION: 'the mandate never granted this action - at any amount',
   NO_MANDATE: 'there is no mandate for this action at all',
-  MANDATE_REVOKED: 'the owner revoked the mandate for this action',
+  MANDATE_REVOKED: 'the owner revoked the mandate for this action',
 };
 
 // ---------------------------------------------------------------- 1. CONTEXT
@@ -1385,11 +1449,12 @@ console.log(dim('  gateway  ' + GATEWAY + '  (run it in a separate terminal - se
 async function attempt(n, intent, args, tool = gatedBookFlight) {
   console.log('');
   console.log(bold('  Step ' + n + ' of 4') + ' - ' + intent);
-  console.log(dim('     signing the request locally, then asking the gate to decide...'));
+  console.log(dim('     signing the request here, checking it against your signed rules...'));
   try {
     const r = await tool(args);
     console.log('\\x1b[32m     ALLOWED\\x1b[0m  your tool ran (in ./gateway) and returned ' + (r.pnr ?? 'ok'));
     console.log(dim('     ' + WHY.AUTHORIZED));
+    return true;
   } catch (e) {
     const g = e.governance ?? {};
     const why = WHY[g.reasonCode] ?? e.message;
@@ -1400,14 +1465,14 @@ async function attempt(n, intent, args, tool = gatedBookFlight) {
     } else {
       console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? 'refused'));
       console.log(dim('     ' + why));
-      console.log(dim('     your tool never ran - refused before execution.'));
+      console.log(dim(g.eventId ? '     decided by the MetaMynd gate - your tool never ran.' : '     decided right here from your signed rules (no network call), and reported for audit - your tool never ran.'));
     }
   }
 }
 
 console.log('');
 console.log(rule(66));
-await attempt(1, 'a ${currency} ${under} booking, low risk. Expected to pass.', { amount: ${under}, currency: '${currency}', merchant: '${merchant}', riskLevel: 'low' });
+const step1Ran = await attempt(1, 'a ${currency} ${under} booking, low risk. Expected to pass.', { amount: ${under}, currency: '${currency}', merchant: '${merchant}', riskLevel: 'low' });
 await attempt(2, 'a ${currency} ${over} booking, deliberately over the cap.', { amount: ${over}, currency: '${currency}', merchant: '${merchant}', riskLevel: 'low' });
 await attempt(3, 'a ${currency} ${under} booking, but flagged high risk.', { amount: ${under}, currency: '${currency}', merchant: '${merchant}', riskLevel: 'high' });
 await attempt(
@@ -1425,7 +1490,13 @@ console.log(bold('  What this proved'));
 console.log('');
 console.log(dim('   - one code path, three outcomes. The rules decided, not this file'));
 console.log(dim('     and not the model driving it.'));
-console.log(dim('   - step 1 ran in ./gateway, a process this file cannot reach into. There'));
+// Only claim what happened (pre-beta rerun 2026-10-03, L-h: this said "step 1 ran in ./gateway" when step 1 was refused).
+if (step1Ran) {
+  console.log(dim('   - step 1 ran in ./gateway, a process this file cannot reach into. There'));
+} else {
+  console.log(dim('   - step 1 did not run this time (see above). When it does, it runs in'));
+  console.log(dim('     ./gateway, a process this file cannot reach into. There'));
+}
 console.log(dim('     is no rawBookFlight() here to call instead - that is what actually'));
 console.log(dim('     stops a bypass, not the guardTool() call above it.'));
 console.log(dim('   - step 4 needed no rule to stop it. The agent could not widen its own'));
@@ -1434,7 +1505,7 @@ console.log(dim('   - every blocked/escalated call never reached a real tool at
 console.log(dim('   - if the gate were unreachable the guard fails CLOSED: it blocks.'));
 console.log('');
 console.log(bold('  With MetaMynd, you can\\'t be bypassed.') + ' ./gateway is why - it independently');
-console.log(dim('  re-verified step 1 before running it, and holds the tool this file never can.'));
+console.log(dim(step1Ran ? '  re-verified step 1 before running it, and holds the tool this file never can.' : '  re-verifies every call before running it, and holds the tool this file never can.'));
 console.log('');
 console.log('  Change the cap in the dashboard (${SOPS_PATH_ASCII}) and run again.');
 console.log(dim('  The outcome changes. This file does not. That is the point.'));
@@ -1553,7 +1624,7 @@ async function attempt(n, total, step) {
   const tool = step.action === 'permissions.update' ? gatedChangeOwnPermissions : gatedAction;
   console.log('');
   console.log(bold('  Step ' + n + ' of ' + total) + ' - ' + step.intent);
-  console.log(dim('     signing the request locally, then asking the gate to decide...'));
+  console.log(dim('     signing the request here, checking it against your signed rules...'));
   let got;
   let g = {};
   try {
@@ -1568,7 +1639,7 @@ async function attempt(n, total, step) {
       ${escalateNote(sandbox)}
     } else {
       console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? e.message));
-      console.log(dim('     your tool never ran - refused before execution.'));
+      console.log(dim(g.eventId ? '     decided by the MetaMynd gate - your tool never ran.' : '     decided right here from your signed rules (no network call), and reported for audit - your tool never ran.'));
     }
   }
   const asExpected = got === step.expect && (!step.reasonCode || g.reasonCode === step.reasonCode);
@@ -1633,7 +1704,7 @@ console.log('');
  * allowed value-less request would be refused AUTHORIZATION_REQUIRED. The README states what that
  * leaves open (replay) rather than implying the financial scaffold's guarantees.
  */
-function gatewayServerFileNeutral(scope, port, apiBase, policyKey) {
+function gatewayServerFileNeutral(scope, port, apiBase, policyKey, agentDid, ownerPrincipal) {
   return `#!/usr/bin/env node
 // gateway/server.mjs — the enforcement boundary for this agent's tool(s).
 //
@@ -1643,6 +1714,7 @@ function gatewayServerFileNeutral(scope, port, apiBase, policyKey) {
 // compromised or dishonest agent calling its own local function gets nothing here, because
 // there is no local function: the tool only runs in this process.
 import http from 'node:http';
+import { readFileSync } from 'node:fs';
 import { createMcpGuard } from '${MCP_GUARD_PKG}';
 import { createHttpGateway } from '${GATEWAY_PKG}';
 
@@ -1666,6 +1738,11 @@ async function performAction(args) {
 // exactly those keys here — the gateway refuses every top-level key you do not name.
 const routes = [{ method: 'POST', path: '/perform', action: '${scope}', valueFields: [], allowedFields: [] }];
 
+// This gateway's OWN identity (a did:key, separate from the agent's), registered as your counterparty when
+// \`npx create-metamynd-agent\` provisioned it. It signs the reports below, so the issuer files them under YOUR account and
+// nobody else can write into it. Keep service.metamynd.json out of version control (it is gitignored).
+const identity = JSON.parse(readFileSync(new URL('./service.metamynd.json', import.meta.url)));
+
 // requireAuthorization is OFF on purpose. It makes the gateway claim a single-use, stateful
 // authorization before running the tool — but the agent's guard only seals one for a value-bearing
 // action (amount > 0), and this agent has no spending authority. With it ON, every ALLOWED request
@@ -1677,11 +1754,23 @@ const routes = [{ method: 'POST', path: '/perform', action: '${scope}', valueFie
 // forged bundle). Without it, verifyBundle() never runs at all: an attacker who can intercept the
 // fetch to \`\${MAGP_API}/policy/bundle/...\` — a MITM, a compromised DNS/proxy — can hand this gateway
 // a bundle with a higher cap or no rules, and it would be trusted the same as the real one.
-const guard = createMcpGuard({ serviceDid: 'did:local:${scope}-gateway', issuerApi: MAGP_API, requireAuthorization: false, policyPublicKey: '${policyKey}' });
+// allowedAgents pins this gateway to the ONE agent it was scaffolded for (MAGP §16.3). Every other check here judges the
+// caller by the caller's OWN mandate and SOP — written by the caller's owner. Without the pin, any agent on the platform
+// whose owner granted it this same action would run your tool with your credentials (refused AGENT_NOT_ADMITTED instead).
+// Add a DID here only for another agent you mean this gateway to act for. gatewayOwnerPrincipal binds it to YOU, the owner of
+// its credentials: an agent listed here that another principal owns is refused anyway (GATEWAY_OWNER_MISMATCH).
+const guard = createMcpGuard({ serviceDid: identity.serviceDid, serviceKey: identity.serviceKey ?? undefined, issuerApi: MAGP_API, requireAuthorization: false, policyPublicKey: '${policyKey}', allowedAgents: ['${agentDid}'], gatewayOwnerPrincipal: '${ownerPrincipal}' });
+// A guard below 0.20.0 ignores allowedAgents and serves every agent: refuse to start on one (a stale lockfile, say).
+if (!Array.isArray(guard.allowedAgents) || !guard.gatewayOwnerPrincipal) throw new Error('this gateway needs @metamynd/agentsafe-mcp-guard >= 0.22.0 to enforce allowedAgents and gatewayOwnerPrincipal - run npm install');
 
 const gateway = createHttpGateway({
   guard,
   routes,
+  // Every request this gateway runs or refuses is reported, signed with the identity above, to your Activity Log (MAGP
+  // 16.4). It claims nothing, so without this the issuer would never see what it executed - or that another agent tried.
+  reportOutcomes: true,
+  // A report the issuer could not take (it was down, say) is kept here and re-sent, so nothing it saw is lost. Gitignored.
+  reportSpool: './reports.spool.jsonl',
   forward: async (req) => {
     let args = {};
     try { args = JSON.parse(req.rawBody?.toString('utf8') || '{}'); } catch { /* empty body */ }
@@ -1762,6 +1851,11 @@ the agent gets nothing, and there is no local function to call directly. The pol
 pinned to MetaMynd's own signing key (\`policyPublicKey\`, baked in from your provisioning response) —
 a party that can intercept the bundle fetch (a MITM, a compromised DNS/proxy) cannot hand this gateway
 a forged bundle with a higher cap or no rules; \`server.mjs\` refuses an unsigned or tampered one outright.
+It is also pinned to THIS agent, and bound to you as the owner of its credentials (\`allowedAgents\` and
+\`gatewayOwnerPrincipal\` in \`server.mjs\`, MAGP 16.3): any other agent - even one whose own
+owner granted it this same action - is refused \`AGENT_NOT_ADMITTED\` before its rules are read. Every request it runs or
+refuses is reported, signed with its own registered identity (\`service.metamynd.json\`), to your Activity Log (MAGP 16.4) -
+it claims nothing, so this is the only way what it ran reaches you.
 
 **NOT closed — be precise about this:**
 
@@ -2037,7 +2131,7 @@ function gitignore() {
 // in the AgentSafe repo for the full pattern (mutual handshake, x402 payment, capability
 // binding) this is a minimal slice of.
 
-function gatewayServerFile(scope, port, apiBase, policyKey) {
+function gatewayServerFile(scope, port, apiBase, policyKey, agentDid, ownerPrincipal) {
   return `#!/usr/bin/env node
 // gateway/server.mjs — the REAL enforcement boundary for this agent's tool(s).
 //
@@ -2092,7 +2186,16 @@ const identity = JSON.parse(readFileSync(new URL('./service.metamynd.json', impo
 // forged bundle). Without it, verifyBundle() never runs at all: an attacker who can intercept the
 // fetch to \`\${MAGP_API}/policy/bundle/...\` — a MITM, a compromised DNS/proxy — can hand this gateway
 // a bundle with a higher cap or no rules, and it would be trusted the same as the real one.
-const guard = createMcpGuard({ serviceDid: identity.serviceDid, serviceKey: identity.serviceKey ?? undefined, issuerApi: MAGP_API, requireAuthorization: true, policyPublicKey: '${policyKey}' });
+// allowedAgents pins this gateway to the ONE agent it was scaffolded for (MAGP §16.3). Every other check here judges the
+// caller by the caller's OWN mandate and SOP — written by the caller's owner. Without the pin, any agent on the platform
+// whose owner granted it this same action would run your tool with your credentials (refused AGENT_NOT_ADMITTED instead).
+// Add a DID here only for another agent you mean this gateway to act for. gatewayOwnerPrincipal binds it to YOU, the owner of
+// its credentials: an agent listed here that another principal owns is refused anyway (GATEWAY_OWNER_MISMATCH).
+// The claim below does not stop that on its own: the hold belongs to the CALLER, and the caller's owner decides which
+// services may claim it — including registering this gateway's DID as one of theirs.
+const guard = createMcpGuard({ serviceDid: identity.serviceDid, serviceKey: identity.serviceKey ?? undefined, issuerApi: MAGP_API, requireAuthorization: true, policyPublicKey: '${policyKey}', allowedAgents: ['${agentDid}'], gatewayOwnerPrincipal: '${ownerPrincipal}' });
+// A guard below 0.20.0 ignores allowedAgents and serves every agent: refuse to start on one (a stale lockfile, say).
+if (!Array.isArray(guard.allowedAgents) || !guard.gatewayOwnerPrincipal) throw new Error('this gateway needs @metamynd/agentsafe-mcp-guard >= 0.22.0 to enforce allowedAgents and gatewayOwnerPrincipal - run npm install');
 
 const gateway = createHttpGateway({
   guard,
@@ -2102,6 +2205,11 @@ const gateway = createHttpGateway({
   // above lists which keys may appear; this makes the VALUES of every one of them (a payee, a passenger list) the agent's too.
   // A request whose authorization bound no payload is refused (PAYLOAD_BINDING_REQUIRED) rather than run unbound.
   requirePayloadBinding: true,
+  // What this gateway refuses itself (another agent, a rule, a binding failure) is reported, signed, to your Activity Log
+  // (MAGP 16.4). Claimed executions are already there, through the claim.
+  reportOutcomes: true,
+  // A report the issuer could not take (it was down, say) is kept here and re-sent, so nothing it saw is lost. Gitignored.
+  reportSpool: './reports.spool.jsonl',
   forward: async (req) => {
     let args = {};
     try { args = JSON.parse(req.rawBody?.toString('utf8') || '{}'); } catch { /* empty body */ }
@@ -2168,7 +2276,7 @@ function gatewayEnvExample() {
 }
 
 function gatewayGitignore() {
-  return `node_modules/\n.env\nservice.metamynd.json\n`;
+  return `node_modules/\n.env\nservice.metamynd.json\nreports.spool.jsonl\nreports.spool.jsonl.flushing\n`;
 }
 
 function gatewayReadme(slug, scope, port) {
@@ -2227,14 +2335,20 @@ add another protected route here rather than adding a local function back in \`i
 
 ## What this closes, precisely
 
-Four independent checks, each closing a different bypass an agent (or anything able to call its
-own code, or a network attacker) might attempt:
+Five independent checks, each closing a different bypass an agent (or anything able to call its
+own code, or a network attacker) might attempt - and a record of what it turned away:
 
 - **Direct call.** \`bookFlight()\` doesn't exist in the agent's process. There's nothing to call.
 - **Forged policy bundle.** \`server.mjs\` bakes in \`policyPublicKey\` (from your provisioning
   response) and refuses an unsigned or tampered bundle outright — a party that can intercept the
   fetch (a MITM, a compromised DNS/proxy) cannot hand this gateway a bundle with a higher cap or
   no rules and have it trusted the same as the real one.
+- **Another agent.** Every other check judges the caller by the caller's OWN mandate, which its own owner
+  writes. \`server.mjs\` pins \`allowedAgents\` to this agent and \`gatewayOwnerPrincipal\` to you (MAGP 16.3), so another agent - even one whose
+  owner granted it this action and registered this gateway as its counterparty - is refused
+  \`AGENT_NOT_ADMITTED\` before anything is claimed.
+- **Visibility.** What it refuses itself (another agent, a rule, a binding failure) is reported, signed with its own
+  registered identity, to your Activity Log (MAGP 16.4); what it executes is already there, through the claim.
 - **Confused deputy (payload).** The gateway re-verifies the signed request against this agent's
   own policy AND binds it to the actual request body (payload binding,
   \`@metamynd/agentsafe-http-gateway\` ≥ 0.4.5) — signing a cheap request while executing an
@@ -2396,20 +2510,30 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'U
     if (!policyKey) {
       throw new Error("scaffoldProject: a gateway needs the issuer's policy-signing key (config.issuer.policyKey) to pin its bundle — call ensurePolicyKey() first, or pass withGateway: false");
     }
+    // The gateway acts for exactly this agent (allowedAgents, MAGP §16.3) — never scaffold one that would pin to nobody.
+    if (!config.agentDid) {
+      throw new Error('scaffoldProject: a gateway is pinned to the agent it serves (config.agentDid) — none was given; pass withGateway: false for an agent-only scaffold');
+    }
+    // It is written into generated JavaScript as a string literal: anything but a plain DID is refused, never quoted around.
+    if (!SAFE_DID.test(config.agentDid)) throw new Error(`scaffoldProject: config.agentDid is not a DID: ${JSON.stringify(config.agentDid)}`);
+    // ...and to the owner of its credentials (gatewayOwnerPrincipal, MAGP §16.3), read from the agent's bundle (ensureOwnerPrincipal).
+    if (typeof config.ownerPrincipal !== 'string' || !SAFE_DID.test(config.ownerPrincipal)) {
+      throw new Error('scaffoldProject: a gateway is bound to the principal that owns its credentials (config.ownerPrincipal) — call ensureOwnerPrincipal() first, or pass withGateway: false');
+    }
     const gwDir = join(outDir, 'gateway');
     if (!existsSync(gwDir)) mkdirSync(gwDir, { recursive: true });
-    if (!neutral) {
+    {
       // The gateway's OWN identity — the one that claims and settles this agent's holds (MAGP §8.7.6/
       // §8.7.10), separate from the agent's own DID on purpose (an agent must not be able to release or
-      // lower-settle a hold it authorized itself). `gatewayIdentity` is real and registered when the
-      // caller generated + registered one (main()'s hosted-financial path); a caller that didn't
+      // lower-settle a hold it authorized itself), and the key its reports are signed with (MAGP 16.4) on either shape.
+      // `gatewayIdentity` is real and registered when the caller generated + registered one (main()'s hosted path); a caller that didn't
       // (an older code path, or a direct scaffoldProject() call in a test) falls back to the historical
       // non-cryptographic placeholder — same shape as before this field existed, still parses and runs,
       // just unable to claim a MAINNET hold or sign an authenticated claim on any network.
       const identity = gatewayIdentity ?? { did: `did:local:${scope}-gateway`, keyHex: null };
       writeFileSafe(gwDir, 'service.metamynd.json', JSON.stringify({ serviceDid: identity.did, serviceKey: identity.keyHex }, null, 2) + '\n', force, 0o600);
     }
-    writeFileSafe(gwDir, 'server.mjs', neutral ? gatewayServerFileNeutral(scope, gatewayPort, apiBase, policyKey) : gatewayServerFile(scope, gatewayPort, apiBase, policyKey), force);
+    writeFileSafe(gwDir, 'server.mjs', neutral ? gatewayServerFileNeutral(scope, gatewayPort, apiBase, policyKey, config.agentDid, config.ownerPrincipal) : gatewayServerFile(scope, gatewayPort, apiBase, policyKey, config.agentDid, config.ownerPrincipal), force);
     writeFileSafe(gwDir, 'package.json', gatewayPackageJson(slug), force);
     writeFileSafe(gwDir, '.env.example', neutral ? gatewayEnvExampleNeutral() : gatewayEnvExample(), force);
     writeFileSafe(gwDir, '.gitignore', gatewayGitignore(), force);
@@ -2638,6 +2762,8 @@ const PORT = Number(process.env.PORT || ${gatewayPort});
 // fails BUNDLE_SUBJECT_MISMATCH, not just an unmatched-signature error, because the bundle
 // this gateway serves is only ever this one agent's.
 const AGENT_DID = '${agentDid}';
+// No principal exists offline: the harness bundle and this gateway name the same local owner (MAGP §16.3).
+const HARNESS_OWNER = 'did:local:harness-owner';
 
 // Reshapes the harness's own rules-file shape ({mandate, sops:[{standardKey,document}],
 // standards:[{standardKey,document}]}) into what agentsafe-mcp-guard's verifyRequest expects
@@ -2658,12 +2784,16 @@ function bundleFromRules(rules) {
 // and your agent process both read, so editing it takes effect on the next request everywhere.
 const guard = createMcpGuard({
   serviceDid: 'did:local:${scope}-gateway',
+  allowedAgents: [AGENT_DID], // MAGP §16.3: any other agent is refused AGENT_NOT_ADMITTED before its rules are read
+  gatewayOwnerPrincipal: HARNESS_OWNER, // the local stand-in for the principal that owns this gateway's credentials
   fetchBundle: async (agentDid) => {
     if (agentDid !== AGENT_DID) return { subject: AGENT_DID, mandates: [], sops: [], standards: [] };
     const rules = JSON.parse(readFileSync('../metamynd-rules.json', 'utf8'));
-    return { subject: AGENT_DID, ...bundleFromRules(rules) };
+    return { subject: AGENT_DID, ownerPrincipal: HARNESS_OWNER, ...bundleFromRules(rules) };
   },
 });
+// A guard below 0.20.0 ignores allowedAgents and serves every agent: refuse to start on one (a stale lockfile, say).
+if (!Array.isArray(guard.allowedAgents) || !guard.gatewayOwnerPrincipal) throw new Error('this gateway needs @metamynd/agentsafe-mcp-guard >= 0.22.0 to enforce allowedAgents and gatewayOwnerPrincipal - run npm install');
 
 // One protected route per gated action in index.mjs. This gateway IS the tool, not a proxy in
 // front of one, so a path with no route below is refused (denyByDefault) — nothing to fall through TO.
@@ -3232,7 +3362,7 @@ const WHY = {
   MERCHANT_NOT_ALLOWED: 'the mandate lists which merchants this agent may pay',
   NO_PERMISSION_FOR_ACTION: 'the mandate never granted this action - at any amount',
   NO_MANDATE: 'there is no mandate for this action at all',
-  MANDATE_REVOKED: 'the owner revoked the mandate for this action',
+  MANDATE_REVOKED: 'the owner revoked the mandate for this action',
 };
 
 async function attempt(n, intent, action, args, tool = gatedBookFlight) {
@@ -3258,7 +3388,7 @@ async function attempt(n, intent, action, args, tool = gatedBookFlight) {
     } else {
       console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? 'refused'));
       console.log(dim('     ' + why));
-      console.log(dim('     your tool never ran - the gate refused before execution.'));
+      console.log(dim(g.eventId ? '     decided by the MetaMynd gate - your tool never ran.' : '     decided right here from your signed rules (no network call), and reported for audit - your tool never ran.'));
     }
     dashboard.logDecision(action, args, g);
   }
@@ -3455,7 +3585,7 @@ async function attempt(n, total, step) {
       }
     } else {
       console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? e.message));
-      console.log(dim('     your tool never ran - the gate refused before execution.'));
+      console.log(dim(g.eventId ? '     decided by the MetaMynd gate - your tool never ran.' : '     decided right here from your signed rules (no network call), and reported for audit - your tool never ran.'));
     }
     dashboard.logDecision(action, step.context, g);
   }
@@ -3928,6 +4058,7 @@ async function runClaim(args) {
     keepConfigAndStop('--financial was passed, but the approved agent has NO spending authority (the request was non-financial).');
   }
   if (!args['no-gateway'] && !(await ensurePolicyKey(config, config.apiBase ?? base))) keepConfigAndStop(NO_POLICY_KEY(base));
+  if (!args['no-gateway'] && !(await ensureOwnerPrincipal(config, config.apiBase || base))) keepConfigAndStop(NO_OWNER_PRINCIPAL(base));
   const slug = slugify(state.name || 'metamynd-agent');
   const outDir = resolve(String(args.out || `./${slug}`));
   if (issuedNonFinancial) {
@@ -4137,16 +4268,15 @@ async function main() {
 
   // 3c. The gateway's OWN identity — a real did:key, separate from the agent's own (an agent must
   // never be able to release or lower-settle a hold it authorized itself; only the SERVICE that
-  // claimed it may). Only the financial, with-gateway shape ever claims a hold at all; the
-  // non-financial gateway never calls claimAuthorization() (requireAuthorization is off there), so
-  // it has no counterparty identity to register.
+  // claimed it may) — and, on either shape, the key that signs its reports to your Activity Log (MAGP 16.4): a
+  // non-financial gateway claims nothing, so without a registered identity nothing it ran would reach you.
   let gatewayIdentity = null;
-  if (financial && !args['no-gateway']) {
+  if (!args['no-gateway']) {
     const gwKeypair = generateAgentKeypair();
     const gatewayDid = buildDidKey(rawPublicKeyFromSpkiHex(gwKeypair.publicKeyHex));
     gatewayIdentity = { did: gatewayDid, keyHex: gwKeypair.privateKeyHex };
-    console.log(c.dim(`\n  → registering the gateway's identity as a trusted counterparty (so it can claim this agent's holds) …`));
-    const reg = await registerGatewayCounterparty(base, token, gatewayDid, `${scope}-gateway`);
+    console.log(c.dim(`\n  → registering the gateway's identity as a trusted counterparty (${financial ? "so it can claim this agent's holds and report to you" : 'so its reports reach your Activity Log'}) …`));
+    const reg = await registerGatewayCounterparty(base, token, gatewayDid, `${scope}-gateway`, financial ? 'claim' : 'report', gwKeypair.privateKeyHex);
     if (reg.ok) {
       console.log(`  ${c.green('✓')} gateway DID ${c.b(gatewayDid)} — ${reg.message}`);
     } else {
@@ -4165,6 +4295,7 @@ async function main() {
     for (const n of demo.notDemonstrated) console.log(`  ${c.yellow('!')} not staged in the demo: ${n.rule} ${c.dim('— ' + n.why + '; still enforced')}`);
   }
   if (!args['no-gateway'] && !(await ensurePolicyKey(config, config.apiBase ?? base))) keepConfigAndFail(outDir, config, NO_POLICY_KEY(base));
+  if (!args['no-gateway'] && !(await ensureOwnerPrincipal(config, config.apiBase || base))) keepConfigAndFail(outDir, config, NO_OWNER_PRINCIPAL(base));
   scaffoldProject({ demo, outDir, config, slug, scope, perTxnMax, currency, merchant: financial ? merchants[0] || 'demo-merchant' : merchants[0], sandbox: false, withGateway: !args['no-gateway'], gatewayPort: Number(args['gateway-port']) || DEFAULT_GATEWAY_PORT, force: !!args.force, gatewayIdentity });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.14.10",
+  "version": "0.14.18",
   "description": "Scaffold a MetaMynd/AgentSafe-governed AI agent in one command — logs in, provisions the agent (identity + mandate + SOP + Standards) in a single call, writes agent.metamynd.json plus a runnable agent + separate tool-gateway process that closes direct-call, confused-deputy, replay, and cumulative-spend bypasses. --harness scaffolds a free, local, zero-network governance harness instead.",
   "type": "module",
   "bin": {