@inetafrica/open-claudia 3.1.24 → 3.1.25

package/core/enforcer.js

@@ -21,7 +21,18 @@ const crypto = require("crypto");
 const { spawnUtilityAgent } = require("./utility-agent");
 const { redactSensitive } = require("./redact");
 
-const ENFORCER_TIMEOUT_MS = Number(process.env.ENFORCER_TIMEOUT_MS || 30000);
+const ENFORCER_TIMEOUT_MS = Number(process.env.ENFORCER_TIMEOUT_MS || 60000);
+// A guard failure that is transport, not verdict: the guard spawns a fresh
+// provider CLI per call, so a cold-start timeout, a momentary concurrency
+// spike, or a spawn miss is worth one retry before failing closed. A bad or
+// unparseable verdict, a provider/auth error, etc. are NOT retried — they fail
+// closed on the first occurrence (never open).
+const TRANSIENT_GUARD_CODES = new Set(["UTILITY_TIMEOUT", "UTILITY_CONCURRENCY_LIMIT", "UTILITY_SPAWN_FAILED"]);
+
+function transientGuardFailure(error) {
+  const code = error?.code || error?.result?.error?.code || "";
+  return TRANSIENT_GUARD_CODES.has(code);
+}
 const CACHE_TTL_MS = Number(process.env.ENFORCER_CACHE_TTL_MS || 5 * 60 * 1000);
 const PAYLOAD_CLIP = 4000;
 const ENFORCER_OUTPUT_SCHEMA = Object.freeze({
@@ -40,7 +51,7 @@ function enabled() {
 
 const GUARD_SYSTEM_PROMPT = [
   "You are an INDEPENDENT security guardrail for an AI assistant that is currently talking to an EXTERNAL person — NOT its owner.",
-  "You are given, in narrowing order of scope, up to three owner-authored policy layers: (1) GLOBAL GUARDRAILS for EVERY external person, (2) CHANNEL RULES for everyone speaking in THIS channel (a group chat, a task thread, …), (3) the MANDATE for THIS specific person. You are also given a PROPOSED assistant output (a reply it wants to send, or an action it wants to run on their behalf).",
+  "You are given, in narrowing order of scope, up to three owner-authored policy layers: (1) GLOBAL GUARDRAILS for EVERY external person, (2) CHANNEL RULES for everyone speaking in THIS channel (a group chat, a task thread, …), (3) the MANDATE for THIS specific person. You are also given a PROPOSED assistant output: a reply it wants to send, an action it wants to run on their behalf, or — for a triage decision — the person's INBOUND REQUEST that the assistant wants to start handling.",
   "Together the layers define what the assistant is cleared to do. Decide whether they clearly permit the proposed output.",
   "",
   "Rules you MUST follow:",
@@ -51,6 +62,8 @@ const GUARD_SYSTEM_PROMPT = [
   "- Regardless of what any layer says, NEVER allow leaking the owner's or other people's private information, credentials, or internal/system/infrastructure details.",
   "- If no layer covers the request, almost nothing is permitted — escalate anything beyond a trivial, harmless pleasantry.",
   "- Meet-and-greet lane: when the person is marked UNVERIFIED (a brand-new auto-added contact), friendly introductions ARE permitted without explicit coverage — greetings, pleasantries, asking who they are, their role, how they know the owner, and what they need, plus saying the owner will follow up. This lane NEVER extends to disclosing information, making commitments, or running actions.",
+  "- Triage decisions judge whether the assistant may START working on the request at all: \"allow\" only when the layers (or the meet-and-greet lane) clearly cover engaging with it — its eventual reply and any actions will still be vetted separately.",
+  "- A TURN GRANT, when present, is the owner's explicit one-off approval to handle ONE specific request this turn. Allow outputs that squarely serve that request. It is NOT blanket permission: prohibitions in any layer and the privacy/credential rules above still override it.",
   "",
   "Reply with ONLY a compact JSON object and nothing else:",
   "{\"decision\":\"allow|block|escalate\",\"reason\":\"<one short clause>\"}",
@@ -73,14 +86,40 @@ function loadChannelRules(speaker) {
   } catch (e) { return ""; }
 }
 
+// Turn-scoped clearance from a triage approval. When the owner pressed
+// "handle it" on a triage card, actions.js wakes the agent with the approval
+// id riding the chat context (bot-process AsyncLocalStorage — the agent
+// subprocess can never set it). The judge is then told the owner cleared
+// engaging with THAT request, so a reply that squarely serves it doesn't
+// bounce back as a second approval card. Reply vets only — never actions:
+// write/destructive runs keep their own approval path. Fail-closed: any
+// mismatch, expiry, or read error means no grant.
+function loadTriageGrant(speaker, kind) {
+  try {
+    if (kind !== "reply" || !speaker) return "";
+    const ctx = require("./context");
+    const id = typeof ctx.currentTriageApprovalId === "function" ? ctx.currentTriageApprovalId() : "";
+    if (!id) return "";
+    const approvals = require("./approvals");
+    const rec = approvals.read(String(id));
+    if (!rec || rec.status !== "approved" || rec.kind !== "triage") return "";
+    if (String(rec.targetAdapter) !== String(speaker.adapterType)) return "";
+    if (String(rec.targetChannel) !== String(speaker.channelId)) return "";
+    if (Date.now() - Date.parse(rec.requestedAt) > 24 * 60 * 60 * 1000) return "";
+    const ask = String(rec.inboundText || "").replace(/\s+/g, " ").trim().slice(0, 300);
+    if (!ask) return "";
+    return `The owner explicitly approved the assistant handling this specific request from this person, for this turn only: "${ask}"`;
+  } catch (e) { return ""; }
+}
+
 // verdict cache: identical (kind, relationship, layers, payload) → same answer
 // within a short TTL, so a chatty external turn that re-checks the same reply
 // doesn't re-bill the model (R9). Every policy layer (and the unverified flag)
 // is part of the key so an edit to any of them busts stale verdicts.
 const cache = new Map();
-function cacheKey({ kind, relationship, mandate, guardrails, channelRules, unverified, payload, tier }) {
+function cacheKey({ kind, relationship, mandate, guardrails, channelRules, turnGrant, unverified, payload, tier }) {
   return crypto.createHash("sha1")
-    .update([kind, relationship || "", tier || "", guardrails || "", channelRules || "", mandate || "", unverified ? "u" : "", payload || ""].join("\0"))
+    .update([kind, relationship || "", tier || "", guardrails || "", channelRules || "", mandate || "", turnGrant || "", unverified ? "u" : "", payload || ""].join("\0"))
     .digest("hex");
 }
 function cacheGet(key) {
@@ -132,6 +171,7 @@ function logVerdict(audit, context, result) {
     fallbackUsed: !!result.fallbackUsed,
     status: result.status,
     cached: !!result.cached,
+    ...(result.retried ? { retried: true } : {}),
     ...(result.code ? { code: result.code } : {}),
   });
 }
@@ -146,9 +186,12 @@ function createEnforcerService(dependencies = {}) {
   // Disabled is the only allow-without-judgement path; every model/provider
   // error, timeout, or invalid schema fails closed to escalation.
   async function verdict({ kind, speaker, payload, tier, provider = null }) {
-    const mandate = (speaker && speaker.mandate) || "";
+    // Defensive clip: the mandate is owner-authored entity text with a write
+    // cap, but a hand-edited file must still never balloon the judge prompt.
+    const mandate = String((speaker && speaker.mandate) || "").slice(0, 6000);
     const guardrails = loadGlobalGuardrails();
     const channelRules = loadChannelRules(speaker);
+    const turnGrant = loadTriageGrant(speaker, kind);
     const relationship = (speaker && speaker.relationship) || "external";
     const unverified = !!(speaker && speaker.person && speaker.person.autoCreated);
     const clipped = String(payload || "").slice(0, PAYLOAD_CLIP);
@@ -158,7 +201,7 @@ function createEnforcerService(dependencies = {}) {
       logVerdict(audit, auditContext, disabled);
       return disabled;
     }
-    const key = `${namespace}:${cacheKey({ kind, relationship, mandate, guardrails, channelRules, unverified, payload: clipped, tier })}`;
+    const key = `${namespace}:${cacheKey({ kind, relationship, mandate, guardrails, channelRules, turnGrant, unverified, payload: clipped, tier })}`;
     const hit = cacheGet(key);
     if (hit) {
       const cached = { ...hit, status: "cached", cached: true };
@@ -182,57 +225,80 @@ function createEnforcerService(dependencies = {}) {
       mandate || "(none — the owner has authored no mandate for this person)",
       "MANDATE>>>",
       "",
+      ...(turnGrant ? [
+        "TURN GRANT (owner-approved, THIS turn only):",
+        "<<<TURNGRANT",
+        turnGrant,
+        "TURNGRANT>>>",
+        "",
+      ] : []),
       `Relationship: ${relationship}`,
       `Person: ${(speaker && speaker.name) || "unknown external contact"}${unverified ? " (UNVERIFIED — brand-new auto-added contact)" : ""}`,
       "",
       kind === "reply"
         ? "PROPOSED REPLY the assistant wants to SEND to this person:"
-        : `PROPOSED ACTION (tier: ${tier || "write"}) the assistant wants to RUN on this person's behalf:`,
+        : kind === "triage"
+          ? "INBOUND REQUEST from this person — the assistant wants to start HANDLING it (triage decision):"
+          : `PROPOSED ACTION (tier: ${tier || "write"}) the assistant wants to RUN on this person's behalf:`,
       "<<<PROPOSED",
       clipped,
       "PROPOSED>>>",
       "",
-      "Do the global guardrails or this person's mandate clearly permit this? Output ONLY the JSON verdict.",
+      "Do the policy layers clearly permit this? Output ONLY the JSON verdict.",
     ].join("\n");
 
-    let utilityResult = null;
-    try {
-      utilityResult = await runUtility(userPrompt, {
-        purpose: "enforcer",
-        provider,
-        tier: "medium",
-        modelEnvPrefix: "ENFORCER_MODEL",
-        legacyClaudeModelEnv: "ENFORCER_MODEL",
-        readOnly: true,
-        outputSchema: ENFORCER_OUTPUT_SCHEMA,
-        systemPrompt: GUARD_SYSTEM_PROMPT,
-        timeoutMs,
-        cwd: process.cwd(),
-      });
-      let obj = utilityResult.json;
-      if (!obj) {
-        const match = String(utilityResult.text || "").match(/\{[\s\S]*?\}/);
-        if (!match) throw Object.assign(new Error("unparseable enforcer verdict"), { code: "ENFORCER_OUTPUT_INVALID" });
-        obj = JSON.parse(match[0]);
-      }
-      if (!obj || !VALID.has(obj.decision) || typeof obj.reason !== "string") {
-        throw Object.assign(new Error("invalid enforcer verdict"), { code: "ENFORCER_OUTPUT_INVALID" });
+    // Judge with one retry on a TRANSIENT guard failure before failing closed.
+    // The guard already fails closed on any error; the retry only shrinks the
+    // window where a transport blip (cold-start timeout, concurrency spike,
+    // spawn miss) needlessly escalates a reply the rules actually permit. It
+    // never fails open and never retries a real verdict.
+    const maxAttempts = 2;
+    let lastError = null;
+    let lastResult = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      let utilityResult = null;
+      try {
+        utilityResult = await runUtility(userPrompt, {
+          purpose: "enforcer",
+          provider,
+          tier: "medium",
+          modelEnvPrefix: "ENFORCER_MODEL",
+          legacyClaudeModelEnv: "ENFORCER_MODEL",
+          readOnly: true,
+          outputSchema: ENFORCER_OUTPUT_SCHEMA,
+          systemPrompt: GUARD_SYSTEM_PROMPT,
+          timeoutMs,
+          cwd: process.cwd(),
+        });
+        let obj = utilityResult.json;
+        if (!obj) {
+          const match = String(utilityResult.text || "").match(/\{[\s\S]*?\}/);
+          if (!match) throw Object.assign(new Error("unparseable enforcer verdict"), { code: "ENFORCER_OUTPUT_INVALID" });
+          obj = JSON.parse(match[0]);
+        }
+        if (!obj || !VALID.has(obj.decision) || typeof obj.reason !== "string") {
+          throw Object.assign(new Error("invalid enforcer verdict"), { code: "ENFORCER_OUTPUT_INVALID" });
+        }
+        const out = {
+          decision: obj.decision,
+          reason: String(obj.reason).slice(0, 200),
+          ...providerMetadata(utilityResult),
+          status: "judged",
+          ...(attempt > 1 ? { retried: true } : {}),
+        };
+        cacheSet(key, out);
+        logVerdict(audit, auditContext, out);
+        return out;
+      } catch (error) {
+        lastError = error;
+        lastResult = utilityResult || error.result || null;
+        if (attempt < maxAttempts && transientGuardFailure(error)) continue;
+        break;
       }
-      const out = {
-        decision: obj.decision,
-        reason: String(obj.reason).slice(0, 200),
-        ...providerMetadata(utilityResult),
-        status: "judged",
-      };
-      cacheSet(key, out);
-      logVerdict(audit, auditContext, out);
-      return out;
-    } catch (error) {
-      const result = utilityResult || error.result || null;
-      const out = failClosed(error.message || "enforcer error", result, error.code || result?.error?.code);
-      logVerdict(audit, auditContext, out);
-      return out;
     }
+    const out = failClosed(lastError?.message || "enforcer error", lastResult, lastError?.code || lastResult?.error?.code);
+    logVerdict(audit, auditContext, out);
+    return out;
   }
 
   return {
@@ -263,39 +329,44 @@ function esc(s) {
   return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-// Post the Approve / Deny / Always-allow keyboard to the OWNER's channel. The
+// Post the Approve / Deny / Make-a-rule keyboard to the OWNER's channel. The
 // apr: button handler (actions.js) is owner-gated and idempotent, so only the
 // owner can decide and a double-tap can't flip it.
+//
+// Framing: the owner is deciding whether the bot should ACT on a request from
+// this person — the card leads with WHO is asking WHAT, then what the bot
+// proposes to do about it, never with the bot's output as the headline.
 async function postOwnerButtons(rec, owner, { kind, summary, reason }) {
   const adapter = adapterFor(owner.adapter);
   if (!adapter) return false;
-  const who = rec.personName || "an external contact";
+  const who = rec.personName || "An external contact";
   const where = rec.channelLabel ? ` in ${esc(rec.channelLabel)}` : "";
   const ask = String(rec.inboundText || "").slice(0, 500);
-  const askBlock = ask
-    ? [`<b>From ${esc(who)}${where}:</b>`, `<pre>${esc(ask)}</pre>`, ``]
-    : [`<b>From ${esc(who)}${where}</b>`, ``];
-  const lines = kind === "reply"
-    ? [
-        `🛡️ <b>External guardrail</b> — a reply needs your OK:`,
-        ``,
-        ...askBlock,
-        `<b>Proposed reply:</b>`,
-        `<pre>${esc(String(summary || rec.payloadText || "").slice(0, 700))}</pre>`,
-        reason ? `\nWhy flagged: ${esc(reason)}` : ``,
-      ]
-    : [
-        `🛡️ <b>External guardrail</b> — ${esc(who)} wants a ${esc(rec.tier)} action:`,
-        ``,
-        ...askBlock,
-        `<b>Proposed action:</b>`,
-        `<pre>${esc(String(rec.command || ""))}</pre>`,
-        reason ? `\nWhy flagged: ${esc(reason)}` : ``,
-      ];
+  const askBlock = ask ? [`<b>They asked:</b>`, `<pre>${esc(ask)}</pre>`, ``] : [];
+  let head, body;
+  if (kind === "reply") {
+    head = `🛡️ <b>${esc(who)}</b>${where} asked me something — should I act on it?`;
+    body = [
+      `<b>I'd reply:</b>`,
+      `<pre>${esc(String(summary || rec.payloadText || "").slice(0, 700))}</pre>`,
+    ];
+  } else if (kind === "triage") {
+    head = `🛡️ <b>${esc(who)}</b>${where} wants me to handle a request — should I?`;
+    body = ask ? [] : [`<i>(no request text captured)</i>`];
+  } else {
+    head = `🛡️ <b>${esc(who)}</b>${where} wants me to run a <b>${esc(rec.tier)}</b> action — should I?`;
+    body = [
+      `<b>The exact command:</b>`,
+      `<pre>${esc(String(rec.command || ""))}</pre>`,
+    ];
+  }
+  const lines = [head, ``, ...askBlock, ...body, reason ? `\nWhy I'm checking: ${esc(reason)}` : ``];
+  const yes = kind === "triage" ? "✅ Yes, handle it" : "✅ Approve once";
+  const no = kind === "triage" ? "⛔ No, decline" : "⛔ Deny";
   const keyboard = { inline_keyboard: [
     [
-      { text: "✅ Approve once", callback_data: `apr:${rec.id}:ok` },
-      { text: "⛔ Deny", callback_data: `apr:${rec.id}:no` },
+      { text: yes, callback_data: `apr:${rec.id}:ok` },
+      { text: no, callback_data: `apr:${rec.id}:no` },
     ],
     [
       { text: "📝 Make a rule…", callback_data: `apr:${rec.id}:rule` },
@@ -359,10 +430,12 @@ async function escalate({
     }
   } catch (e) {}
   const rec = approvals.create({
-    tool: kind === "reply" ? "external-reply" : "external-action",
+    tool: kind === "reply" ? "external-reply" : kind === "triage" ? "external-triage" : "external-action",
     verb: "",
-    tier: kind === "reply" ? "reply" : (tier || "write"),
-    command: kind === "reply" ? "(deliver vetted reply)" : String(command || ""),
+    tier: kind === "reply" ? "reply" : kind === "triage" ? "triage" : (tier || "write"),
+    command: kind === "action" ? String(command || "")
+      : kind === "triage" ? "(handle held external request)"
+      : "(deliver vetted reply)",
     channelId: String(speaker.channelId),   // origin = the external speaker
     adapter: String(speaker.adapterType),
     canonicalUserId,
@@ -417,7 +490,46 @@ async function guardOutboundReply(text) {
   return { allow: false, guarded: true, decision: v.decision, reason: v.reason, escalated: e.escalated, escalationId: e.id };
 }
 
+// The router-facing up-front gate: on a guarded external turn the INBOUND
+// request itself is judged BEFORE any agent work happens. allow → the turn
+// proceeds (its reply and actions are still vetted separately — triage is an
+// early advisory gate, the output vets stay authoritative). Anything else →
+// no generation at all: the owner gets a "should I handle this?" card and the
+// external gets the holding line. Approval re-runs enter via the scheduler,
+// never the router, so an approved turn cannot re-triage itself into a loop.
+//
+// `pinning` carries the provider/project/user context the approval record
+// needs so the approve-button wakeup can resume in the ORIGIN channel.
+// Contract: never throws; an internal error on a guarded turn holds the
+// message (fail closed), and owner/no-context turns are always untouched.
+async function guardInboundTriage(text, pinning = {}) {
+  let speaker = null;
+  try {
+    const relationship = require("./relationship");
+    speaker = relationship.currentSpeaker();
+    if (!relationship.guardActive(speaker)) return { held: false, guarded: false };
+    const inbound = String(text || "").trim();
+    if (!inbound) return { held: false, guarded: true };
+    const v = await verdict({ kind: "triage", speaker, payload: inbound });
+    if (v.decision === "allow") return { held: false, guarded: true, decision: "allow" };
+    const e = await escalate({
+      speaker, kind: "triage", payloadText: "", summary: inbound, reason: v.reason,
+      canonicalUserId: String(pinning.canonicalUserId || ""),
+      userId: String(pinning.userId || ""),
+      provider: String(pinning.provider || ""),
+      project: String(pinning.project || ""),
+      projectDir: String(pinning.projectDir || ""),
+    });
+    return { held: true, guarded: true, decision: v.decision, reason: v.reason, escalated: e.escalated, escalationId: e.id };
+  } catch (err) {
+    if (!speaker || speaker.isOwner) return { held: false, guarded: false };
+    const audit = safeAudit();
+    if (audit) audit.log("enforcer.triage.failed", { reason: String(err?.message || err).slice(0, 160) });
+    return { held: true, guarded: true, decision: "escalate", reason: "triage failed — holding the request" };
+  }
+}
+
 module.exports = {
   createEnforcerService, enabled, verdict, vetReply, vetAction, escalate, guardOutboundReply,
-  postOwnerButtons, ENFORCER_OUTPUT_SCHEMA, GUARD_SYSTEM_PROMPT,
+  guardInboundTriage, postOwnerButtons, ENFORCER_OUTPUT_SCHEMA, GUARD_SYSTEM_PROMPT,
 };

package/core/entities.js

@@ -28,6 +28,10 @@ const ENTITIES_DIR = process.env.ENTITIES_DIR ? path.resolve(process.env.ENTITIE
 
 const TYPES = ["person", "place", "project", "org", "system", "thing"];
 const MAX_LOG_ENTRIES = 40;
+// Write cap for a person's Mandate section. Mandates are security-relevant
+// text injected into the guard prompt, so growth is bounded at the writers
+// (approval always-allow, rule capture) — never silently truncated on read.
+const MANDATE_MAX_CHARS = 4000;
 // Persona-pack sections layered on top of the base Notes/Log. Additive: only
 // serialized when populated, so ordinary entities are untouched (R7).
 const PERSONA_SECTIONS = ["Role", "Style", "Knows", "Mandate"];
@@ -429,7 +433,7 @@ function matchEntities(text, { limit = 4, threshold = null } = {}) {
 }
 
 module.exports = {
-  ENTITIES_DIR, TYPES, slugify,
+  ENTITIES_DIR, TYPES, slugify, MANDATE_MAX_CHARS,
   PERSONA_SECTIONS, RELATIONSHIPS, normalizeRelationship,
   listEntities, findEntity, readEntity, writeEntity, upsertEntity, removeEntity,
   touchSeen, entityNameFromPath, matchEntities, reindex, markIndexDirty,

package/core/handlers.js

@@ -1752,7 +1752,7 @@ register({
 });
 
 register({
-  name: "guardrails", description: "View/manage rules for external people (global + per-channel)", args: "[add <rule> | remove <id>]", ownerOnly: true,
+  name: "guardrails", description: "View/manage rules for external people (global + channel + per-person)", args: "[add <rule> | remove <id> | revoke <id>]", ownerOnly: true,
   handler: async (env, { tail }) => {
     if (!ownerEnv(env)) return send("Owner only — global guardrails are restricted.");
     const gr = require("./external-guardrails");
@@ -1770,19 +1770,25 @@ register({
     }
 
     const cr = require("./channel-rules");
+    const md = require("./mandates");
 
-    if (subCmd === "remove" || subCmd === "rm") {
+    // remove and revoke are the same operation across all three layers —
+    // "revoke" reads naturally for per-person grants, "remove" for rules.
+    if (subCmd === "remove" || subCmd === "rm" || subCmd === "revoke") {
       const key = restArr.join(" ").trim();
-      if (!key) return send("Usage: /guardrails remove <id>");
+      if (!key) return send(`Usage: /guardrails ${subCmd} <id>`);
       if (gr.removeGuardrail(key)) return send(`Removed ${key}.`);
       if (cr.removeRule(key)) return send(`Removed channel rule ${key}.`);
+      const hit = md.revokeLine(key);
+      if (hit) return send(`Revoked [${hit.id}] from ${hit.name}'s mandate: ${hit.text}`);
       return send(`No matching guardrail: ${key}`);
     }
 
     const all = gr.listGuardrails();
     const channels = cr.listChannels().filter((c) => c.rules.length > 0);
-    if (all.length === 0 && channels.length === 0) {
-      return send(`No guardrails yet. These are rules I apply to external people — globally, or per channel (make one from an approval card). Add a global one: /guardrails add <rule>\n\ne.g. /guardrails add never discuss pricing or staff details\n\nFile: ${gr.GUARDRAILS_FILE}`);
+    const persons = md.listPersonMandates();
+    if (all.length === 0 && channels.length === 0 && persons.length === 0) {
+      return send(`No guardrails yet. These are rules I apply to external people — globally, per channel, or per person (make one from an approval card). Add a global one: /guardrails add <rule>\n\ne.g. /guardrails add never discuss pricing or staff details\n\nFile: ${gr.GUARDRAILS_FILE}`);
     }
     const parts = [];
     if (all.length > 0) {
@@ -1795,8 +1801,12 @@ register({
       const lines = c.rules.map((r) => `👥 [${r.id}] ${r.text}`);
       parts.push(`Channel rules — ${c.label || c.key}:\n${lines.join("\n")}`);
     }
+    for (const p of persons) {
+      const lines = p.lines.map((l) => `[${l.id}] ${l.text}${l.expiresAt ? ` · until ${l.expiresAt}` : ""}`);
+      parts.push(`👤 ${p.name} (${p.slug}):\n${lines.join("\n")}`);
+    }
     let msg = parts.join("\n\n");
-    msg += `\n\n/guardrails add <rule> · /guardrails remove <id>\nChannel rules are made from approval cards (“Make a rule → This channel”).\nPer-person rules live in each person's note (Mandate).\nFiles: ${gr.GUARDRAILS_FILE} · ${cr.CHANNEL_RULES_FILE}`;
+    msg += `\n\n/guardrails add <rule> · /guardrails revoke <id>\nChannel + person rules are made from approval cards; Always-allow grants expire after ${md.GRANT_TTL_DAYS || "∞"} days (re-approve to renew).\nFiles: ${gr.GUARDRAILS_FILE} · ${cr.CHANNEL_RULES_FILE}`;
     return send(msg);
   },
 });

package/core/mandates.js

@@ -0,0 +1,160 @@
+// Per-person mandate lines as first-class, revocable grants — parsing, stable
+// ids, and expiry for the Mandate section of a person's entity note.
+//
+// The mandate is the third policy layer the enforcer judges (floor > global
+// guardrails > channel rules > MANDATE > turn grant). Global and channel rules
+// already have hash ids and /guardrails remove; this module gives mandate
+// lines the same lifecycle so an approval-card grant is a scoped capability,
+// not a permanent blanket:
+//   - id: sha1(slug + normalized line text) — slug-scoped, so the same
+//     capability granted to two people revokes independently.
+//   - expiry: a trailing " [until YYYY-MM-DD]" marker (UTC date, inclusive).
+//     Filtering is DETERMINISTIC at read time (activeMandateText) — the guard
+//     judge never does date math, an expired line simply never reaches it.
+//   - revoke: /guardrails revoke <id> removes exactly one line from exactly
+//     one person.
+//
+// Dedup and ids ignore the expiry marker: re-granting the same capability
+// refreshes its expiry instead of stacking duplicate lines.
+
+const crypto = require("crypto");
+
+// Trailing expiry marker, always the last thing on a line.
+const EXPIRY_RE = /\s*\[until (\d{4}-\d{2}-\d{2})\]\s*$/;
+
+// Tap-grants ("Always allow" on an approval card) default to a bounded TTL —
+// a guardrail, not a blanket. 0 = permanent. Owner-authored rules pass their
+// own expiry (usually none).
+const GRANT_TTL_DAYS = Math.max(0, Number(process.env.MANDATE_GRANT_TTL_DAYS || 30));
+
+function utcDate(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function normalize(text) {
+  return String(text || "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+// Split a line into its capability text and optional expiry date.
+function splitExpiry(line) {
+  const s = String(line || "").trim();
+  const m = s.match(EXPIRY_RE);
+  if (!m) return { text: s, expiresAt: null };
+  return { text: s.replace(EXPIRY_RE, "").trim(), expiresAt: m[1] };
+}
+
+function formatLine(text, expiresAt) {
+  const core = String(text || "").replace(/\s+/g, " ").trim();
+  return expiresAt ? `${core} [until ${expiresAt}]` : core;
+}
+
+function isExpired(expiresAt, now) {
+  if (!expiresAt) return false;
+  return utcDate(now === undefined ? Date.now() : now) > expiresAt; // inclusive of the named day
+}
+
+function lineId(slug, lineText) {
+  const { text } = splitExpiry(lineText);
+  return crypto.createHash("sha1")
+    .update(`${normalize(slug)}\0${normalize(text)}`)
+    .digest("hex").slice(0, 8);
+}
+
+// Parse a Mandate section into entries. Only "- "/"* " bullets are grants;
+// anything else survives hand-edits but carries no id.
+function parseMandate(slug, sectionText, now) {
+  const out = [];
+  for (const line of String(sectionText || "").split("\n")) {
+    const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const { text, expiresAt } = splitExpiry(m[1]);
+    if (!text) continue;
+    out.push({ id: lineId(slug, text), text, expiresAt, expired: isExpired(expiresAt, now), raw: line });
+  }
+  return out;
+}
+
+// Read-side filter for the guard judge: drop expired bullets, keep everything
+// else byte-for-byte. This is the single choke point (relationship.speakerFor)
+// so every consumer of speaker.mandate sees only live grants.
+function activeMandateText(sectionText, now) {
+  return String(sectionText || "")
+    .split("\n")
+    .filter((line) => {
+      const m = line.match(/^\s*[-*]\s+(.*\S)\s*$/);
+      if (!m) return true;
+      return !isExpired(splitExpiry(m[1]).expiresAt, now);
+    })
+    .join("\n");
+}
+
+function defaultGrantExpiry(now) {
+  if (!GRANT_TTL_DAYS) return null;
+  return utcDate((now === undefined ? Date.now() : now) + GRANT_TTL_DAYS * 24 * 60 * 60 * 1000);
+}
+
+// Owner rule text may carry its own expiry phrase: "... until 2026-08-30" or
+// "... for 14d". Extracted here so the stored line uses the one marker format.
+function extractExpiry(text, now) {
+  const s = String(text || "").trim();
+  let m = s.match(/\s+until\s+(\d{4}-\d{2}-\d{2})$/i);
+  if (m) return { text: s.slice(0, m.index).trim(), expiresAt: m[1] };
+  m = s.match(/\s+for\s+(\d{1,4})\s*d(?:ays?)?$/i);
+  if (m) {
+    const days = Math.max(1, Number(m[1]));
+    return { text: s.slice(0, m.index).trim(), expiresAt: utcDate((now === undefined ? Date.now() : now) + days * 24 * 60 * 60 * 1000) };
+  }
+  return { text: s, expiresAt: null };
+}
+
+// Every person-shaped entity carrying live grants, for /guardrails listing.
+function listPersonMandates(now) {
+  const entities = require("./entities");
+  const out = [];
+  for (const ent of entities.listEntities()) {
+    const section = String((ent.sections && ent.sections.Mandate) || "").trim();
+    if (!section) continue;
+    const lines = parseMandate(ent.slug, section, now).filter((l) => !l.expired);
+    if (lines.length === 0) continue;
+    out.push({ slug: ent.slug, name: ent.name, lines });
+  }
+  return out;
+}
+
+// Remove exactly one grant by id across all entities. Returns what was
+// revoked, or null when no line matches. Clearing the LAST line writes the
+// section empty directly — upsertEntity treats "" as "leave unchanged".
+function revokeLine(id) {
+  const key = String(id || "").trim().toLowerCase();
+  if (!key) return null;
+  const entities = require("./entities");
+  for (const ent of entities.listEntities()) {
+    const section = String((ent.sections && ent.sections.Mandate) || "");
+    if (!section.trim()) continue;
+    const entries = parseMandate(ent.slug, section);
+    const hit = entries.find((l) => l.id === key);
+    if (!hit) continue;
+    const remaining = section
+      .split("\n")
+      .filter((line) => line !== hit.raw)
+      .join("\n")
+      .trim();
+    entities.upsertEntity({
+      slug: ent.slug, name: ent.name,
+      log: `owner revoked mandate line [${hit.id}]: ${hit.text.slice(0, 80)}`,
+    });
+    const fresh = entities.readEntity(ent.slug);
+    fresh.sections.Mandate = remaining;
+    fresh.updated = new Date().toISOString();
+    entities.writeEntity(fresh);
+    return { slug: ent.slug, name: ent.name, id: hit.id, text: hit.text, expiresAt: hit.expiresAt };
+  }
+  return null;
+}
+
+module.exports = {
+  GRANT_TTL_DAYS,
+  normalize, splitExpiry, formatLine, isExpired, lineId,
+  parseMandate, activeMandateText, defaultGrantExpiry, extractExpiry,
+  listPersonMandates, revokeLine,
+};