clay-server 2.27.0-beta.8 → 2.27.0

package/lib/project-debate.js

@@ -721,6 +721,13 @@ function attachDebate(ctx) {
     ctx.send({ type: "mention_processing", mateId: mateId, active: active });
   }
 
+  // Persist a debate message to session history and send to clients
+  function debateSendAndRecord(session, msg) {
+    session.history.push(msg);
+    ctx.sm.appendToSessionFile(session, msg);
+    ctx.sendToSession(session.localId, msg);
+  }
+
   // --- Live debate ---
 
   function startDebateLive(session) {
@@ -771,7 +778,7 @@ function attachDebate(ctx) {
 
     // Signal moderator's first turn
     debateMateProcessing(debate.moderatorId, true);
-    ctx.sendToSession(debateSession.localId, {
+    debateSendAndRecord(debateSession, {
       type: "debate_turn",
       mateId: debate.moderatorId,
       mateName: moderatorProfile.name,
@@ -798,7 +805,7 @@ function attachDebate(ctx) {
       },
       onDelta: function (delta) {
         if (debateSession._debate && debateSession._debate.phase !== "ended") {
-          ctx.sendToSession(debateSession.localId, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
+          debateSendAndRecord(debateSession, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
         }
       },
       onDone: function (fullText) {
@@ -906,7 +913,7 @@ function attachDebate(ctx) {
 
     // Notify clients of new turn
     debateMateProcessing(mateId, true);
-    ctx.sendToSession(session.localId, {
+    debateSendAndRecord(session, {
       type: "debate_turn",
       mateId: mateId,
       mateName: profile.name,
@@ -926,7 +933,7 @@ function attachDebate(ctx) {
       onDelta: function (delta) {
         if (session._debate && session._debate.phase !== "ended") {
           debate._currentTurnText += delta;
-          ctx.sendToSession(session.localId, { type: "debate_stream", mateId: mateId, mateName: profile.name, delta: delta });
+          debateSendAndRecord(session, { type: "debate_stream", mateId: mateId, mateName: profile.name, delta: delta });
         }
       },
       onDone: function (fullText) {
@@ -1071,7 +1078,7 @@ function attachDebate(ctx) {
 
     // Notify clients of moderator turn
     debateMateProcessing(debate.moderatorId, true);
-    ctx.sendToSession(session.localId, {
+    debateSendAndRecord(session, {
       type: "debate_turn",
       mateId: debate.moderatorId,
       mateName: moderatorProfile.name,
@@ -1101,7 +1108,7 @@ function attachDebate(ctx) {
       },
       onDelta: function (delta) {
         if (session._debate && session._debate.phase !== "ended") {
-          ctx.sendToSession(session.localId, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
+          debateSendAndRecord(session, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
         }
       },
       onDone: function (fullText) {
@@ -1168,7 +1175,7 @@ function attachDebate(ctx) {
     debate.turnInProgress = true;
     var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
 
-    ctx.sendToSession(session.localId, {
+    debateSendAndRecord(session, {
       type: "debate_turn",
       mateId: debate.moderatorId,
       mateName: moderatorProfile.name,
@@ -1207,7 +1214,7 @@ function attachDebate(ctx) {
     debate.turnInProgress = true;
     var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
 
-    ctx.sendToSession(session.localId, {
+    debateSendAndRecord(session, {
       type: "debate_turn",
       mateId: debate.moderatorId,
       mateName: moderatorProfile.name,
@@ -1238,7 +1245,7 @@ function attachDebate(ctx) {
       },
       onDelta: function (delta) {
         if (session._debate && session._debate.phase !== "ended") {
-          ctx.sendToSession(session.localId, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
+          debateSendAndRecord(session, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
         }
       },
       onDone: function (fullText) {
@@ -1287,7 +1294,7 @@ function attachDebate(ctx) {
     var moderatorProfile = ctx.getMateProfile(debate.mateCtx, debate.moderatorId);
 
     debateMateProcessing(debate.moderatorId, true);
-    ctx.sendToSession(session.localId, {
+    debateSendAndRecord(session, {
       type: "debate_turn",
       mateId: debate.moderatorId,
       mateName: moderatorProfile.name,
@@ -1477,7 +1484,7 @@ function attachDebate(ctx) {
 
       debate.turnInProgress = true;
       debateMateProcessing(debate.moderatorId, true);
-      ctx.sendToSession(session.localId, {
+      debateSendAndRecord(session, {
         type: "debate_turn",
         mateId: debate.moderatorId,
         mateName: moderatorProfile.name,
@@ -1525,7 +1532,7 @@ function attachDebate(ctx) {
           },
           onDelta: function (delta) {
             if (session._debate && session._debate.phase !== "ended") {
-              ctx.sendToSession(session.localId, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
+              debateSendAndRecord(session, { type: "debate_stream", mateId: debate.moderatorId, mateName: moderatorProfile.name, delta: delta });
             }
           },
           onDone: function (fullText) {

package/lib/project-http.js

@@ -629,11 +629,13 @@ function attachHTTP(ctx) {
       var execSync = require("child_process").execSync;
       try {
         var out = execSync("git status --porcelain", { cwd: cwd, encoding: "utf8", timeout: 5000 });
-        var dirty = out.trim().split("\n").some(function (line) {
+        var lines = out.trim().split("\n").filter(function (line) {
           return line.trim().length > 0 && !line.startsWith("??");
         });
+        var dirty = lines.length > 0;
+        var files = lines.map(function (line) { return line.trim(); });
         res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ dirty: dirty }));
+        res.end(JSON.stringify({ dirty: dirty, files: files }));
       } catch (e) {
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ dirty: false }));

package/lib/project-loop.js

@@ -21,6 +21,7 @@ function attachLoop(ctx) {
   var sendTo = ctx.sendTo;
   var sendToSession = ctx.sendToSession;
   var pushModule = ctx.pushModule;
+  var notificationsModule = ctx.notificationsModule;
   var getHubSchedules = ctx.getHubSchedules;
   var getLinuxUserForSession = ctx.getLinuxUserForSession;
   var onProcessingChanged = ctx.onProcessingChanged;
@@ -134,13 +135,16 @@ function attachLoop(ctx) {
           var _ld = path.join(_loopsBase, _loopDirs[_li]);
           try {
             fs.accessSync(path.join(_ld, "PROMPT.md"));
-            fs.accessSync(path.join(_ld, "JUDGE.md"));
             fs.accessSync(path.join(_ld, "LOOP.json"));
+            var _loopCfg = JSON.parse(fs.readFileSync(path.join(_ld, "LOOP.json"), "utf8"));
+            var _isSimple = _loopCfg.loopMode === "simple";
+            if (!_isSimple) fs.accessSync(path.join(_ld, "JUDGE.md"));
             // Found a completed loop — recover to approval phase
             loopState.loopId = _loopDirs[_li];
             loopState.phase = "approval";
-            var _loopCfg = JSON.parse(fs.readFileSync(path.join(_ld, "LOOP.json"), "utf8"));
             loopState.maxIterations = _loopCfg.maxIterations || 20;
+            if (!loopState.wizardData) loopState.wizardData = {};
+            loopState.wizardData.loopMode = _loopCfg.loopMode || "judge";
             saveLoopState();
             console.log("[ralph-loop] Recovered orphaned loop: " + _loopDirs[_li]);
             break;
@@ -177,7 +181,8 @@ function attachLoop(ctx) {
     var hasJudge = false;
     try { fs.accessSync(path.join(dir, "PROMPT.md")); hasPrompt = true; } catch (e) {}
     try { fs.accessSync(path.join(dir, "JUDGE.md")); hasJudge = true; } catch (e) {}
-    return hasPrompt && hasJudge;
+    var isSimple = loopState.wizardData && loopState.wizardData.loopMode === "simple";
+    return isSimple ? hasPrompt : (hasPrompt && hasJudge);
   }
 
   // .claude/ directory watcher for PROMPT.md / JUDGE.md
@@ -223,16 +228,18 @@ function attachLoop(ctx) {
       try { fs.accessSync(path.join(dir, "JUDGE.md")); hasJudge = true; } catch (e) {}
       try { fs.accessSync(path.join(dir, "LOOP.json")); hasLoopJson = true; } catch (e) {}
     }
+    var isSimple = loopState.wizardData && loopState.wizardData.loopMode === "simple";
+    var bothReady = isSimple ? hasPrompt : (hasPrompt && hasJudge);
     send({
       type: "ralph_files_status",
       promptReady: hasPrompt,
       judgeReady: hasJudge,
       loopJsonReady: hasLoopJson,
-      bothReady: hasPrompt && hasJudge,
+      bothReady: bothReady,
       taskId: loopState.loopId,
     });
-    // Auto-transition to approval phase when both files appear
-    if (hasPrompt && hasJudge && loopState.phase === "crafting") {
+    // Auto-transition to approval phase when files are ready
+    if (bothReady && loopState.phase === "crafting") {
       loopState.phase = "approval";
       saveLoopState();
 
@@ -298,7 +305,10 @@ function attachLoop(ctx) {
       // Set the loopId to the schedule's own id (not the linked task) so sidebar groups correctly
       loopState.loopId = record.id;
       loopState.loopFilesId = loopFilesId;
-      loopState.wizardData = null;
+      // Restore loopMode from LOOP.json so simple loops work correctly on trigger
+      var _triggerCfg = {};
+      try { _triggerCfg = JSON.parse(fs.readFileSync(path.join(recDir, "LOOP.json"), "utf8")); } catch (e) {}
+      loopState.wizardData = { loopMode: _triggerCfg.loopMode || "judge" };
       activeRegistryId = record.id;
       console.log("[loop-registry] Auto-starting loop: " + record.name + " (" + loopState.loopId + ")");
       send({ type: "schedule_run_started", recordId: record.id });
@@ -356,12 +366,17 @@ function attachLoop(ctx) {
       loopConfig = JSON.parse(fs.readFileSync(path.join(dir, "LOOP.json"), "utf8"));
     } catch (e) {}
 
+    var isSimple = loopState.wizardData && loopState.wizardData.loopMode === "simple";
     loopState.active = true;
     loopState.phase = "executing";
     loopState.promptText = promptText;
-    loopState.judgeText = judgeText;
+    loopState.judgeText = isSimple ? null : judgeText;
     loopState.iteration = 0;
-    loopState.maxIterations = judgeText ? ((loopOpts.maxIterations >= 1 ? loopOpts.maxIterations : null) || loopConfig.maxIterations || 20) : 1;
+    if (isSimple) {
+      loopState.maxIterations = (loopOpts.maxIterations >= 1 ? loopOpts.maxIterations : null) || loopConfig.maxIterations || 5;
+    } else {
+      loopState.maxIterations = judgeText ? ((loopOpts.maxIterations >= 1 ? loopOpts.maxIterations : null) || loopConfig.maxIterations || 20) : 1;
+    }
     loopState.baseCommit = baseCommit;
     loopState.currentSessionId = null;
     loopState.judgeSessionId = null;
@@ -440,7 +455,15 @@ function attachLoop(ctx) {
         setTimeout(function() { runNextIteration(); }, 2000);
         return;
       }
-      if (loopState.judgeText && loopState.maxIterations > 1) {
+      var _isSimple = loopState.wizardData && loopState.wizardData.loopMode === "simple";
+      if (_isSimple) {
+        // Simple mode: no judge, proceed to next iteration or finish
+        if (loopState.iteration >= loopState.maxIterations) {
+          finishLoop("complete");
+        } else {
+          setTimeout(function() { runNextIteration(); }, 1000);
+        }
+      } else if (loopState.judgeText && loopState.maxIterations > 1) {
         runJudge();
       } else {
         finishLoop("pass");
@@ -648,19 +671,23 @@ function attachLoop(ctx) {
     }
 
     if (pushModule) {
-      var body = reason === "pass"
-        ? "Task completed after " + loopState.iteration + " iteration(s)"
+      var _finishBody = reason === "pass" || reason === "complete"
+        ? "Completed after " + loopState.iteration + " iteration(s)"
         : reason === "max_iterations"
           ? "Reached max iterations (" + loopState.maxIterations + ")"
-          : reason === "stopped"
-            ? "Loop stopped by user"
-            : "Loop ended due to error";
+          : reason === "stopped" ? "Stopped by user" : "Ended due to error";
       pushModule.sendPush({
-        type: "done",
-        slug: slug,
-        title: "Ralph Loop Complete",
-        body: body,
-        tag: "ralph-loop-done",
+        type: "done", slug: slug, title: "Loop Complete", body: _finishBody, tag: "ralph-loop-done",
+      });
+    }
+
+    if (notificationsModule) {
+      notificationsModule.notify("loop_complete", {
+        reason: reason,
+        name: loopState.name,
+        iterations: loopState.iteration,
+        maxIterations: loopState.maxIterations,
+        sessionId: loopState.currentSessionId,
       });
     }
   }
@@ -683,14 +710,19 @@ function attachLoop(ctx) {
       saveLoopState();
       return;
     }
-    try {
-      loopState.judgeText = fs.readFileSync(path.join(dir, "JUDGE.md"), "utf8");
-    } catch (e) {
-      console.error("[ralph-loop] Cannot resume: missing JUDGE.md");
-      loopState.active = false;
-      loopState.phase = "idle";
-      saveLoopState();
-      return;
+    var _isSimpleResume = loopState.wizardData && loopState.wizardData.loopMode === "simple";
+    if (!_isSimpleResume) {
+      try {
+        loopState.judgeText = fs.readFileSync(path.join(dir, "JUDGE.md"), "utf8");
+      } catch (e) {
+        console.error("[ralph-loop] Cannot resume: missing JUDGE.md");
+        loopState.active = false;
+        loopState.phase = "idle";
+        saveLoopState();
+        return;
+      }
+    } else {
+      loopState.judgeText = null;
     }
     // Retry the interrupted iteration (runNextIteration will increment)
     if (loopState.iteration > 0) {
@@ -742,7 +774,7 @@ function attachLoop(ctx) {
         send({ type: "loop_scheduled", recordId: loopState.loopId, cron: loopState.wizardData.cron });
         return true;
       }
-      startLoop();
+      startLoop({ maxIterations: msg.maxIterations });
       return true;
     }
 
@@ -753,7 +785,7 @@ function attachLoop(ctx) {
 
     if (msg.type === "ralph_wizard_complete") {
       var wData = msg.data || {};
-      var maxIter = wData.maxIterations || 3;
+      var maxIter = wData.maxIterations || null;
       var wizardCron = wData.cron || null;
       var newLoopId = generateLoopId();
       loopState.loopId = newLoopId;
@@ -762,6 +794,9 @@ function attachLoop(ctx) {
         task: wData.task || "",
         maxIterations: maxIter,
         cron: wizardCron,
+        loopMode: wData.loopMode || "judge",
+        promptAuthor: wData.promptAuthor || "clay",
+        judgeAuthor: wData.judgeAuthor || null,
       };
       loopState.phase = "crafting";
       loopState.startedAt = Date.now();
@@ -784,7 +819,7 @@ function attachLoop(ctx) {
       try { fs.mkdirSync(lDir, { recursive: true }); } catch (e) {}
       var loopJsonPath = path.join(lDir, "LOOP.json");
       var tmpLoopJson = loopJsonPath + ".tmp";
-      fs.writeFileSync(tmpLoopJson, JSON.stringify({ maxIterations: maxIter }, null, 2));
+      fs.writeFileSync(tmpLoopJson, JSON.stringify({ maxIterations: maxIter, loopMode: wData.loopMode || "judge" }, null, 2));
       fs.renameSync(tmpLoopJson, loopJsonPath);
 
       var craftName = (loopState.wizardData && loopState.wizardData.name) || "";
@@ -804,19 +839,15 @@ function attachLoop(ctx) {
           var tmpJudge = judgePath + ".tmp";
           fs.writeFileSync(tmpJudge, wData.judgeText);
           fs.renameSync(tmpJudge, judgePath);
-        } else if (!recordSource) {
-          // Scheduled task with no judge: force single iteration and go to approval
-          var singleJson = loopJsonPath + ".tmp2";
-          fs.writeFileSync(singleJson, JSON.stringify({ maxIterations: 1 }, null, 2));
-          fs.renameSync(singleJson, loopJsonPath);
-
+        } else if (wData.loopMode === "simple" || !recordSource) {
+          // Simple loop or scheduled task with no judge: go straight to approval
           loopState.phase = "approval";
           saveLoopState();
           send({ type: "ralph_phase", phase: "approval", source: recordSource, wizardData: loopState.wizardData });
           send({ type: "ralph_files_status", promptReady: true, judgeReady: false, bothReady: true });
           return true;
         } else {
-          // Ralph with no judge: start a crafting session to create JUDGE.md
+          // Ralph with judge mode but no judge provided: start a crafting session to create JUDGE.md
           loopState.phase = "crafting";
           saveLoopState();
 
@@ -863,13 +894,39 @@ function attachLoop(ctx) {
         return true;
       }
 
-      // Default: "draft" mode — Clay crafts both PROMPT.md and JUDGE.md
-      var craftingPrompt = "Use the /clay-ralph skill to design a Ralph Loop for the following task. " +
-        "You MUST invoke the clay-ralph skill — do NOT execute the task yourself. " +
-        "Your job is to interview me, then create PROMPT.md and JUDGE.md files " +
-        "that a future autonomous session will execute.\n\n" +
-        "## Task\n" + (wData.task || "") +
-        "\n\n## Loop Directory\n" + lDir;
+      // Default: "draft" mode — Clay crafts files via the clay-ralph skill
+      var _draftIsSimple = wData.loopMode === "simple";
+      var craftingPrompt;
+      if (_draftIsSimple) {
+        craftingPrompt = "Use the /clay-ralph skill to design a Ralph Loop for the following task. " +
+          "You MUST invoke the clay-ralph skill — do NOT execute the task yourself. " +
+          "This is a Simple Loop (no judge). Your job is to create ONLY a PROMPT.md file " +
+          "that a future autonomous session will execute. Do NOT create a JUDGE.md file.\n\n" +
+          "## Task\n" + (wData.task || "") +
+          "\n\n## Loop Directory\n" + lDir;
+      } else if (wData.judgeAuthor === "me") {
+        craftingPrompt = "Use the /clay-ralph skill to design a Ralph Loop for the following task. " +
+          "You MUST invoke the clay-ralph skill — do NOT execute the task yourself. " +
+          "The user will provide their own JUDGE.md, so create ONLY a PROMPT.md file " +
+          "that a future autonomous session will execute. Do NOT create a JUDGE.md file.\n\n" +
+          "## Task\n" + (wData.task || "") +
+          "\n\n## Loop Directory\n" + lDir;
+      } else {
+        craftingPrompt = "Use the /clay-ralph skill to design a Ralph Loop for the following task. " +
+          "You MUST invoke the clay-ralph skill — do NOT execute the task yourself. " +
+          "Your job is to interview me, then create PROMPT.md and JUDGE.md files " +
+          "that a future autonomous session will execute.\n\n" +
+          "## Task\n" + (wData.task || "") +
+          "\n\n## Loop Directory\n" + lDir;
+      }
+
+      // Pre-write user-provided files before crafting starts
+      if (wData.judgeText && wData.judgeAuthor === "me") {
+        var _judgePathDraft = path.join(lDir, "JUDGE.md");
+        var _tmpJudgeDraft = _judgePathDraft + ".tmp";
+        fs.writeFileSync(_tmpJudgeDraft, wData.judgeText);
+        fs.renameSync(_tmpJudgeDraft, _judgePathDraft);
+      }
 
       // Create a new session for crafting
       var craftingSession = sm.createSession();
@@ -1088,10 +1145,11 @@ function attachLoop(ctx) {
   // --- Connection state: send loop state to newly connected client ---
   function sendConnectionState(ws) {
     // Ralph Loop availability
+    var _connIsSimple = loopState.wizardData && loopState.wizardData.loopMode === "simple";
     var hasLoopFiles = false;
     try {
       fs.accessSync(path.join(cwd, ".claude", "PROMPT.md"));
-      fs.accessSync(path.join(cwd, ".claude", "JUDGE.md"));
+      if (!_connIsSimple) fs.accessSync(path.join(cwd, ".claude", "JUDGE.md"));
       hasLoopFiles = true;
     } catch (e) {}
     // Also check loop directory files
@@ -1100,7 +1158,7 @@ function attachLoop(ctx) {
       if (_avDir) {
         try {
           fs.accessSync(path.join(_avDir, "PROMPT.md"));
-          fs.accessSync(path.join(_avDir, "JUDGE.md"));
+          if (!_connIsSimple) fs.accessSync(path.join(_avDir, "JUDGE.md"));
           hasLoopFiles = true;
         } catch (e) {}
       }
@@ -1115,11 +1173,14 @@ function attachLoop(ctx) {
     });
 
     // Ralph phase state
+    // Derive source from wizardData for reconnect (so client can distinguish ralph vs task)
+    var _connSource = (loopState.wizardData && loopState.wizardData.source === "task") ? null : "ralph";
     sendTo(ws, {
       type: "ralph_phase",
       phase: loopState.phase,
       wizardData: loopState.wizardData,
       craftingSessionId: loopState.craftingSessionId || null,
+      source: _connSource,
     });
     if (loopState.phase === "crafting" || loopState.phase === "approval") {
       var _hasPrompt = false;
@@ -1129,11 +1190,12 @@ function attachLoop(ctx) {
         try { fs.accessSync(path.join(_lDir, "PROMPT.md")); _hasPrompt = true; } catch (e) {}
         try { fs.accessSync(path.join(_lDir, "JUDGE.md")); _hasJudge = true; } catch (e) {}
       }
+      var _connBothReady = _connIsSimple ? _hasPrompt : (_hasPrompt && _hasJudge);
       sendTo(ws, {
         type: "ralph_files_status",
         promptReady: _hasPrompt,
         judgeReady: _hasJudge,
-        bothReady: _hasPrompt && _hasJudge,
+        bothReady: _connBothReady,
         taskId: loopState.loopId,
       });
     }

package/lib/project-mate-interaction.js

@@ -569,6 +569,10 @@ function attachMateInteraction(ctx) {
         onDone: mentionCallbacks.onDone,
         onError: mentionCallbacks.onError,
         canUseTool: function (toolName, input, toolOpts) {
+          // Full-auto mode: auto-approve everything except AskUserQuestion
+          if (sm.currentPermissionMode === "bypassPermissions" && toolName !== "AskUserQuestion") {
+            return Promise.resolve({ behavior: "allow", updatedInput: input });
+          }
           // Use the shared whitelist from sdk-bridge (read-only tools + safe bash commands)
           var whitelisted = sdk.checkToolWhitelist(toolName, input);
           if (whitelisted) return Promise.resolve(whitelisted);

package/lib/project-notifications.js

@@ -0,0 +1,210 @@
+// project-notifications.js - Global notification queue, event-based creation
+// Single instance shared by all projects. All formatting logic lives here.
+// Follows attachXxx(ctx) pattern per MODULE_MAP.md
+
+var fs = require("fs");
+var path = require("path");
+var config = require("./config");
+
+var NOTIF_FILE = path.join(config.CONFIG_DIR, "notifications.json");
+var REMINDER_INTERVAL = 60 * 60 * 1000; // 1 hour
+
+function generateId() {
+  var rand = Math.random().toString(36).substring(2, 8);
+  return "n_" + Date.now() + "_" + rand;
+}
+
+// ========================================================
+// Event -> notification formatters
+// ========================================================
+
+var formatters = {
+  loop_complete: function (data) {
+    var reason = data.reason || "complete";
+    var body = (reason === "pass" || reason === "complete")
+      ? "Completed after " + (data.iterations || 0) + " iteration(s)"
+      : reason === "max_iterations"
+        ? "Reached max iterations (" + (data.maxIterations || "?") + ")"
+        : reason === "stopped"
+          ? "Stopped by user"
+          : "Ended due to error";
+    return {
+      type: reason === "error" ? "loop_error" : "loop_complete",
+      title: (data.name || "Loop") + " " + (reason === "error" ? "failed" : "complete"),
+      body: body,
+      meta: { reason: reason, iterations: data.iterations },
+    };
+  },
+
+  response_done: function (data) {
+    return {
+      type: "response_done",
+      title: data.title || "Response ready",
+      body: data.preview || "",
+    };
+  },
+
+  permission_request: function (data) {
+    return {
+      type: "permission_request",
+      title: data.title || "Permission requested",
+      body: data.body || "",
+      meta: { requestId: data.requestId, toolName: data.toolName, toolInput: data.toolInput || null },
+    };
+  },
+
+  mate_dm: function (data) {
+    return {
+      type: "mate_dm",
+      title: data.senderName || "Message",
+      body: data.preview || "Sent you a message",
+    };
+  },
+};
+
+// ========================================================
+// Module (global singleton)
+// ========================================================
+
+function attachNotifications(ctx) {
+  var broadcastAll = ctx.broadcastAll;
+  var pushModule = ctx.pushModule;
+
+  var notifications = loadNotifications();
+  var reminderTimer = null;
+
+  function loadNotifications() {
+    try {
+      var raw = fs.readFileSync(NOTIF_FILE, "utf8");
+      var parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed;
+    } catch (e) {}
+    return [];
+  }
+
+  function saveNotifications() {
+    var tmp = NOTIF_FILE + ".tmp";
+    try {
+      fs.writeFileSync(tmp, JSON.stringify(notifications, null, 2));
+      fs.renameSync(tmp, NOTIF_FILE);
+    } catch (e) {
+      console.error("[notifications] Failed to save:", e.message);
+    }
+  }
+
+  function getUnreadCount() {
+    return notifications.length;
+  }
+
+  // --- Core API ---
+
+  function notify(event, data) {
+    var formatter = formatters[event];
+    if (!formatter) {
+      console.warn("[notifications] Unknown event: " + event);
+      return null;
+    }
+    var formatted = formatter(data || {});
+    if (!formatted) return null;
+
+    var notif = {
+      id: generateId(),
+      type: formatted.type || event,
+      title: formatted.title || "",
+      body: formatted.body || "",
+      slug: data.slug || "",
+      sessionId: data.sessionId || null,
+      mateId: data.mateId || null,
+      ownerId: data.ownerId || null,
+      createdAt: Date.now(),
+      meta: formatted.meta || {},
+    };
+    notifications.unshift(notif);
+    saveNotifications();
+    broadcastAll({
+      type: "notification_created",
+      notification: notif,
+      unreadCount: getUnreadCount(),
+    });
+    return notif;
+  }
+
+  function dismiss(ids) {
+    var before = notifications.length;
+    notifications = notifications.filter(function(n) { return ids.indexOf(n.id) === -1; });
+    if (notifications.length !== before) {
+      saveNotifications();
+      broadcastAll({
+        type: "notification_dismissed",
+        ids: ids,
+        unreadCount: getUnreadCount(),
+      });
+    }
+  }
+
+  function dismissAll() {
+    if (notifications.length > 0) {
+      notifications = [];
+      saveNotifications();
+      broadcastAll({ type: "notification_dismissed_all", unreadCount: 0 });
+    }
+  }
+
+  // --- Periodic reminder ---
+
+  function startReminder() {
+    if (reminderTimer) return;
+    reminderTimer = setInterval(function () {
+      var count = getUnreadCount();
+      if (count > 0 && pushModule) {
+        pushModule.sendPush({
+          type: "reminder",
+          title: "Clay",
+          body: count + " unread notification" + (count > 1 ? "s" : ""),
+          tag: "clay-notif-reminder",
+        });
+      }
+    }, REMINDER_INTERVAL);
+  }
+
+  function stopReminder() {
+    if (reminderTimer) { clearInterval(reminderTimer); reminderTimer = null; }
+  }
+
+  startReminder();
+
+  // --- Connection state (called per-client with sendTo) ---
+
+  function sendConnectionState(ws, sendTo) {
+    if (!sendTo) return;
+    sendTo(ws, {
+      type: "notifications_state",
+      notifications: notifications,
+      unreadCount: getUnreadCount(),
+    });
+  }
+
+  // --- Message handler ---
+
+  function handleNotificationMessage(ws, msg) {
+    if (msg.type === "notification_dismiss") {
+      dismiss(msg.ids || []);
+      return true;
+    }
+    if (msg.type === "notification_dismiss_all") {
+      dismissAll();
+      return true;
+    }
+    return false;
+  }
+
+  return {
+    notify: notify,
+    getUnreadCount: getUnreadCount,
+    sendConnectionState: sendConnectionState,
+    handleNotificationMessage: handleNotificationMessage,
+    stopReminder: stopReminder,
+  };
+}
+
+module.exports = { attachNotifications: attachNotifications };