@inetafrica/open-claudia 3.5.74 → 3.5.76

package/core/connected-apps.js

@@ -96,14 +96,28 @@ function getJson(baseUrl, urlPath, token) {
 }
 
 // Ask central which apps this bot token is a member of. Returns [] on failure
-// (caller keeps the last-known list).
-async function fetchConnectedApps() {
+// (caller keeps the last-known list). A personal bot watches the apps its owner
+// ticked in her consent (core/bot-profile.js), as her: its own key only works
+// in Kazee Chat once its key limit is on.
+async function fetchConnectedApps({ request } = {}) {
+  const botProfile = require("./bot-profile");
+  if (botProfile.isPersonal()) {
+    return botProfile.consentApplications().map((name) => ({ id: name, name }));
+  }
   const token = botToken();
   if (!token) return [];
-  const res = await getJson(CENTRAL_URL, "/api/principal/applications", token);
+  const res = request
+    ? (await request("GET", "/api/principal/applications", token)).body
+    : await getJson(CENTRAL_URL, "/api/principal/applications", token);
   return Array.isArray(res?.applications) ? res.applications : [];
 }
 
+// The token to poll an app with: a pass for a personal bot (core/app-pass.js),
+// the bot's own key otherwise.
+async function tokenForApp(app, opts) {
+  return require("./app-pass").tokenFor(String(app?.name || ""), opts);
+}
+
 function registerConnector(connector) {
   if (!connector || !connector.appKey) throw new Error("connector needs an appKey");
   connectors.set(connector.appKey, connector);
@@ -141,7 +155,7 @@ async function pollApp(app) {
   const connector = connectorFor(app);
   if (!connector) { state.status = "no-connector"; return; }
   try {
-    const items = await connector.poll(app, botToken());
+    const items = await connector.poll(app, await tokenForApp(app));
     const added = recordItems(state, items || []);
     state.lastPollAt = now;
     state.status = "ok";
@@ -244,6 +258,7 @@ module.exports = {
   stopConnectedApps,
   registerConnector,
   fetchConnectedApps,
+  tokenForApp,
   snapshot,
   getAllInboxes,
   STORE_FILE,

package/core/handlers.js

@@ -642,7 +642,9 @@ register({
   handler: async (env) => {
     if (!ownerEnv(env)) return;
     const { mint, TTL_MS } = require("./web-otp");
-    const { token } = mint();
+    // The link names who asked, so a personal bot's dashboard knows it is
+    // her (core/access.js); an autonomous bot ignores it.
+    const { token } = mint({ userId: env.userId || "" });
     const url = `${dashboardBaseUrl()}/otp/${token}`;
     const mins = Math.round(TTL_MS / 60000);
     const lines = [`Web dashboard login (valid ${mins} min, single use):`, url];

package/core/identity.js

@@ -98,6 +98,20 @@ function isConfiguredOwnerChannel(transport, channelId) {
   // is the same configured Kazee owner id — recognise them on Spaces too, else
   // the owner's own comments are classed external (default-deny).
   if (t === "spaces") return !!cfg.config.KAZEE_OWNER_USER_ID && c === String(cfg.config.KAZEE_OWNER_USER_ID);
+  // A personal bot's dashboard and voice bridge are owner channels only when
+  // they name its one owner (Central's); see access.transportOwnerUserId.
+  if (t === "voice" || t === "web") {
+    let personal = false, owner = "";
+    try {
+      const botProfile = require("./bot-profile");
+      personal = botProfile.isPersonal();
+      owner = botProfile.ownerUserId();
+    } catch (e) {}
+    if (personal) {
+      if (!owner || c !== owner) return false;
+      return t === "web" || String(cfg.config.VOICE_OWNER_USER_ID || "") === owner;
+    }
+  }
   if (t === "voice") return c === String(cfg.config.VOICE_OWNER_USER_ID || "voice-owner");
   // Web dashboard chat: fixed single-owner channel gated by the dashboard
   // session, so its identity is operator-implied rather than env-declared.

package/core/lessons.js

@@ -184,7 +184,8 @@ function topicLessons(dir, { exclude = null, max = 3, maxChars = 900 } = {}) {
   const lessons = readLessons().filter((l) => l.src === dir);
   if (lessons.length === 0) return [];
   const skip = exclude || new Set(injectedLessons().map((l) => l.id));
-  const meta = reconcileMeta(lessons);
+  // The full list: reconciling just this pack would drop every other lesson's meta.
+  const meta = reconcileMeta();
   const ranked = lessons.filter((l) => !skip.has(l.id)).sort((a, b) => {
     const ma = meta[a.id] || {}, mb = meta[b.id] || {};
     return (mb.reinforced || 0) - (ma.reinforced || 0)

package/core/loopback.js

@@ -108,7 +108,13 @@ const JSON_KINDS = new Set([
   "tool-gate",
   "say", "call-say", "call", "tts", "transcribe",
   "card-send", "card-update", "card-show", "decide-add", "decide-list", "decide-cancel",
+  "owner-setup",
+  "view-send", "view-push",
 ]);
+// view-send carries the page and its preview (each at most 2 MB) as base64.
+const VIEW_FILE_MAX = 2 * 1024 * 1024;
+const VIEW_SEND_BODY_MAX = 6 * 1024 * 1024;
+const VIEW_PUSH_DATA_MAX = 16384;
 
 // Who is calling, decided by the bot: the principal of a LIVE run whose
 // OC_RUN_ATTEST matches (see core/speaker-attest), else UNATTRIBUTED. Nothing
@@ -302,17 +308,121 @@ async function handleCardKind(res, kind, payload, { channelId, adapterId, adapte
   return reply(res, 400, { error: `unknown card command ${kind}` });
 }
 
+// HTML views (Kazee Chat only; core/views.js answers their events). Like a
+// card, a view's events wake the conversation that sent it, so only a live,
+// attributed run may send one, into that run's own room and thread.
+function decodeViewFile(file, what, exts) {
+  if (!file || typeof file !== "object") return { error: `missing ${what}` };
+  const fileName = path.basename(String(file.fileName || "")).replace(/[^A-Za-z0-9._-]/g, "_");
+  const ext = path.extname(fileName).toLowerCase();
+  if (!exts.includes(ext)) return { error: `the ${what} must be a ${exts.join(" or ")} file (got ${fileName || "no name"})` };
+  if (typeof file.data !== "string" || !file.data) return { error: `the ${what} is empty` };
+  const buffer = Buffer.from(file.data, "base64");
+  if (!buffer.length) return { error: `the ${what} is empty` };
+  if (buffer.length > VIEW_FILE_MAX) return { error: `the ${what} is over 2 MB` };
+  return { buffer, fileName, ext };
+}
+
+async function handleViewKind(res, kind, payload, { channelId, adapterId, adapter }) {
+  const cards = require("./cards");
+  const caller = callerOf(payload);
+  if (!caller.attributed) {
+    return reply(res, 403, { error: "views can only be used from a live, attributed run" });
+  }
+  const own = (caller.adapterId && registry.findAdapter(caller.adapterId)) || adapter;
+  const room = String(caller.channelId || channelId);
+  const threadId = threadForCaller(caller, room, payload.threadId);
+
+  if (kind === "view-send") {
+    if (own.type !== "kazee" || typeof own.sendCard !== "function" || typeof own.uploadMedia !== "function") {
+      return reply(res, 501, { error: `views are Kazee Chat only (this conversation is on ${own.type || adapterId})` });
+    }
+    const title = String(payload.title || "").trim();
+    if (!title || title.length > 140) return reply(res, 400, { error: "a view needs a --title of at most 140 characters" });
+    const body = payload.body ? String(payload.body).trim() : "";
+    if (body.length > 600) return reply(res, 400, { error: "--body is over 600 characters" });
+    const label = payload.label ? String(payload.label).trim() : "";
+    if (label.length > 40) return reply(res, 400, { error: "--label is over 40 characters" });
+    const wake = payload.wake === undefined || payload.wake === null || payload.wake === "" ? "each" : String(payload.wake);
+    if (!["each", "none"].includes(wake)) return reply(res, 400, { error: "--wake must be each or none" });
+    let handler = null;
+    if (payload.handler) {
+      handler = String(payload.handler);
+      if (!path.isAbsolute(handler)) return reply(res, 400, { error: "the handler path must be absolute (the bot process has its own cwd)" });
+      let st = null;
+      try { st = fs.statSync(handler); } catch (_) {}
+      if (!st || !st.isFile()) return reply(res, 400, { error: `handler not found: ${handler}` });
+    }
+    const page = decodeViewFile(payload.page, "page", [".html", ".htm"]);
+    if (page.error) return reply(res, 400, { error: page.error });
+    const preview = payload.preview ? decodeViewFile(payload.preview, "preview", [".png", ".jpg", ".jpeg"]) : null;
+    if (preview && preview.error) return reply(res, 400, { error: preview.error });
+
+    let block;
+    try {
+      const pageId = await own.uploadMedia(room, { buffer: page.buffer, fileName: page.fileName, contentType: "text/html; charset=utf-8" });
+      block = { type: "view", page: pageId };
+      if (preview) {
+        block.preview = await own.uploadMedia(room, {
+          buffer: preview.buffer, fileName: preview.fileName, contentType: preview.ext === ".png" ? "image/png" : "image/jpeg",
+        });
+      }
+      if (label) block.label = label;
+    } catch (e) {
+      return reply(res, 502, { error: `upload failed: ${e.message}` });
+    }
+    const card = { v: 1, kind: "report", title, ...(body ? { body } : {}), blocks: [block] };
+    let messageId;
+    try {
+      messageId = await own.sendCard(room, card, { threadId });
+    } catch (e) {
+      return reply(res, 400, { error: e.message });
+    }
+    if (!messageId) return reply(res, 502, { error: "Kazee Chat returned no message id for the view" });
+    // wake "none" on the card path: a view takes no card answers; its events
+    // go through core/views.js with the view's own policy.
+    cards.recordSentCard({
+      messageId, title, kind: "report", wake: "none",
+      origin: cardOrigin(caller, payload, own, threadId),
+      view: { handler, wake },
+    });
+    return reply(res, 200, { ok: true, messageId, handler, wake, card });
+  }
+
+  if (kind === "view-push") {
+    const rec = cards.getCard(payload.messageId);
+    if (!rec || !rec.view) return reply(res, 404, { error: "not a view this bot sent (or older than the card ledger)" });
+    const mine = rec.origin && rec.origin.canonicalUserId && rec.origin.canonicalUserId === caller.canonicalUserId;
+    if (!mine && caller.owner !== true) return reply(res, 403, { error: "only the conversation's person or the owner can push to this view" });
+    const target = (rec.origin && registry.findAdapter(rec.origin.adapter)) || own;
+    if (typeof target.pushView !== "function") return reply(res, 501, { error: "views are Kazee Chat only" });
+    const data = payload.data === undefined ? null : payload.data;
+    if (Buffer.byteLength(JSON.stringify(data)) > VIEW_PUSH_DATA_MAX) return reply(res, 400, { error: "the data is over 16 KB as JSON" });
+    try {
+      await target.pushView(String(payload.messageId), data, payload.to ? String(payload.to) : undefined);
+    } catch (e) {
+      return reply(res, 400, { error: e.message });
+    }
+    return reply(res, 200, { ok: true });
+  }
+  return reply(res, 400, { error: `unknown view command ${kind}` });
+}
+
 function readBodyAsString(req, max = 64 * 1024) {
   return new Promise((resolve, reject) => {
-    let buf = "";
+    // Bytes first, text at the end: a big body (view-send) arrives in many
+    // chunks, and a chunk may end inside a multi-byte character.
+    const chunks = [];
+    let size = 0;
     req.on("data", (d) => {
-      buf += d.toString();
-      if (buf.length > max) {
+      chunks.push(d);
+      size += d.length;
+      if (size > max) {
         req.destroy();
         reject(new Error("body too large"));
       }
     });
-    req.on("end", () => resolve(buf));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
     req.on("error", reject);
   });
 }
@@ -368,7 +478,7 @@ async function handleSend(req, res, url, kind) {
 }
 
 async function handleJson(req, res, url, kind) {
-  const body = await readBodyAsString(req);
+  const body = await readBodyAsString(req, kind === "view-send" ? VIEW_SEND_BODY_MAX : undefined);
   let payload = {};
   if (body.trim()) {
     try { payload = JSON.parse(body); }
@@ -439,6 +549,7 @@ async function handleJson(req, res, url, kind) {
         maxHops: out.maxHops,
         source: out.source,
         target: out.target,
+        newThread: out.newThread === true,
       });
     } catch (e) {
       return reply(res, e.status || 500, { error: e.message });
@@ -452,6 +563,29 @@ async function handleJson(req, res, url, kind) {
     return handleCardKind(res, kind, payload, { channelId, adapterId, adapter });
   }
 
+  if (kind === "view-send" || kind === "view-push") {
+    return handleViewKind(res, kind, payload, { channelId, adapterId, adapter });
+  }
+  // `open-claudia owner-setup` (core/owner-setup.js): the one-tap card that
+  // lets a personal bot's owner switch it on or renew it. It always goes to
+  // HER direct chat, never this room; the bot decides what it says from its
+  // own profile. A run that is not hers sends each card at most once a day.
+  if (kind === "owner-setup") {
+    const caller = callerOf(payload);
+    if (!caller.attributed) return reply(res, 403, { error: "owner-setup can only be used from a live, attributed run" });
+    const ownerSetup = require("./owner-setup");
+    const planned = ownerSetup.plan({ apps: Array.isArray(payload.apps) ? payload.apps.map(String) : [], renew: payload.renew === true });
+    if (planned.refused) return reply(res, 400, { error: planned.refused });
+    if (planned.nothing) return reply(res, 200, { ok: true, sent: null, nothing: planned.nothing });
+    try {
+      const sent = await ownerSetup.tellOwnerAsked(planned, { owner: caller.owner === true });
+      if (!sent) return reply(res, 502, { error: "could not reach the owner's direct chat in Kazee" });
+      return reply(res, 200, { ok: true, sent, title: planned.card ? planned.card.title : null });
+    } catch (e) {
+      return reply(res, 502, { error: e.message });
+    }
+  }
+
   if (kind === "call-say") {
     try {
       const result = await require("./call-speech").speak({ ...payload, channelId, userId, adapter: adapterId });

package/core/migration-backup.js

@@ -257,8 +257,12 @@ function acquireLock(root) {
       let stale = false;
       try {
         const stat = assertRegularFile(filePath, "MIGRATION_LOCKED", "migration lock");
-        const pid = Number(fs.readFileSync(filePath, "utf8").trim());
-        if (Number.isSafeInteger(pid) && pid > 0 && Date.now() - stat.mtimeMs > 1000) {
+        const text = fs.readFileSync(filePath, "utf8").trim();
+        const pid = Number(text);
+        // An old empty lock was left by a run that died before writing its pid
+        // (kazee-people, Oct 2026: 817 restarts); nobody can hold it.
+        if (!text && Date.now() - stat.mtimeMs > 1000) stale = true;
+        else if (Number.isSafeInteger(pid) && pid > 0 && Date.now() - stat.mtimeMs > 1000) {
           // We haven't taken the lock yet, so one naming our own pid was left by an
           // earlier run that died holding it. In a container the bot is pid 1 after
           // every restart, so the liveness probe below would find "us" alive forever.

package/core/owner-setup.js

@@ -0,0 +1,216 @@
+// The owner switches a personal bot on (or renews it) with one tap (SEC-28,
+// Sumeet 30 Oct 2026).
+//
+// Instead of telling her where the page is, the bot sends its owner a Kazee
+// Chat card with one link button that opens Central straight at the form; she
+// only taps Confirm or Renew. Used when an app refuses a pass because she has
+// not switched the bot on there (core/app-pass.js), for the daily renew notice
+// a week before the consent ends, and for `open-claudia owner-setup`.
+//
+// The card is a "report" card (no questions) with a `link` block, at most 2 per
+// card (chat-central, 30 Oct). If the card can't be sent the owner gets the old
+// text, with the link.
+//
+// The bot can never switch itself on: the link only opens the form, and only
+// the owner, signed in to Central, can confirm it.
+
+const botProfile = require("./bot-profile");
+const appPass = require("./app-pass");
+
+const CENTRAL_WEB = "https://central.kazee.africa";
+const ASSISTANTS_PATH = "/settings/assistants";
+const LINK_LABEL_MAX = 40;
+const CONSENT_DAYS = 90;
+const SEND_EVERY_MS = 24 * 60 * 60 * 1000;
+
+// The refusals the owner fixes herself by switching the bot on for the app.
+const SWITCH_ON_REASONS = new Set(["consent-none", "consent-off", "consent-ended", "app-not-ticked"]);
+
+const sentAt = new Map(); // card key -> last sent at (non-owner callers only)
+let lastRenewDay = "";
+
+function switchOnUrl(botId, apps) {
+  const list = apps.map((a) => encodeURIComponent(a)).join(",");
+  return `${CENTRAL_WEB}${ASSISTANTS_PATH}?bot=${encodeURIComponent(botId)}&do=switch-on&apps=${list}`;
+}
+
+function renewUrl(botId) {
+  return `${CENTRAL_WEB}${ASSISTANTS_PATH}?bot=${encodeURIComponent(botId)}&do=renew`;
+}
+
+// "Tickets", "Tickets and CRM", "Tickets, CRM and Spaces".
+function listWords(words) {
+  if (words.length <= 1) return words.join("");
+  return `${words.slice(0, -1).join(", ")} and ${words[words.length - 1]}`;
+}
+
+function dateWords(when) {
+  const d = new Date(when);
+  if (!Number.isFinite(d.getTime())) return "soon";
+  return d.toLocaleDateString("en-GB", { weekday: "long", day: "numeric", month: "long", year: "numeric" });
+}
+
+// The bot as the owner knows it: its own name (BOT_NAME, else its hostname),
+// else Central's name for it; and Central's id.
+function botForCard() {
+  let name = "";
+  try { name = String(require("./config").settingValue("BOT_NAME") || "").trim(); } catch (_) {}
+  // Else the pod's name from its public hostname (as the dashboard does).
+  if (!name) {
+    try {
+      const url = String(require("./config").settingValue("WEB_PUBLIC_URL") || "").trim();
+      if (url) name = new URL(url).hostname.split(".")[0] || "";
+    } catch (_) {}
+  }
+  if (!name) name = botProfile.get()?.bot?.name || "your assistant";
+  return { id: String(botProfile.get()?.bot?.id || ""), name: name.charAt(0).toUpperCase() + name.slice(1) };
+}
+
+function linkBlock(label, url) {
+  return { type: "link", label: String(label).slice(0, LINK_LABEL_MAX), url };
+}
+
+function buildSwitchOnCard({ bot, apps }) {
+  const labels = apps.map(appPass.appLabel);
+  const where = labels.length <= 2 ? listWords(labels) : "your apps";
+  return {
+    v: 1,
+    kind: "report",
+    title: `Let ${bot.name} work in ${where} for you`,
+    body: `${bot.name} can then work in ${listWords(labels)} as you, with the AI mark, for ${CONSENT_DAYS} days, and you can switch it off any time.`,
+    blocks: [linkBlock("Switch me on", switchOnUrl(bot.id, apps))],
+  };
+}
+
+function buildRenewCard({ bot, endsAt }) {
+  return {
+    v: 1,
+    kind: "report",
+    title: `Keep ${bot.name} working for you`,
+    body: `${bot.name}'s permission to act for you ends on ${dateWords(endsAt)}; renew it for another ${CONSENT_DAYS} days.`,
+    blocks: [linkBlock("Renew", renewUrl(bot.id))],
+  };
+}
+
+// The text an old app (or a failed card) shows: the words plus the link.
+function withLink(text, card) {
+  const url = card?.blocks?.find((b) => b.type === "link")?.url;
+  return url ? `${text}\n${url}` : text;
+}
+
+function switchOnText(apps) {
+  const words = listWords(apps.map(appPass.appLabel));
+  return `${botProfile.ownerFirstName()}, to let me work in ${words} for you: open ${botProfile.MY_ASSISTANTS}, tap Let it act for me and tick ${words}.`;
+}
+
+// A refused pass: the switch-on card for that app, or (another reason, like
+// the owner's own account lacking access) just the text.
+function forRefusal(err, text) {
+  const message = text || err?.ownerMessage || "";
+  if (!err || !SWITCH_ON_REASONS.has(err.reason) || !botProfile.isPersonal()) return { text: message };
+  const card = buildSwitchOnCard({ bot: botForCard(), apps: [err.applicationName] });
+  return { card, text: withLink(message, card), key: `switch-on:${err.applicationName}` };
+}
+
+function forRenew() {
+  const card = buildRenewCard({ bot: botForCard(), endsAt: botProfile.consent()?.endsAt });
+  return { card, text: withLink(botProfile.renewMessage(), card), key: "renew" };
+}
+
+// What `open-claudia owner-setup` sends. `apps` names Central apps (or the
+// labels the owner uses: "Tickets"); none means the pass-ready apps the live
+// consent doesn't tick yet. Answers { card, text } or { nothing: "<line>" }.
+function plan({ apps = [], renew = false } = {}) {
+  if (!botProfile.isPersonal()) {
+    return { refused: "Only a personal bot is switched on by its owner; this bot works with its own key." };
+  }
+  const consent = botProfile.consent();
+  if (renew && consent?.endsAt) return forRenew();
+  const wanted = apps.map(appName).filter(Boolean);
+  const on = botProfile.consentApplications();
+  const missing = wanted.length ? wanted : botProfile.passApplications().filter((a) => !on.includes(a));
+  if (missing.length) {
+    const card = buildSwitchOnCard({ bot: botForCard(), apps: missing });
+    return { card, text: withLink(switchOnText(missing), card), key: `switch-on:${missing.join(",")}` };
+  }
+  if (botProfile.renewDue()) return forRenew();
+  const until = consent?.endsAt ? `, until ${dateWords(consent.endsAt)}` : "";
+  return { nothing: `Already switched on for every app I can work in for ${botProfile.ownerFirstName()} (${listWords(on.map(appPass.appLabel))})${until}. Nothing sent.` };
+}
+
+// "Tickets" -> "Ticket_Central"; a Central name stays as it is.
+function appName(raw) {
+  const s = String(raw || "").trim();
+  if (!s) return "";
+  const known = [...new Set([...botProfile.passApplications(), ...botProfile.consentApplications()])];
+  return known.find((n) => n === s)
+    || known.find((n) => appPass.appLabel(n).toLowerCase() === s.toLowerCase())
+    || s;
+}
+
+function kazeeAdapter() {
+  try { return require("./adapter-registry").getAdapters().find((a) => a.type === "kazee") || null; }
+  catch (_) { return null; }
+}
+
+// Send { card, text } to the owner's direct Kazee chat: the card, else the
+// text. Resolves "card", "text" or null (no Kazee, no owner, nothing sent).
+async function tellOwner({ card, text }, { adapter = kazeeAdapter() } = {}) {
+  const ownerId = botProfile.ownerUserId();
+  if (!ownerId || !adapter || typeof adapter.directChatFor !== "function") return null;
+  const chatId = await adapter.directChatFor(ownerId);
+  if (!chatId) return null;
+  if (card && typeof adapter.sendCard === "function") {
+    try {
+      if (await adapter.sendCard(chatId, card, { content: text })) return "card";
+      console.error("owner-setup: Kazee Chat returned no message id for the card; sending the text");
+    } catch (e) {
+      console.error("owner-setup: card not sent, sending the text:", e.message);
+    }
+  }
+  if (!text) return null;
+  await adapter.send(chatId, text);
+  return "text";
+}
+
+// A run that is not the owner's asks at most once a day per card, so nobody
+// else can fill her chat with cards.
+async function tellOwnerAsked(sending, { owner = false, now = Date.now(), adapter } = {}) {
+  const key = sending.key || sending.text;
+  if (!owner && now - (sentAt.get(key) || 0) < SEND_EVERY_MS) return "already-sent";
+  sentAt.set(key, now);
+  return tellOwner(sending, adapter ? { adapter } : undefined);
+}
+
+// The renew card, once a day while Central says renewDue.
+async function maybeSendRenew({ now = new Date(), adapter } = {}) {
+  const today = now.toISOString().slice(0, 10);
+  if (!botProfile.renewDue() || lastRenewDay === today) return null;
+  lastRenewDay = today;
+  try { return await tellOwner(forRenew(), adapter ? { adapter } : undefined); }
+  catch (e) { console.error("renew notice failed:", e.message); return null; }
+}
+
+// Tests only.
+function reset() {
+  sentAt.clear();
+  lastRenewDay = "";
+}
+
+module.exports = {
+  buildSwitchOnCard,
+  buildRenewCard,
+  switchOnUrl,
+  renewUrl,
+  forRefusal,
+  forRenew,
+  plan,
+  tellOwner,
+  tellOwnerAsked,
+  maybeSendRenew,
+  botForCard,
+  reset,
+  SWITCH_ON_REASONS,
+  LINK_LABEL_MAX,
+  CENTRAL_WEB,
+};

package/core/pack-review.js

@@ -682,6 +682,49 @@ function listDeferredDecisions() {
   } catch (_) { return []; }
 }
 
+// In-process FIFO in front of the review model: a busy bot runs reviews one at a
+// time instead of stacking model processes (OC_REVIEW_CONCURRENCY, default 1).
+// Utility calls over their cap are rejected, not queued, so lowering the cap
+// would lose reviews. acquire() hands back a release function, at once when a
+// slot is free and otherwise as a promise; a waiter pushed out by the bound
+// (OC_REVIEW_QUEUE_MAX, default 20, oldest first) gets "dropped", and one still
+// waiting at shutdown gets "closed".
+function reviewSetting(key, fallback) {
+  const value = Number(require("./config").settingValue(key));
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function createReviewGate({ limit, maxWaiting }) {
+  let active = 0;
+  let closed = false;
+  const waiting = [];
+  function grant() {
+    active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      active -= 1;
+      if (waiting.length) waiting.shift()(grant());
+    };
+  }
+  return {
+    acquire() {
+      if (closed) return "closed";
+      if (active < limit) return grant();
+      if (waiting.length >= maxWaiting) {
+        waiting.shift()("dropped");
+        console.warn(`[pack-review] review queue full (${maxWaiting} waiting): dropped the oldest waiting review`);
+      }
+      return new Promise((resolve) => waiting.push(resolve));
+    },
+    close() {
+      closed = true;
+      for (const resolve of waiting.splice(0)) resolve("closed");
+    },
+  };
+}
+
 function createPackReviewer(dependencies = {}) {
   const runUtility = dependencies.spawnUtilityAgent || spawnUtilityAgent;
   const queue = dependencies.mutationQueue || memoryMutationQueue;
@@ -689,6 +732,10 @@ function createPackReviewer(dependencies = {}) {
   const lockRetryDelayMs = dependencies.lockRetryDelayMs ?? LOCK_RETRY_DELAY_MS;
   const adjudicator = dependencies.dedupAdjudicator
     || dedupAdjudicator.createDedupAdjudicator({ spawnUtilityAgent: dependencies.spawnUtilityAgent });
+  const gate = createReviewGate({
+    limit: reviewSetting("OC_REVIEW_CONCURRENCY", 1),
+    maxWaiting: reviewSetting("OC_REVIEW_QUEUE_MAX", 20),
+  });
   const handles = new Map();
   let accepting = true;
 
@@ -712,19 +759,34 @@ function createPackReviewer(dependencies = {}) {
     }
 
     const capturedProvider = provider || null;
-    const versions = snapshotMemoryVersions();
-    // Denies are the OWNER's refusals — mine them only when reviewing an
-    // owner turn, so deny content never surfaces via external speakers' turns.
-    const denies = (!source || source.isOwner) ? collectDeniedApprovals() : { block: "", ids: [] };
-    const prompt = buildReviewPrompt(
-      redactSensitive(String(userText || "")),
-      redactSensitive(String(assistantText || "")),
-      activePacks,
-      denies.block,
-    );
     const work = (async () => {
       let utilityResult = null;
+      let releaseSlot = () => {};
       try {
+        // The review's own timeout starts at the model call, after this wait.
+        let slot = gate.acquire();
+        if (slot instanceof Promise) slot = await slot;
+        if (slot === "dropped") {
+          reviewerMetric({ provider: capturedProvider || "", status: "dropped", code: "REVIEW_QUEUE_FULL" });
+          return { status: "dropped", reason: "review queue full" };
+        }
+        if (slot === "closed") {
+          queue.record({ id: null, label: "review", status: "pending_intent_rejected", provider: capturedProvider, runId: runId || null });
+          return { status: "not_admitted", reason: "review shutdown in progress" };
+        }
+        releaseSlot = slot;
+        // Read memory after the wait: a snapshot from before it would make this
+        // review's rewrites stale whenever the review ahead touched the same pack.
+        const versions = snapshotMemoryVersions();
+        // Denies are the OWNER's refusals — mine them only when reviewing an
+        // owner turn, so deny content never surfaces via external speakers' turns.
+        const denies = (!source || source.isOwner) ? collectDeniedApprovals() : { block: "", ids: [] };
+        const prompt = buildReviewPrompt(
+          redactSensitive(String(userText || "")),
+          redactSensitive(String(assistantText || "")),
+          activePacks,
+          denies.block,
+        );
         utilityResult = await runUtility(prompt, {
           purpose: "review",
           activeProvider: capturedProvider,
@@ -754,6 +816,8 @@ function createPackReviewer(dependencies = {}) {
         try {
           dedup = await adjudicator.adjudicateDecision(decision, { provider: capturedProvider, cwd: process.cwd() });
         } catch (_) {}
+        // Model runs are done; the wait for the write lock does not hold the slot.
+        releaseSlot();
         const finalDecision = dedup ? dedup.decision : decision;
         const enqueueApply = () => queue.enqueue("review", () => applyDecisionBatch({
           decision: finalDecision,
@@ -822,6 +886,8 @@ function createPackReviewer(dependencies = {}) {
           announcementFailed,
           error: { code: error.code || "REVIEW_FAILED", message: redactSensitive(error.message) },
         };
+      } finally {
+        releaseSlot();
       }
     })();
     return track(work, { provider: capturedProvider, channelId: channelId || null, runId: runId || null });
@@ -829,6 +895,7 @@ function createPackReviewer(dependencies = {}) {
 
   function stopAdmission(reason = "shutdown") {
     accepting = false;
+    gate.close();
     queue.record({ id: null, label: "review", status: "review_admission_stopped", reason: String(reason).slice(0, 160) });
   }
 

package/core/recall/index.js

@@ -4,7 +4,7 @@
 // Each engine implements: async run(ctx) -> { packBlock, entityBlock,
 // packMatches, entityMatches }. The active engine is chosen per channel via
 // the `recallEngine` setting (set by the /engine slash command), falling back
-// to the RECALL_ENGINE env var, then to DEFAULT_ENGINE. Unknown names fall
+// to RECALL_ENGINE (process env or the bot's .env), then to DEFAULT_ENGINE. Unknown names fall
 // back to the default so a bad value can never break recall. The discoverer is
 // the default: it's fail-open (falls back to the classic keyword baseline on
 // any error), so it never recalls worse than classic, only better. `ask`
@@ -37,7 +37,8 @@ function listEngines() {
 
 function activeEngineName(settings) {
   const fromSettings = settings && settings.recallEngine;
-  const fromEnv = process.env.RECALL_ENGINE;
+  let fromEnv;
+  try { fromEnv = require("../config").settingValue("RECALL_ENGINE"); } catch (e) { fromEnv = process.env.RECALL_ENGINE; }
   const name = String(fromSettings || fromEnv || DEFAULT_ENGINE).toLowerCase();
   return ENGINES[name] ? name : DEFAULT_ENGINE;
 }