@inetafrica/open-claudia 3.3.2 → 3.4.0

package/core/enforcer.js

@@ -112,6 +112,35 @@ function loadTriageGrant(speaker, kind) {
   } catch (e) { return ""; }
 }
 
+// What this proposed output costs on the capability ladder. Talking (a reply,
+// or the triage decision to engage at all) is the weakest rung; running
+// something on the person's behalf is `act`, and a destructive tool run keeps
+// its own rung so an `act` grant can never authorize one.
+function neededCapability(kind, tier) {
+  if (kind === "reply" || kind === "triage") return "read";
+  return String(tier || "").toLowerCase() === "destructive" ? "destructive" : "act";
+}
+
+// The deterministic gate, ahead of the model. A live (principal × room) grant is
+// the owner's own decision and needs no judging — the model is advisory INSIDE a
+// grant, never the thing that issues one. No grant is not a denial here: it just
+// means nothing has been decided yet, so the model layers below still run and
+// anything they don't clearly cover escalates to an owner as before.
+function grantClearance(speaker, kind, tier) {
+  try {
+    if (!speaker || !speaker.speakerId || !speaker.room) return null;
+    const grants = require("./grants");
+    const decision = grants.allows({
+      adapter: speaker.adapterType,
+      senderId: speaker.speakerId,
+      room: speaker.room,
+      needed: neededCapability(kind, tier),
+    });
+    if (!decision.ok) return null;
+    return decision.grant;
+  } catch (e) { return null; }
+}
+
 // 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)
@@ -173,6 +202,7 @@ function logVerdict(audit, context, result) {
     cached: !!result.cached,
     ...(result.retried ? { retried: true } : {}),
     ...(result.code ? { code: result.code } : {}),
+    ...(result.grantId ? { grantId: result.grantId } : {}),
   });
 }
 
@@ -201,6 +231,21 @@ function createEnforcerService(dependencies = {}) {
       logVerdict(audit, auditContext, disabled);
       return disabled;
     }
