herdr-plugin-amq 0.1.7 → 0.1.9

package/src/server.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { findAmqRoot, getAgentHandles } from "./config.mjs";
+import { markMaildirMessageRead } from "./protocol.mjs";
 import {
   loadAllMessages,
   loadThreads,
@@ -75,6 +76,7 @@ export function startWebServer({
   // Map<handle, { herdrStatus, herdrPaneId, herdrWorkspaceId, ... }>
   let herdrStatusCache = new Map();
   let herdrSubscription = null;
+  let herdrRefreshDebounce = null;
 
   function broadcastSSE(payload) {
     const msg = `data: ${JSON.stringify(payload)}\n\n`;
@@ -89,6 +91,15 @@ export function startWebServer({
     } catch {}
   }
 
+  function scheduleHerdrRefresh(reason = "event") {
+    if (isClosing) return;
+    clearTimeout(herdrRefreshDebounce);
+    herdrRefreshDebounce = setTimeout(async () => {
+      await refreshHerdrCache();
+      broadcastSSE({ type: "herdr_agents_refresh", reason, at: new Date().toISOString() });
+    }, 80);
+  }
+
   let isClosing = false;
   let herdrReconnectTimeout = null;
 
@@ -99,42 +110,22 @@ export function startWebServer({
     }
     herdrSubscription = subscribeHerdrEvents({
       onConnect: () => {
-        // Refresh snapshot on connect so our cache is up to date
-        refreshHerdrCache();
+        scheduleHerdrRefresh("connected");
       },
       onEvent: (event) => {
-        const t = event.type;
-        // Agent state changed — update cache and notify SSE clients
-        if (t === "agent.state_changed" || t === "agent.updated") {
-          const handle = event.name;
-          if (handle) {
-            const existing = herdrStatusCache.get(handle) || {};
-            herdrStatusCache.set(handle, {
-              ...existing,
-              herdrStatus: event.agent_status || existing.herdrStatus,
-              herdrPaneId: event.pane_id || existing.herdrPaneId,
-              herdrWorkspaceId: event.workspace_id || existing.herdrWorkspaceId,
-              herdrTabId: event.tab_id || existing.herdrTabId,
-              herdrTitle: event.terminal_title_stripped || event.terminal_title || existing.herdrTitle,
-              interactiveReady: event.interactive_ready ?? existing.interactiveReady,
-            });
-            broadcastSSE({
-              type: "herdr_agent_update",
-              handle,
-              herdrStatus: event.agent_status,
-              paneId: event.pane_id,
-              at: new Date().toISOString(),
-            });
-          }
-        }
-        // Workspace/pane lifecycle — do a full agent refresh
-        if (t === "workspace.created" || t === "workspace.closed" ||
-            t === "pane.created" || t === "pane.closed") {
-          refreshHerdrCache();
+        const type = String(event?.type || "");
+        if (
+          type.startsWith("pane.") ||
+          type.startsWith("agent.") ||
+          type === "workspace.created" ||
+          type === "workspace.closed"
+        ) {
+          scheduleHerdrRefresh(type);
         }
       },
       onDisconnect: () => {
-        // Reconnect after 5s if Herdr socket drops
+        herdrStatusCache = new Map();
+        broadcastSSE({ type: "herdr_agents_refresh", reason: "disconnected", at: new Date().toISOString() });
         if (!isClosing) {
           herdrReconnectTimeout = setTimeout(startHerdrSubscription, 5000);
         }
@@ -285,9 +276,25 @@ export function startWebServer({
           herdrWorkspaceId: h.herdrWorkspaceId,
           herdrTabId: h.herdrTabId,
           herdrTitle: h.herdrTitle,
-          interactiveReady: h.interactiveReady,
-          agentType: h.agentType,
-          // Promote herdrStatus as the primary status when available
+          herdrObservedAt: h.herdrObservedAt,
+           interactiveReady: h.interactiveReady,
+           agentType: h.agentType,
+           runtimeModel: h.herdrModel || null,
+           modelSource: h.herdrModelSource || null,
+           herdrActivity: {
+            status: h.herdrStatus,
+            title: h.herdrMetadataTitle || h.herdrTitle,
+            terminalTitle: h.herdrTerminalTitle,
+            metadataTitle: h.herdrMetadataTitle,
+            stateLabels: h.herdrStateLabels || {},
+            tokens: h.herdrTokens || [],
+            stateChangeSeq: h.herdrStateChangeSeq,
+            observedAt: h.herdrObservedAt,
+             focused: h.herdrFocused,
+             launchPending: h.herdrLaunchPending,
+             model: h.herdrModel || null,
+             modelSource: h.herdrModelSource || null,
+           },
           status: h.herdrStatus !== "unknown" ? h.herdrStatus : (a.status || "offline"),
         };
       });
@@ -306,6 +313,11 @@ export function startWebServer({
 
     if (pathname === "/api/agents" && req.method === "POST") {
       const body = await parseJsonBody(req);
+      if (body.__error) {
+        res.writeHead(413, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: body.__error }));
+        return;
+      }
       const repoRoot = path.resolve(path.dirname(amqRoot));
       // Workspaces are the default under the hood: automatically isolate agent in .worktrees/<handle>
       const worktreeResult = ensureAgentWorktree(repoRoot, body.handle, body.branch);
@@ -314,7 +326,7 @@ export function startWebServer({
         worktree: worktreeResult?.ok ? worktreeResult.path : body.worktree,
       });
       // Refresh Herdr cache after registration
-      refreshHerdrCache().catch(() => {});
+      scheduleHerdrRefresh("agent_registered");
       res.writeHead(result.ok ? 200 : 400, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ ...result, worktreeResult }));
       return;
@@ -459,6 +471,24 @@ export function startWebServer({
     }
 
 
+    if (pathname.startsWith("/api/messages/") && pathname.endsWith("/read") && req.method === "POST") {
+      const messageId = decodeURIComponent(pathname.slice("/api/messages/".length, -"/read".length));
+      const account = url.searchParams.get("account") || "user";
+      if (account === "all" || !/^[A-Za-z0-9_-]{1,128}$/.test(account)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: "A concrete mailbox account is required" }));
+        return;
+      }
+      const result = markMaildirMessageRead(amqRoot, account, messageId);
+      if (result.ok) {
+        invalidateMessageCache();
+        broadcastSSE({ type: "mail_update", reason: "message_read", account, messageId, at: new Date().toISOString() });
+      }
+      res.writeHead(result.ok ? 200 : 404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result));
+      return;
+    }
+
     if (pathname === "/api/messages" && req.method === "GET") {
       const account = url.searchParams.get("account") || "all";
       const folder = url.searchParams.get("folder") || "inbox";
@@ -718,8 +748,11 @@ export function startWebServer({
           ? "text/css; charset=utf-8"
           : "application/javascript; charset=utf-8";
 
-      res.writeHead(200, { "Content-Type": mime });
-      fs.createReadStream(filePath).pipe(res);
+    res.writeHead(200, {
+      "Content-Type": mime,
+      "Cache-Control": "no-store, max-age=0",
+    });
+    fs.createReadStream(filePath).pipe(res);
     } else {
       res.writeHead(404, { "Content-Type": "text/plain" });
       res.end("File not found");
@@ -779,6 +812,7 @@ export function startWebServer({
       server6 = null;
     }
     if (herdrReconnectTimeout) clearTimeout(herdrReconnectTimeout);
+    if (herdrRefreshDebounce) clearTimeout(herdrRefreshDebounce);
     if (watchDebounce) clearTimeout(watchDebounce);
     if (herdrSubscription) {
       try { herdrSubscription.close(); } catch {}
@@ -801,10 +835,20 @@ export function startWebServer({
 function parseJsonBody(req) {
   return new Promise((resolve) => {
     let acc = "";
+    let tooLarge = false;
     req.on("data", (chunk) => {
+      if (tooLarge) return;
       acc += chunk;
+      if (Buffer.byteLength(acc) > 1024 * 1024) {
+        acc = "";
+        tooLarge = true;
+      }
     });
     req.on("end", () => {
+      if (tooLarge) {
+        resolve({ __error: "request body too large" });
+        return;
+      }
       try {
         resolve(JSON.parse(acc));
       } catch {

package/src/store.mjs

@@ -5,7 +5,8 @@ import crypto from "node:crypto";
 import { execCmd, getHerdrBin, getAgentHandles, getRepoRootFromAmq } from "./config.mjs";
 import { scanAgentBriefs, getAgentBrief, saveAgentBrief } from "./briefs.mjs";
 import { ingestAttachment } from "./blobs.mjs";
-import { sendMaildirMessage, replyMaildirMessage, drainMaildir } from "./protocol.mjs";
+import { sendMaildirMessage, replyMaildirMessage, drainMaildir, ensureAgentMailbox, findMessageForRecipient, isSafeMailIdentifier, readMaildirMessageFile, writeBoundedFileAtomic } from "./protocol.mjs";
+import { renderLocalTemplate } from "./templates.mjs";
 
 const PALETTE = [
   "#1a73e8", "#ea4335", "#fbbc05", "#34a853", "#ff6d00",
@@ -856,58 +857,242 @@ export function loadAgentDirectory(amqRoot) {
   return list;
 }
 
+function readAgentProfile(profilePath) {
+  try {
+    const content = readMaildirMessageFile(profilePath, 1024 * 1024);
+    if (content === null) return null;
+    const parsed = JSON.parse(content);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeAgentProfile(agentDir, profileData) {
+  const profilePath = path.join(agentDir, "profile.json");
+  writeBoundedFileAtomic(profilePath, JSON.stringify(profileData, null, 2), 1024 * 1024);
+}
+
+function normalizeText(value, fallback, maxLength) {
+  if (typeof value !== "string") return fallback;
+  const normalized = value
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/`/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+  return normalized ? normalized.slice(0, maxLength) : fallback;
+}
+
+function normalizeMultiline(value, fallback, maxLength) {
+  if (typeof value !== "string") return fallback;
+  const normalized = value
+    .replace(/\0/g, "")
+    .replace(/\r\n/g, "\n")
+    .replace(/[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "")
+    .trim();
+  return normalized ? normalized.slice(0, maxLength) : fallback;
+}
+
+function withAgentRegistrationLock(agentDir, operation) {
+  const lockDir = path.join(agentDir, ".registration.lock");
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  const deadline = Date.now() + 5000;
+
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > 30000) fs.rmSync(lockDir, { recursive: true, force: true });
+      } catch {}
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for agent registration lock");
+      Atomics.wait(sleeper, 0, 0, 25);
+    }
+  }
+
+  try {
+    return operation();
+  } finally {
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function defaultWelcomeBody(handle, name) {
+  return `Welcome to AMQ.\nAgent data: name=${JSON.stringify(name)}; handle=${JSON.stringify(handle)}.\nRun herdr-amq mail drain --me ${handle} --include-body to read messages. No reply is required.`.slice(0, 2048);
+}
+
+function selectProfileFields(profile) {
+  if (!profile || typeof profile !== "object") return {};
+  const selected = {};
+  for (const key of ["name", "role", "model", "emoji", "color", "worktree", "prompt", "createdAt", "registrationId"]) {
+    if (Object.prototype.hasOwnProperty.call(profile, key)) selected[key] = profile[key];
+  }
+  if (profile.welcome && typeof profile.welcome === "object" && !Array.isArray(profile.welcome)) {
+    selected.welcome = {};
+    for (const key of ["status", "messageId", "sentAt", "templatePath", "templateSha256", "source", "lastError"]) {
+      if (Object.prototype.hasOwnProperty.call(profile.welcome, key)) selected.welcome[key] = profile.welcome[key];
+    }
+  }
+  return selected;
+}
+
 /**
  * Register a new agent or update an existing agent profile with model configuration and prompt
  */
-export function registerAgent(amqRoot, { handle, name, role, model = "claude-3-7-sonnet", emoji, color, worktree, prompt, brief, syncDisk = true }) {
-  if (!amqRoot || !fs.existsSync(amqRoot)) {
-    return { ok: false, error: "Invalid AMQ root" };
-  }
+export function registerAgent(amqRoot, options = {}) {
+  if (!amqRoot || !fs.existsSync(amqRoot)) return { ok: false, error: "Invalid AMQ root" };
 
-  const safeHandle = (handle || "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-");
-  if (!safeHandle) {
-    return { ok: false, error: "Invalid agent handle" };
-  }
+  const safeHandle = (options.handle || "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+  if (!isSafeMailIdentifier(safeHandle, 128)) return { ok: false, error: "Invalid agent handle" };
 
-  const agentDir = path.join(amqRoot, "agents", safeHandle);
-  if (!fs.existsSync(agentDir)) {
-    // Create standard AMQ maildir structure
-    fs.mkdirSync(path.join(agentDir, "inbox", "new"), { recursive: true });
-    fs.mkdirSync(path.join(agentDir, "inbox", "cur"), { recursive: true });
-    fs.mkdirSync(path.join(agentDir, "inbox", "tmp"), { recursive: true });
-    fs.mkdirSync(path.join(agentDir, "outbox", "sent"), { recursive: true });
-    fs.mkdirSync(path.join(agentDir, "outbox", "tmp"), { recursive: true });
-    fs.mkdirSync(path.join(agentDir, "receipts"), { recursive: true });
+  try {
+    const agentDir = ensureAgentMailbox(amqRoot, safeHandle);
+    return withAgentRegistrationLock(agentDir, () => registerAgentLocked(amqRoot, agentDir, safeHandle, options));
+  } catch (error) {
+    return { ok: false, error: error.message };
   }
+}
 
-  const promptContent = prompt || brief || undefined;
+function registerAgentLocked(amqRoot, agentDir, safeHandle, options) {
+  const { name, role, model, emoji, color, worktree, prompt, brief, syncDisk = true } = options;
+  const profilePath = path.join(agentDir, "profile.json");
+  const existingProfile = readAgentProfile(profilePath);
+  const now = new Date().toISOString();
+  const registrationId = isSafeMailIdentifier(existingProfile?.registrationId, 128)
+    ? existingProfile.registrationId
+    : crypto.randomUUID();
+  const shouldDeliverWelcome = !existingProfile || existingProfile?.welcome?.status === "pending";
+  const welcomeMessageId = isSafeMailIdentifier(existingProfile?.welcome?.messageId)
+    ? existingProfile.welcome.messageId
+    : `welcome-${registrationId}`;
+  const defaultName = formatAgentTitle(safeHandle);
+  const defaultEmoji = safeHandle === "user" ? "👤" : safeHandle.slice(0, 1).toUpperCase();
+  const promptContent = normalizeMultiline(
+    prompt ?? brief,
+    normalizeMultiline(existingProfile?.prompt, "", 256 * 1024),
+    256 * 1024
+  );
   const profileData = {
+    ...selectProfileFields(existingProfile),
     handle: safeHandle,
-    name: name || formatAgentTitle(safeHandle),
-    role: role || "Autonomous Specialist",
-    model: model || "claude-3-7-sonnet",
-    emoji: emoji || (safeHandle === "user" ? "👤" : safeHandle.slice(0, 1).toUpperCase()),
-    color: color || getAgentColor(safeHandle),
-    worktree: worktree || null,
+    name: normalizeText(name, normalizeText(existingProfile?.name, defaultName, 120), 120),
+    role: normalizeText(role, normalizeText(existingProfile?.role, "Autonomous Specialist", 240), 240),
+    model: normalizeText(model, normalizeText(existingProfile?.model, "claude-3-7-sonnet", 200), 200),
+    emoji: normalizeText(emoji, normalizeText(existingProfile?.emoji, defaultEmoji, 16), 16),
+    color: normalizeText(color, normalizeText(existingProfile?.color, getAgentColor(safeHandle), 64), 64),
+    worktree: normalizeText(worktree, normalizeText(existingProfile?.worktree, "", 1024), 1024) || null,
     prompt: promptContent,
-    updatedAt: new Date().toISOString(),
+    createdAt: existingProfile?.createdAt || now,
+    registrationId,
+    updatedAt: now,
   };
 
-  fs.writeFileSync(
-    path.join(agentDir, "profile.json"),
-    JSON.stringify(profileData, null, 2),
-    "utf8"
-  );
+  if (shouldDeliverWelcome) {
+    profileData.welcome = {
+      status: "pending",
+      messageId: welcomeMessageId,
+      ...(typeof existingProfile?.welcome?.lastError === "string"
+        ? { lastError: normalizeText(existingProfile.welcome.lastError, "delivery pending", 512) }
+        : {}),
+    };
+  }
+  writeAgentProfile(agentDir, profileData);
 
-  // Sync to disk brief file if prompt is provided
   if (syncDisk && promptContent) {
     try {
       const repoRoot = getRepoRootFromAmq(amqRoot);
-      saveAgentBrief(repoRoot, safeHandle, { description: role, prompt: promptContent, model, role });
+      saveAgentBrief(repoRoot, safeHandle, {
+        description: profileData.role,
+        prompt: promptContent,
+        model: profileData.model,
+        role: profileData.role,
+      });
     } catch {}
   }
 
-  return { ok: true, agent: profileData };
+  if (!shouldDeliverWelcome) return { ok: true, agent: profileData, welcome: { ok: true, skipped: true } };
+
+  const rendered = renderLocalTemplate(
+    amqRoot,
+    "welcome",
+    {
+      agent: {
+        handle: safeHandle,
+        name: profileData.name,
+        role: profileData.role,
+        model: profileData.model,
+        emoji: profileData.emoji,
+        color: profileData.color,
+        worktree: profileData.worktree || "",
+      },
+    },
+    defaultWelcomeBody(safeHandle, profileData.name)
+  );
+
+  let deliveredMessage = findMessageForRecipient(amqRoot, safeHandle, welcomeMessageId);
+  let deliveryError = null;
+  if (!deliveredMessage) {
+    try {
+      sendMaildirMessage(amqRoot, {
+        id: welcomeMessageId,
+        from: "coordinator",
+        to: [safeHandle],
+        subject: `Welcome to AMQ, ${safeHandle}`,
+        thread: `welcome/${safeHandle}`,
+        body: rendered.text,
+        priority: "normal",
+        kind: "status",
+        labels: ["welcome", "registration"],
+        context: {
+          template: "welcome",
+          templateSource: rendered.source,
+          templateSha256: rendered.sha256,
+          registrationId,
+        },
+        created: now,
+      });
+      deliveredMessage = findMessageForRecipient(amqRoot, safeHandle, welcomeMessageId);
+    } catch (error) {
+      deliveryError = error;
+      deliveredMessage = findMessageForRecipient(amqRoot, safeHandle, welcomeMessageId);
+    }
+  }
+
+  if (!deliveredMessage) {
+    profileData.welcome = {
+      status: "pending",
+      messageId: welcomeMessageId,
+      lastError: normalizeText(
+        deliveryError?.message,
+        "Welcome delivery was not observed",
+        512
+      ),
+    };
+    writeAgentProfile(agentDir, profileData);
+    return {
+      ok: true,
+      agent: profileData,
+      welcome: { ok: false, pending: true, error: profileData.welcome.lastError },
+    };
+  }
+
+  profileData.welcome = {
+    status: "sent",
+    messageId: welcomeMessageId,
+    sentAt: deliveredMessage.header?.created || now,
+    templatePath: rendered.source === "template" && rendered.path ? path.relative(amqRoot, rendered.path) : null,
+    templateSha256: rendered.source === "template" ? rendered.sha256 : null,
+    source: rendered.source,
+  };
+  writeAgentProfile(agentDir, profileData);
+  return {
+    ok: true,
+    agent: profileData,
+    welcome: { ok: true, id: welcomeMessageId, sentAt: profileData.welcome.sentAt },
+  };
 }
 
 /**

package/src/templates.mjs

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const ALLOWED_TEMPLATES = new Set(["welcome", "doorbell"]);
+const MAX_TEMPLATE_BYTES = 64 * 1024;
+const VARIABLE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function normalizeScalar(value) {
+  if (typeof value === "string") {
+    return value
+      .replace(/[\u0000-\u001f\u007f]+/g, " ")
+      .replace(/`/g, "'")
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "boolean") return value;
+  throw new Error("Template values must be finite scalars");
+}
+
+function boundedFallback(fallback) {
+  const text = typeof fallback === "string" ? fallback : String(fallback ?? "");
+  const bytes = Buffer.from(text, "utf8");
+  return bytes.length <= MAX_TEMPLATE_BYTES ? text : bytes.subarray(0, MAX_TEMPLATE_BYTES).toString("utf8");
+}
+
+function resolveVariable(context, expression) {
+  const key = expression.trim();
+  if (!VARIABLE_PATTERN.test(key)) throw new Error(`Unsupported template variable: ${key}`);
+  const segments = key.split(".");
+  if (segments.some((segment) => FORBIDDEN_SEGMENTS.has(segment))) {
+    throw new Error(`Unsupported template variable: ${key}`);
+  }
+
+  let value = context;
+  for (const segment of segments) {
+    if (!value || typeof value !== "object" || !Object.prototype.hasOwnProperty.call(value, segment)) {
+      throw new Error(`Missing template variable: ${key}`);
+    }
+    value = value[segment];
+  }
+  return normalizeScalar(value);
+}
+
+export function renderTemplate(source, context) {
+  if (typeof source !== "string" || !source.trim()) throw new Error("Template is empty");
+  if (Buffer.byteLength(source, "utf8") > MAX_TEMPLATE_BYTES) throw new Error("Template is too large");
+
+  if (source.includes("{%") || source.includes("{#")) throw new Error("Unsupported template syntax");
+  const withoutExpressions = source.replace(/{{([\s\S]*?)}}/g, "");
+  if (withoutExpressions.includes("{") || withoutExpressions.includes("}")) {
+    throw new Error("Malformed template expression");
+  }
+
+  const rendered = source.replace(/{{([\s\S]*?)}}/g, (_, expression) => String(resolveVariable(context, expression)));
+  if (Buffer.byteLength(rendered, "utf8") > MAX_TEMPLATE_BYTES) throw new Error("Rendered template is too large");
+  return rendered;
+}
+
+export function loadLocalTemplate(amqRoot, name) {
+  if (!amqRoot || !ALLOWED_TEMPLATES.has(name)) return null;
+
+  try {
+    const root = fs.realpathSync(path.resolve(amqRoot));
+    const templateDir = path.join(root, "templates");
+    const dirStat = fs.lstatSync(templateDir);
+    if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) return null;
+
+    const realTemplateDir = fs.realpathSync(templateDir);
+    if (realTemplateDir !== templateDir) return null;
+
+    const templatePath = path.join(templateDir, `${name}.md`);
+    const realTemplatePath = fs.realpathSync(templatePath);
+    if (path.dirname(realTemplatePath) !== realTemplateDir) return null;
+
+    const noFollow = fs.constants.O_NOFOLLOW || 0;
+    const fd = fs.openSync(templatePath, fs.constants.O_RDONLY | noFollow);
+    try {
+      const stat = fs.fstatSync(fd);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_TEMPLATE_BYTES) return null;
+      const source = fs
+        .readFileSync(fd, "utf8")
+        .replace(/^\uFEFF/, "")
+        .replace(/\r\n/g, "\n");
+      if (!source.trim() || source.includes("\0") || Buffer.byteLength(source, "utf8") > MAX_TEMPLATE_BYTES) return null;
+
+      return {
+        name,
+        path: realTemplatePath,
+        source,
+        sha256: crypto.createHash("sha256").update(source).digest("hex"),
+      };
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+
+export function renderLocalTemplate(amqRoot, name, context, fallback) {
+  const safeFallback = boundedFallback(fallback);
+  const template = loadLocalTemplate(amqRoot, name);
+  if (!template) return { text: safeFallback, source: "fallback", path: null, sha256: null };
+
+  try {
+    return {
+      text: renderTemplate(template.source, context),
+      source: "template",
+      path: template.path,
+      sha256: template.sha256,
+    };
+  } catch {
+    return { text: safeFallback, source: "fallback", path: null, sha256: null };
+  }
+}