+    const cleared = grantClearance(speaker, kind, tier);
+    if (cleared) {
+      const granted = {
+        decision: "allow",
+        reason: `covered by owner grant ${cleared.id} (${cleared.capability}${cleared.room === "*" ? ", all rooms" : ""})`,
+        ...providerMetadata(null),
+        status: "granted",
+        grantId: cleared.id,
+      };
+      logVerdict(audit, auditContext, granted);
+      if (cleared.turnsRemaining != null) {
+        try { require("./grants").consumeTurn(cleared.id); } catch (e) {}
+      }
+      return granted;
+    }
     const key = `${namespace}:${cacheKey({ kind, relationship, mandate, guardrails, channelRules, turnGrant, unverified, payload: clipped, tier })}`;
     const hit = cacheGet(key);
     if (hit) {
@@ -336,7 +381,7 @@ function esc(s) {
 // 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, strandedMandate = "" }) {
+async function postOwnerButtons(rec, owner, { kind, summary, reason, strandedMandate = "", expiredNote = "" }) {
   const adapter = adapterFor(owner.adapter);
   if (!adapter) return false;
   const who = rec.personName || "An external contact";
@@ -381,14 +426,26 @@ async function postOwnerButtons(rec, owner, { kind, summary, reason, strandedMan
   const lines = [head, ``, ...askBlock, ...body,
     unverifiedLine ? `\n${unverifiedLine}` : ``,
     strandedMandate ? `\n⚠️ ${esc(strandedMandate)}` : ``,
+    expiredNote ? `\n⏳ ${esc(expiredNote)}` : ``,
     reason ? `\nWhy I'm checking: ${esc(reason)}` : ``];
   const yes = kind === "triage" ? "✅ Yes, handle it" : "✅ Approve once";
   const no = kind === "triage" ? "⛔ No, decline" : "⛔ Deny";
+  // Reach row: standing capability, and how far it travels. The default is
+  // deliberately the narrow one — a grant is for THIS person in THIS room, so
+  // trusting someone in one group never silently trusts them in another. Only
+  // offered when the record identifies the speaker apart from the room.
+  const reachRow = rec.speakerId && rec.room
+    ? [
+      { text: `✅ Always — here`, callback_data: `grn:${rec.id}:room` },
+      { text: `🌍 Always — everywhere`, callback_data: `grn:${rec.id}:all` },
+    ]
+    : null;
   const keyboard = { inline_keyboard: [
     [
       { text: yes, callback_data: `apr:${rec.id}:ok` },
       { text: no, callback_data: `apr:${rec.id}:no` },
     ],
+    ...(reachRow ? [reachRow] : []),
     [
       { text: "📝 Make a rule…", callback_data: `apr:${rec.id}:rule` },
       ...(verifyRow || []),
@@ -426,7 +483,12 @@ async function escalate({
   const approvals = require("./approvals");
   const relationship = require("./relationship");
   const audit = safeAudit();
-  const owner = await relationship.ownerTarget();
+  // Approval belongs to the owner SET. The card goes to every reachable owner;
+  // the first is recorded as the nominal approver only because the record has
+  // one such field — the apr: handler authorizes on isChatOwner, so any of them
+  // can decide, and decide() is idempotent so the second tap can't flip it.
+  const owners = await relationship.ownerTargets();
+  const owner = owners[0];
   if (!owner) {
     if (audit) audit.log("enforcer.escalate.failed", { reason: "no reachable owner", guardKind: kind, person: speaker && speaker.name });
     return { ok: false, escalated: false, reason: "no reachable owner to approve" };
@@ -478,6 +540,22 @@ async function escalate({
       }
     }
   } catch (e) { strandedMandate = ""; }
+  // A grant that simply ran out looks, from the owner's side, exactly like one
+  // they never gave — the bot just starts asking again. Say which line lapsed
+  // and when, so re-approving is an informed choice rather than a puzzle.
+  let expiredNote = "";
+  try {
+    if (speaker && speaker.slug) {
+      const entities = require("./entities");
+      const ent = entities.readEntity(speaker.slug);
+      const section = String((ent && ent.sections && ent.sections.Mandate) || "");
+      const lapsed = require("./mandates").expiredMandateLines(speaker.slug, section);
+      if (lapsed.length) {
+        const first = lapsed[0];
+        expiredNote = `A previous grant for ${personName || "them"} expired on ${first.expiresAt}: "${first.text.slice(0, 100)}"${lapsed.length > 1 ? ` (+${lapsed.length - 1} more)` : ""}. That is why I'm asking again.`;
+      }
+    }
+  } catch (e) { expiredNote = ""; }
   const rec = approvals.create({
     tool: kind === "reply" ? "external-reply" : kind === "triage" ? "external-triage" : "external-action",
     verb: "",
@@ -507,8 +585,12 @@ async function escalate({
     entitySlug: (speaker && speaker.slug) || "",
     inboundText,
     channelLabel,
+    speakerId: (speaker && speaker.speakerId) || "",
+    room: (speaker && speaker.room) || "",
   });
-  const posted = await postOwnerButtons(rec, owner, { kind, summary, reason, strandedMandate });
+  const results = await Promise.all(owners.map((o) =>
+    postOwnerButtons(rec, o, { kind, summary, reason, strandedMandate, expiredNote }).catch(() => false)));
+  const posted = results.some(Boolean);
   if (!posted) {
     approvals.decide(rec.id, "denied", "owner-unreachable");
     if (audit) audit.log("enforcer.escalate.failed", { reason: "could not post to owner", id: rec.id });

package/core/fsutil.js

@@ -52,4 +52,45 @@ function readJsonWithFallback(file, fallback) {
   return fallback;
 }
 
-module.exports = { atomicWriteFileSync, readJsonWithFallback };
+// Cross-process mutex for read-modify-write on a shared JSON store. Atomic
+// writes stop a file being torn in half, but they cannot stop two processes
+// each reading the same list, each appending one entry, and the second rename
+// discarding the first's. The bot and the `open-claudia` CLI are separate
+// processes writing the same stores, so that race is reachable.
+//
+// An exclusive-create lockfile is the portable primitive (no flock on every
+// filesystem we run on). A held lock older than LOCK_STALE_MS is assumed to
+// belong to a process that died mid-write and is reclaimed, so a crash can
+// never wedge the store permanently. Failing to acquire is not fatal: the
+// caller proceeds unlocked, which is exactly today's behaviour.
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+function withFileLock(file, fn) {
+  const lock = `${file}.lock`;
+  let held = null;
+  for (let attempt = 0; attempt < 21 && !held; attempt += 1) {
+    try {
+      held = fs.openSync(lock, "wx", 0o600);
+    } catch (error) {
+      if (error.code !== "EEXIST") break;
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+          fs.rmSync(lock, { force: true });
+          continue;
+        }
+      } catch (_) { continue; }
+      Atomics.wait(LOCK_WAIT, 0, 0, 5);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    if (held !== null) {
+      try { fs.closeSync(held); } catch (_) {}
+      try { fs.rmSync(lock, { force: true }); } catch (_) {}
+    }
+  }
+}
+
+module.exports = { atomicWriteFileSync, readJsonWithFallback, withFileLock };

package/core/grants.js

@@ -0,0 +1,221 @@
+// (principal × room) capability grants — the only source of non-owner
+// authority on this pod.
+//
+// The three external-policy layers that predate this file are each keyed by
+// exactly one thing: global guardrails apply to every external person, channel
+// rules to everyone in one room, a person's mandate to one person in every
+// room. The pair — THIS person, in THIS room — had no home, so trusting
+// someone in one group silently trusted them in every group they shared with
+// the bot.
+//
+// Two boundaries this module must never cross:
+//   1. Authority is pod-owned. Room membership and platform roles (a Kazee
+//      groupAdmin, a Telegram chat admin) confer nothing here. Whoever
+//      administers a room decides only whether the agent is IN it — an agent is
+//      a user, and that is exactly the power any member holds over any other.
+//   2. Rooms are surface-agnostic. `<surface>:<id>` covers a Kazee group, a
+//      Spaces task thread, a Telegram group and a DM alike, so a pod that lives
+//      only on Spaces and never touches Kazee chat resolves grants identically.
+
+const fs = require("fs");
+const { GRANTS_FILE } = require("./config");
+const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
+
+// Ordered weakest → strongest. A grant answers with one of these; the enforcer
+// maps a proposed action onto the same ladder and refuses anything above.
+const CAPABILITIES = ["read", "act", "destructive"];
+
+const ALL_ROOMS = "*";
+
+function nowIso() { return new Date().toISOString(); }
+
+function capabilityRank(capability) {
+  const idx = CAPABILITIES.indexOf(String(capability || "").toLowerCase());
+  return idx < 0 ? -1 : idx;
+}
+
+function normalizeCapability(capability) {
+  const c = String(capability || "").toLowerCase();
+  return CAPABILITIES.includes(c) ? c : "read";
+}
+
+// Rooms are keyed `<surface>:<id>`, matching core/identity.conversationKeyFor
+// so a caller can hand us a conversation key directly.
+function roomKey(surface, roomId) {
+  const s = String(surface || "").trim().toLowerCase();
+  const r = String(roomId || "").trim();
+  if (!s || !r) return "";
+  return `${s}:${r}`;
+}
+
+function principalKey(adapter, senderId) {
+  const a = String(adapter || "").trim().toLowerCase();
+  const s = String(senderId || "").trim();
+  if (!a || !s) return "";
+  return `${a}:${s}`;
+}
+
+function load() {
+  const raw = readJsonWithFallback(GRANTS_FILE, null);
+  const list = raw && Array.isArray(raw.grants) ? raw.grants : [];
+  return list.filter((g) => g && typeof g === "object");
+}
+
+function save(grants) {
+  atomicWriteFileSync(GRANTS_FILE, JSON.stringify({ grants }, null, 2), { backup: true });
+}
+
+function isLive(grant, at = Date.now()) {
+  if (!grant || grant.revokedAt) return false;
+  if (grant.expiresAt && Date.parse(grant.expiresAt) <= at) return false;
+  if (grant.turnsRemaining != null && Number(grant.turnsRemaining) <= 0) return false;
+  return true;
+}
+
+// The deterministic lookup that replaces the LLM as the gate. Returns the
+// strongest live grant for this principal in this room, preferring a grant
+// issued for this exact room over an all-rooms grant, so a narrow room grant
+// can never be weakened by a broad one and vice versa.
+function resolve({ adapter, senderId, room }) {
+  const principal = principalKey(adapter, senderId);
+  const target = String(room || "");
+  if (!principal) return null;
+  const at = Date.now();
+  const candidates = load().filter((g) =>
+    isLive(g, at)
+    && principalKey(g.principal?.adapter, g.principal?.channelId) === principal
+    && (g.room === target || g.room === ALL_ROOMS));
+  if (!candidates.length) return null;
+  candidates.sort((a, b) => {
+    // Exact room beats all-rooms; then the stronger capability wins.
+    const exact = (b.room === target) - (a.room === target);
+    if (exact) return exact;
+    return capabilityRank(b.capability) - capabilityRank(a.capability);
+  });
+  return candidates[0];
+}
+
+// True when this principal may take an action at `needed` strength in `room`.
+// Owners never reach here — they are resolved before any grant lookup.
+function allows({ adapter, senderId, room, needed = "read", subject = null }) {
+  const grant = resolve({ adapter, senderId, room });
+  if (!grant) return { ok: false, reason: "no_grant", grant: null };
+  if (capabilityRank(grant.capability) < capabilityRank(needed)) {
+    return { ok: false, reason: "capability_too_low", grant };
+  }
+  const scope = Array.isArray(grant.scope) ? grant.scope : [];
+  // An empty scope means "anything within this capability" — a scoped grant
+  // only covers the subjects it names.
+  if (scope.length && subject && !scope.includes(String(subject))) {
+    return { ok: false, reason: "out_of_scope", grant };
+  }
+  return { ok: true, reason: "granted", grant };
+}
+
+// Only an owner may call this — enforced by the caller, which holds the turn
+// context needed to know who is asking.
+function grant({
+  adapter,
+  senderId,
+  room,
+  capability = "read",
+  scope = [],
+  grantedBy = "",
+  personId = null,
+  expiresAt = null,
+  turns = null,
+  allRooms = false,
+}) {
+  const principal = principalKey(adapter, senderId);
+  if (!principal) throw new Error("adapter and senderId are required");
+  const target = allRooms ? ALL_ROOMS : String(room || "");
+  if (!target) throw new Error("room is required unless allRooms is set");
+  const grants = load();
+  // Re-granting the same pair replaces rather than stacks, so revoking one
+  // record can never leave a weaker duplicate behind still granting access.
+  const kept = grants.filter((g) =>
+    !(principalKey(g.principal?.adapter, g.principal?.channelId) === principal
+      && g.room === target
+      && isLive(g)));
+  const record = {
+    id: `grant_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    principal: { adapter: String(adapter).toLowerCase(), channelId: String(senderId) },
+    personId: personId || null,
+    room: target,
+    capability: normalizeCapability(capability),
+    scope: Array.isArray(scope) ? scope.map(String) : [],
+    grantedBy: String(grantedBy || ""),
+    grantedAt: nowIso(),
+    expiresAt: expiresAt || null,
+    turnsRemaining: turns == null ? null : Number(turns),
+    revokedAt: null,
+  };
+  kept.push(record);
+  save(kept);
+  return record;
+}
+
+function revoke(grantId) {
+  const grants = load();
+  const g = grants.find((x) => x.id === grantId);
+  if (!g || g.revokedAt) return null;
+  g.revokedAt = nowIso();
+  save(grants);
+  return g;
+}
+
+// Revoke every live grant for a principal, optionally only in one room.
+function revokeAllFor({ adapter, senderId, room = null }) {
+  const principal = principalKey(adapter, senderId);
+  if (!principal) return 0;
+  const grants = load();
+  let n = 0;
+  for (const g of grants) {
+    if (!isLive(g)) continue;
+    if (principalKey(g.principal?.adapter, g.principal?.channelId) !== principal) continue;
+    if (room && g.room !== room) continue;
+    g.revokedAt = nowIso();
+    n += 1;
+  }
+  if (n) save(grants);
+  return n;
+}
+
+// One-turn grants burn down as they are used, so an owner's "just this once"
+// can't linger as standing access.
+function consumeTurn(grantId) {
+  const grants = load();
+  const g = grants.find((x) => x.id === grantId);
+  if (!g || g.turnsRemaining == null) return null;
+  g.turnsRemaining = Math.max(0, Number(g.turnsRemaining) - 1);
+  save(grants);
+  return g;
+}
+
+function list({ includeExpired = false } = {}) {
+  const all = load();
+  return includeExpired ? all : all.filter((g) => isLive(g));
+}
+
+function listForRoom(room, { includeExpired = false } = {}) {
+  return list({ includeExpired }).filter((g) => g.room === String(room) || g.room === ALL_ROOMS);
+}
+
+module.exports = {
+  CAPABILITIES,
+  ALL_ROOMS,
+  GRANTS_FILE,
+  roomKey,
+  principalKey,
+  capabilityRank,
+  normalizeCapability,
+  isLive,
+  resolve,
+  allows,
+  grant,
+  revoke,
+  revokeAllFor,
+  consumeTurn,
+  list,
+  listForRoom,
+};

package/core/handlers.js

@@ -20,6 +20,7 @@ const {
   getProviderSettings,
   getProjectSessions, getLastProjectSession, userOwnsProviderSession,
   createSessionCallbackToken, linkIdentity,
+  roomSettingsFor, setRoomSetting,
 } = require("./state");
 const { canonicalForChannel, canonicalForTelegram, normalizeCanonicalUserId, channelKey, identities, isConfiguredOwnerChannel, removeIdentityMapping } = require("./identity");
 const { isChatAuthorized, isChatOwner, recordPendingAuthRequest, authRequestLabel, hasOwner, bootstrapOwner } = require("./access");
@@ -208,6 +209,13 @@ function switchProviderState(providerId, options = {}) {
     providerSettings: structuredClone(state.providerSettings || {}),
     isFirstMessage: state.isFirstMessage,
   };
+  // The room is authoritative for who answers in it; the speaker's own value
+  // stays updated as their default for rooms they have never pinned. Without
+  // the room write, switching provider only moved the switcher — everyone else
+  // in the room, and every job it spawned, stayed on the old one.
+  const roomKey = state.roomKey ? String(state.roomKey) : "";
+  const previousRoomBackend = roomKey ? (roomSettingsFor(roomKey)?.backend ?? null) : null;
+  if (roomKey) setRoomSetting(roomKey, "backend", provider);
   state.settings.backend = provider;
   if (Object.prototype.hasOwnProperty.call(options, "model")) state.settings.model = options.model;
   const project = getProjectKey(state);
@@ -220,6 +228,7 @@ function switchProviderState(providerId, options = {}) {
     state.activeSessions = previous.activeSessions;
     state.providerSettings = previous.providerSettings;
     state.settings.backend = previous.provider;
+    if (roomKey) setRoomSetting(roomKey, "backend", previousRoomBackend);
     state.isFirstMessage = previous.isFirstMessage;
   });
   return persisted.ok
@@ -1815,6 +1824,46 @@ register({
   },
 });
 
+register({
+  name: "grants", description: "View/revoke capability grants (who may do what, in which room)", args: "[revoke <id> | revoke-all <adapter>:<sender>]", ownerOnly: true,
+  handler: async (env, { tail }) => {
+    if (!ownerEnv(env)) return send("Owner only — grants are restricted.");
+    const grants = require("./grants");
+    const trimmed = (tail || "").trim();
+    const [sub, ...restArr] = trimmed ? trimmed.split(/\s+/) : [];
+    const subCmd = (sub || "").toLowerCase();
+
+    if (subCmd === "revoke") {
+      const id = restArr.join(" ").trim();
+      if (!id) return send("Usage: /grants revoke <id>");
+      const g = grants.revoke(id);
+      if (!g) return send(`No live grant with id ${id}.`);
+      try { require("./audit").log("grant.revoked", { id: g.id, room: g.room, capability: g.capability }); } catch (e) {}
+      return send(`Revoked ${g.id} — ${g.capability} in ${g.room === grants.ALL_ROOMS ? "every room" : g.room}.`);
+    }
+
+    if (subCmd === "revoke-all") {
+      const target = restArr.join(" ").trim();
+      const idx = target.lastIndexOf(":");
+      if (idx <= 0) return send("Usage: /grants revoke-all <adapter>:<senderId>");
+      const n = grants.revokeAllFor({ adapter: target.slice(0, idx), senderId: target.slice(idx + 1) });
+      return send(n ? `Revoked ${n} grant${n === 1 ? "" : "s"} for ${target}.` : `No live grants for ${target}.`);
+    }
+
+    const live = grants.list();
+    if (live.length === 0) {
+      return send("No capability grants yet.\n\nA grant is what lets a non-owner act: it covers ONE person in ONE room, so trusting someone in one group never trusts them elsewhere. Make one from an approval card (\"Always — here\" / \"Always — everywhere\").");
+    }
+    const lines = live.map((g) => {
+      const where = g.room === grants.ALL_ROOMS ? "everywhere" : g.room;
+      const until = g.expiresAt ? ` · until ${g.expiresAt.slice(0, 10)}` : "";
+      const turns = g.turnsRemaining != null ? ` · ${g.turnsRemaining} turn(s) left` : "";
+      return `🔑 [${g.id}] ${g.principal.adapter}:${g.principal.channelId} → ${g.capability} in ${where}${until}${turns}`;
+    });
+    return send(`Capability grants (${live.length}):\n\n${lines.join("\n")}\n\n/grants revoke <id> · /grants revoke-all <adapter>:<senderId>\nFile: ${grants.GRANTS_FILE}`);
+  },
+});
+
 register({
   name: "ideas", description: "View/manage the self-improvement backlog", args: "[add <idea> | remove <id>]",
   handler: async (env, { tail }) => {

package/core/intro-flow.js

@@ -7,7 +7,7 @@ const people = require("./people");
 const intros = require("./intros");
 const audit = require("./audit");
 const registry = require("./adapter-registry");
-const { bootstrapOwner, loadAuth, saveAuth, updateAuthorizedChatEnv } = require("./access");
+const { bootstrapOwner, mutateAuth, updateAuthorizedChatEnv } = require("./access");
 const { CHAT_ID } = require("./config");
 
 const MAX_BIO_LEN = 500;
@@ -103,25 +103,26 @@ async function notifyOwnerAboutIntro(intro) {
 // from people.isOwner: dropping it here is what demoted owners approved onto
 // a second channel (isChatOwner reads this file, not the person).
 function ensureAuthEntry(channelId, { name = null, username = null, isOwner = false } = {}) {
-  const auth = loadAuth();
   const id = String(channelId);
-  const existing = auth.authorized.find((a) => String(a.chatId) === id);
-  if (existing) {
-    if (isOwner && existing.isOwner !== true) {
-      existing.isOwner = true;
-      saveAuth(auth);
+  // Under the store lock: this is the write that sets isOwner, and an unlocked
+  // read-modify-write racing another approval would drop the promotion — the
+  // roster would look right to whoever wrote last and the owner would be
+  // guarded on their own channel.
+  return mutateAuth((auth) => {
+    const existing = auth.authorized.find((a) => String(a.chatId) === id);
+    if (existing) {
+      if (isOwner && existing.isOwner !== true) existing.isOwner = true;
+      return auth;
     }
+    auth.authorized.push({
+      chatId: id,
+      name: name || "",
+      username: username || null,
+      isOwner: !!isOwner,
+      authorizedAt: new Date().toISOString(),
+    });
     return auth;
-  }
-  auth.authorized.push({
-    chatId: id,
-    name: name || "",
-    username: username || null,
-    isOwner: !!isOwner,
-    authorizedAt: new Date().toISOString(),
   });
-  saveAuth(auth);
-  return auth;
 }
 
 // A sender whose transport user id already maps to a person is never

package/core/mandates.js

@@ -88,6 +88,15 @@ function activeMandateText(sectionText, now) {
     .join("\n");
 }
 
+// The lines that HAVE lapsed for one person. activeMandateText drops them
+// silently by design (the judge must never see a dead grant), but silence is
+// wrong for the owner: a tap-grant expiring after GRANT_TTL_DAYS looked
+// identical to never having granted it, so the bot simply started asking again
+// with nothing to explain why. Callers surface these at the moment they bite.
+function expiredMandateLines(slug, sectionText, now) {
+  return parseMandate(slug, sectionText, now).filter((l) => l.expired);
+}
+
 function defaultGrantExpiry(now) {
   if (!GRANT_TTL_DAYS) return null;
   return utcDate((now === undefined ? Date.now() : now) + GRANT_TTL_DAYS * 24 * 60 * 60 * 1000);
@@ -155,6 +164,6 @@ function revokeLine(id) {
 module.exports = {
   GRANT_TTL_DAYS,
   normalize, splitExpiry, formatLine, isExpired, lineId,
-  parseMandate, activeMandateText, defaultGrantExpiry, extractExpiry,
+  parseMandate, activeMandateText, expiredMandateLines, defaultGrantExpiry, extractExpiry,
   listPersonMandates, revokeLine,
 };