@gugu910/pi-slack-bridge 0.1.3

package/dist/pinet-commands.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPinetCommands = registerPinetCommands;
+const helpers_js_1 = require("./helpers.js");
+const activity_log_js_1 = require("./activity-log.js");
+// ─── Registration ────────────────────────────────────────
+function registerPinetCommands(pi, deps) {
+    pi.registerCommand("pinet-start", {
+        description: "Start Pinet as the broker (Slack connection + message routing)",
+        handler: async (_args, ctx) => {
+            if (deps.pinetRegistrationBlocked()) {
+                ctx.ui.notify(deps.getPinetRegistrationBlockReason(), "warning");
+                return;
+            }
+            if (deps.pinetEnabled()) {
+                ctx.ui.notify(`Pinet already running (${deps.brokerRole()})`, "info");
+                return;
+            }
+            deps.setExtCtx(ctx);
+            try {
+                await deps.connectAsBroker(ctx);
+            }
+            catch (err) {
+                ctx.ui.notify(`Pinet broker failed: ${errorMsg(err)}`, "error");
+                deps.setExtStatus(ctx, "error");
+            }
+        },
+    });
+    pi.registerCommand("pinet-follow", {
+        description: "Connect to an existing Pinet broker as a follower",
+        handler: async (_args, ctx) => {
+            if (deps.pinetRegistrationBlocked()) {
+                ctx.ui.notify(deps.getPinetRegistrationBlockReason(), "warning");
+                return;
+            }
+            if (deps.pinetEnabled()) {
+                ctx.ui.notify(`Pinet already running (${deps.brokerRole()})`, "info");
+                return;
+            }
+            deps.setExtCtx(ctx);
+            try {
+                await deps.connectAsFollower(ctx);
+                ctx.ui.notify(`${deps.agentEmoji()} ${deps.agentName()} — following broker`, "info");
+            }
+            catch (err) {
+                ctx.ui.notify(`Pinet follow failed: ${errorMsg(err)}`, "error");
+                deps.setExtStatus(ctx, "error");
+            }
+        },
+    });
+    pi.registerCommand("pinet-unfollow", {
+        description: "Disconnect from the Pinet broker and keep working locally",
+        handler: async (_args, ctx) => {
+            if (!deps.pinetEnabled() || deps.brokerRole() == null) {
+                ctx.ui.notify("Pinet not running. Use /pinet-start or /pinet-follow.", "info");
+                return;
+            }
+            if (deps.brokerRole() !== "follower") {
+                ctx.ui.notify("Pinet is running as broker; /pinet-unfollow only applies to followers.", "warning");
+                return;
+            }
+            const { unregisterError } = await deps.disconnectFollower(ctx);
+            if (unregisterError) {
+                ctx.ui.notify(`Pinet follower disconnected locally, but broker deregistration failed: ${unregisterError}`, "warning");
+                return;
+            }
+            ctx.ui.notify(`${deps.agentEmoji()} ${deps.agentName()} — disconnected from broker; local session still running`, "info");
+        },
+    });
+    pi.registerCommand("pinet-reload", {
+        description: "Tell a connected Pinet agent to reload itself",
+        handler: async (args, ctx) => {
+            const target = args.trim();
+            if (!target) {
+                ctx.ui.notify("Usage: /pinet-reload <agent-name-or-id>", "warning");
+                return;
+            }
+            try {
+                const result = await deps.sendPinetAgentMessage(target, "/reload");
+                ctx.ui.notify(`Sent /reload to ${result.target}`, "info");
+            }
+            catch (err) {
+                ctx.ui.notify(`Pinet reload failed: ${errorMsg(err)}`, "error");
+            }
+        },
+    });
+    pi.registerCommand("pinet-exit", {
+        description: "Tell a connected Pinet agent to exit gracefully",
+        handler: async (args, ctx) => {
+            const target = args.trim();
+            if (!target) {
+                ctx.ui.notify("Usage: /pinet-exit <agent-name-or-id>", "warning");
+                return;
+            }
+            try {
+                const result = await deps.sendPinetAgentMessage(target, "/exit");
+                ctx.ui.notify(`Sent /exit to ${result.target}`, "info");
+            }
+            catch (err) {
+                ctx.ui.notify(`Pinet exit failed: ${errorMsg(err)}`, "error");
+            }
+        },
+    });
+    pi.registerCommand("pinet-free", {
+        description: "Mark this Pinet agent idle/free for new work",
+        handler: async (_args, ctx) => {
+            if (!deps.pinetEnabled()) {
+                ctx.ui.notify("Pinet not running. Use /pinet-start or /pinet-follow.", "info");
+                return;
+            }
+            try {
+                const result = deps.signalAgentFree(ctx, { requirePinet: true });
+                const suffix = result.drainedQueuedInbox
+                    ? ` Processing ${result.queuedInboxCount} queued inbox item${result.queuedInboxCount === 1 ? "" : "s"} now.`
+                    : result.queuedInboxCount > 0
+                        ? ` ${result.queuedInboxCount} queued inbox item${result.queuedInboxCount === 1 ? " remains" : "s remain"}.`
+                        : "";
+                ctx.ui.notify(`Marked ${deps.agentEmoji()} ${deps.agentName()} idle/free for new work.${suffix}`, "info");
+            }
+            catch (err) {
+                ctx.ui.notify(`Pinet free failed: ${errorMsg(err)}`, "error");
+            }
+        },
+    });
+    pi.registerCommand("pinet-skin", {
+        description: "Regenerate the mesh naming/personality skin from a theme",
+        handler: async (args, ctx) => {
+            if (!deps.pinetEnabled() || deps.brokerRole() == null) {
+                ctx.ui.notify("Pinet not running. Use /pinet-start or /pinet-follow.", "info");
+                return;
+            }
+            if (deps.brokerRole() !== "broker") {
+                ctx.ui.notify("/pinet-skin can only run on the active broker.", "warning");
+                return;
+            }
+            try {
+                const result = deps.applyMeshSkin(args);
+                ctx.ui.notify(`Applied mesh skin "${result.theme}" to ${result.updatedAgents.length} agent${result.updatedAgents.length === 1 ? "" : "s"}.`, "info");
+            }
+            catch (err) {
+                ctx.ui.notify(`Pinet skin failed: ${errorMsg(err)}`, "error");
+            }
+        },
+    });
+    pi.registerCommand("pinet-status", {
+        description: "Show Pinet status",
+        handler: async (_args, ctx) => {
+            if (!deps.pinetEnabled()) {
+                ctx.ui.notify("Pinet not running. Use /pinet-start or /pinet-follow.", "info");
+                return;
+            }
+            const mode = deps.brokerRole() === "broker" ? "broker" : "follower";
+            const ownedCount = [...deps.threads().values()].filter((t) => (0, helpers_js_1.agentOwnsThread)(t.owner, deps.agentName(), deps.agentAliases(), deps.agentOwnerToken())).length;
+            const users = deps.allowedUsers();
+            const allowlistInfo = users
+                ? `Allowed users: ${[...users].join(", ")}`
+                : "Allowed users: all (no allowlist set)";
+            const s = deps.settings();
+            const defaultChInfo = s.defaultChannel
+                ? `Default channel: ${s.defaultChannel}`
+                : "Default channel: none";
+            const activityLogInfo = s.logChannel
+                ? `Activity log: ${s.logChannel} (${s.logLevel ?? "actions"})`
+                : "Activity log: disabled";
+            const lbm = deps.lastBrokerMaintenance();
+            const brokerHealthInfo = mode === "broker" && lbm
+                ? [
+                    `Pending backlog: ${lbm.pendingBacklogCount}`,
+                    `Last maintenance: assigned ${lbm.assignedBacklogCount}, reaped ${lbm.reapedAgentIds.length}, repaired ${lbm.repairedThreadClaims}`,
+                    ...(lbm.anomalies.length > 0 ? [`Health: ${lbm.anomalies.join("; ")}`] : []),
+                ]
+                : [];
+            const brokerCanvasInfo = mode === "broker"
+                ? [
+                    `Control plane canvas: ${deps.isBrokerControlPlaneCanvasEnabled()
+                        ? (deps.getConfiguredBrokerControlPlaneCanvasId() ??
+                            `pending (${deps.getConfiguredBrokerControlPlaneCanvasChannel() ?? "no target"})`)
+                        : "disabled"}`,
+                    ...(deps.lastBrokerControlPlaneCanvasRefreshAt()
+                        ? [`Canvas refreshed: ${deps.lastBrokerControlPlaneCanvasRefreshAt()}`]
+                        : []),
+                    ...(deps.lastBrokerControlPlaneCanvasError()
+                        ? [`Canvas status: ${deps.lastBrokerControlPlaneCanvasError()}`]
+                        : []),
+                    `Home tab viewers: ${deps.getBrokerControlPlaneHomeTabViewerIds().length}`,
+                    ...(deps.lastBrokerControlPlaneHomeTabRefreshAt()
+                        ? [`Home tab refreshed: ${deps.lastBrokerControlPlaneHomeTabRefreshAt()}`]
+                        : []),
+                    ...(deps.lastBrokerControlPlaneHomeTabError()
+                        ? [`Home tab status: ${deps.lastBrokerControlPlaneHomeTabError()}`]
+                        : []),
+                ]
+                : [];
+            ctx.ui.notify([
+                `Mode: ${mode}`,
+                `Agent: ${deps.agentEmoji()} ${deps.agentName()}`,
+                `Bot: ${deps.botUserId() ?? "unknown"}`,
+                `Connection: ${mode}`,
+                `Skin: ${deps.activeSkinTheme() ?? "(legacy/manual)"}`,
+                ...(deps.agentPersonality() ? [`Persona: ${deps.agentPersonality()}`] : []),
+                `Threads: ${deps.threads().size} (${ownedCount} owned by ${deps.agentName()})`,
+                `DM channel: ${deps.lastDmChannel() ?? "none yet"}`,
+                allowlistInfo,
+                defaultChInfo,
+                activityLogInfo,
+                ...brokerHealthInfo,
+                ...brokerCanvasInfo,
+            ].join("\n"), "info");
+        },
+    });
+    const showActivityLogs = async (_args, ctx) => {
+        const s = deps.settings();
+        const channelInfo = s.logChannel ? `${s.logChannel} (${s.logLevel ?? "actions"})` : "disabled";
+        ctx.ui.notify([
+            `Activity log channel: ${channelInfo}`,
+            (0, activity_log_js_1.formatRecentActivityLogEntries)(deps.activityLogger().getRecentEntries(10)),
+        ].join("\n\n"), s.logChannel ? "info" : "warning");
+    };
+    pi.registerCommand("pinet-logs", {
+        description: "Show recent broker activity log entries",
+        handler: showActivityLogs,
+    });
+    pi.registerCommand("slack-logs", {
+        description: "Show recent broker activity log entries",
+        handler: showActivityLogs,
+    });
+    pi.registerCommand("pinet-rename", {
+        description: "Rename this Pinet agent",
+        handler: async (args, ctx) => {
+            const newName = args.trim();
+            if (!newName) {
+                const fresh = (0, helpers_js_1.generateAgentName)(undefined, deps.brokerRole() === "broker" ? "broker" : "worker");
+                deps.applyLocalAgentIdentity(fresh.name, fresh.emoji, deps.agentPersonality());
+            }
+            else {
+                deps.applyLocalAgentIdentity(newName, deps.agentEmoji(), deps.agentPersonality());
+            }
+            ctx.ui.notify(`${deps.agentEmoji()} Agent renamed to: ${deps.agentName()}`, "info");
+        },
+    });
+}
+function errorMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/ralph-loop.js

@@ -0,0 +1,385 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRalphLoopState = createRalphLoopState;
+exports.resetRalphLoopState = resetRalphLoopState;
+exports.runRalphLoopCycle = runRalphLoopCycle;
+exports.startRalphLoop = startRalphLoop;
+exports.stopRalphLoop = stopRalphLoop;
+const os = __importStar(require("node:os"));
+const helpers_js_1 = require("./helpers.js");
+const socket_server_js_1 = require("./broker/socket-server.js");
+const client_js_1 = require("./broker/client.js");
+const task_assignments_js_1 = require("./task-assignments.js");
+const git_metadata_js_1 = require("./git-metadata.js");
+function createRalphLoopState() {
+    return {
+        timer: null,
+        running: false,
+        nudges: new Map(),
+        reportedGhosts: new Set(),
+        nonGhostSignature: "",
+        hadOutstandingAnomalies: false,
+        followUpAt: 0,
+        followUpPending: false,
+        taskAssignmentReportSignature: "",
+        pendingTaskAssignmentReport: null,
+    };
+}
+function resetRalphLoopState(state) {
+    if (state.timer) {
+        clearInterval(state.timer);
+        state.timer = null;
+    }
+    state.running = false;
+    state.nudges.clear();
+    state.reportedGhosts.clear();
+    state.nonGhostSignature = "";
+    state.hadOutstandingAnomalies = false;
+    state.followUpAt = 0;
+    state.followUpPending = false;
+    state.taskAssignmentReportSignature = "";
+    state.pendingTaskAssignmentReport = null;
+}
+// ─── Core loop ───────────────────────────────────────────
+async function runRalphLoopCycle(ctx, state, deps) {
+    const db = deps.getBrokerDb();
+    const selfId = deps.getBrokerAgentId();
+    if (!db || !selfId || state.running)
+        return;
+    state.running = true;
+    const cycleStartedAt = new Date().toISOString();
+    const cycleStartMs = Date.now();
+    try {
+        deps.runMaintenance(ctx);
+        const currentBranch = (await (0, git_metadata_js_1.probeGitBranch)(process.cwd())) ?? null;
+        const workloads = db.getAllAgents().map((agent) => ({
+            ...agent,
+            pendingInboxCount: db.getPendingInboxCount(agent.id),
+            ownedThreadCount: db.getOwnedThreadCount(agent.id),
+        }));
+        const pendingBacklogCount = db.getBacklogCount("pending");
+        const evaluationOptions = {
+            now: Date.now(),
+            heartbeatTimeoutMs: socket_server_js_1.DEFAULT_HEARTBEAT_TIMEOUT_MS,
+            heartbeatIntervalMs: client_js_1.HEARTBEAT_INTERVAL_MS,
+            stuckWorkingThresholdMs: helpers_js_1.DEFAULT_RALPH_LOOP_STUCK_WORKING_THRESHOLD_MS,
+            pendingBacklogCount,
+            currentBranch,
+            brokerHeartbeatActive: deps.heartbeatTimerActive(),
+            brokerMaintenanceActive: deps.maintenanceTimerActive(),
+            brokerAgentId: selfId,
+        };
+        const evaluation = (0, helpers_js_1.evaluateRalphLoopCycle)(workloads, evaluationOptions);
+        const now = Date.now();
+        const nudgeAgentIds = new Set(evaluation.nudgeAgentIds);
+        for (const workload of workloads) {
+            if (!nudgeAgentIds.has(workload.id)) {
+                state.nudges.delete(workload.id);
+                continue;
+            }
+            const lastNudgeAt = state.nudges.get(workload.id) ?? 0;
+            if (now - lastNudgeAt < helpers_js_1.DEFAULT_RALPH_LOOP_NUDGE_COOLDOWN_MS) {
+                continue;
+            }
+            deps.sendMaintenanceMessage(workload.id, (0, helpers_js_1.buildRalphLoopNudgeMessage)(workload.pendingInboxCount, workload.ownedThreadCount, cycleStartedAt));
+            state.nudges.set(workload.id, now);
+        }
+        const ghostRewrite = (0, helpers_js_1.rewriteRalphLoopGhostAnomalies)(evaluation, state.reportedGhosts);
+        state.reportedGhosts.clear();
+        for (const ghostId of ghostRewrite.nextReportedGhostIds) {
+            state.reportedGhosts.add(ghostId);
+        }
+        const visibleEvaluation = ghostRewrite.evaluation;
+        const visibleSignature = (0, helpers_js_1.buildRalphLoopAnomalySignature)(visibleEvaluation);
+        const nonGhostSignature = ghostRewrite.nonGhostAnomalies.join("|");
+        const hasOutstandingAnomalies = evaluation.anomalies.length > 0;
+        const ralphNotifications = (0, helpers_js_1.buildRalphLoopCycleNotifications)(visibleEvaluation, cycleStartedAt);
+        const followUpPrompt = ghostRewrite.newGhostIds.length === 0 &&
+            ghostRewrite.clearedGhostIds.length > 0 &&
+            ghostRewrite.nonGhostAnomalies.length === 0
+            ? null
+            : ralphNotifications.followUpPrompt;
+        const agentsById = new Map(workloads.map((workload) => [workload.id, { emoji: workload.emoji, name: workload.name }]));
+        let projectedAssignments = [];
+        const rawTrackedAssignments = db.listTaskAssignments();
+        const trackedAssignmentSourceIds = [
+            ...new Set(rawTrackedAssignments
+                .map((assignment) => assignment.sourceMessageId)
+                .filter((messageId) => messageId != null)),
+        ];
+        const trackedAssignments = (0, task_assignments_js_1.normalizeTrackedTaskAssignments)(rawTrackedAssignments, new Map(db
+            .getMessagesByIds(trackedAssignmentSourceIds)
+            .map((message) => [message.id, message.body])));
+        if (trackedAssignments.length === 0) {
+            state.pendingTaskAssignmentReport = null;
+            state.taskAssignmentReportSignature = "";
+        }
+        else {
+            const resolvedAssignments = await (0, task_assignments_js_1.resolveTaskAssignments)(trackedAssignments, process.cwd());
+            const changedAssignments = resolvedAssignments.filter(task_assignments_js_1.hasTaskAssignmentStatusChange);
+            projectedAssignments = resolvedAssignments.map((assignment) => {
+                if ((0, task_assignments_js_1.hasTaskAssignmentStatusChange)(assignment)) {
+                    db.updateTaskAssignmentProgress(assignment.id, assignment.nextStatus, assignment.nextPrNumber);
+                }
+                return { ...assignment, status: assignment.nextStatus, prNumber: assignment.nextPrNumber };
+            });
+            if (changedAssignments.length > 0) {
+                const openedCount = changedAssignments.filter((a) => a.nextStatus === "pr_open").length;
+                const mergedCount = changedAssignments.filter((a) => a.nextStatus === "pr_merged").length;
+                const closedCount = changedAssignments.filter((a) => a.nextStatus === "pr_closed").length;
+                const tone = closedCount > 0 ? "warning" : mergedCount > 0 || openedCount > 0 ? "success" : "info";
+                const title = mergedCount > 0
+                    ? mergedCount === 1
+                        ? "Task merged"
+                        : "Tasks merged"
+                    : openedCount > 0
+                        ? openedCount === 1
+                            ? "Worker completion recorded"
+                            : "Worker completions recorded"
+                        : "Task progress updated";
+                const summaryParts = [];
+                if (openedCount > 0)
+                    summaryParts.push(`${openedCount} worker completion${openedCount === 1 ? "" : "s"} moved to PR open`);
+                if (mergedCount > 0)
+                    summaryParts.push(`${mergedCount} PR${mergedCount === 1 ? "" : "s"} merged`);
+                if (closedCount > 0)
+                    summaryParts.push(`${closedCount} PR${closedCount === 1 ? "" : "s"} closed`);
+                if (summaryParts.length === 0) {
+                    summaryParts.push(`${changedAssignments.length} tracked assignment${changedAssignments.length === 1 ? " changed" : "s changed"}`);
+                }
+                deps.logActivity({
+                    kind: "task_progress",
+                    level: "actions",
+                    title,
+                    summary: summaryParts.join("; "),
+                    details: changedAssignments.map((a) => {
+                        const next = deps.summarizeTrackedAssignmentStatus(a.nextStatus, a.nextPrNumber, a.branch);
+                        return `${deps.formatTrackedAgent(a.agentId)} — #${a.issueNumber}: ${next.summary}`;
+                    }),
+                    fields: [
+                        { label: "Updated", value: changedAssignments.length },
+                        { label: "Merged", value: mergedCount },
+                        { label: "PR open", value: openedCount },
+                        { label: "Cycle", value: cycleStartedAt },
+                    ],
+                    tone,
+                });
+            }
+            state.pendingTaskAssignmentReport = (0, task_assignments_js_1.getPendingTaskAssignmentReport)(projectedAssignments, agentsById, state.taskAssignmentReportSignature, cycleStartedAt);
+        }
+        const shouldDeliverFollowUp = followUpPrompt != null &&
+            (0, helpers_js_1.shouldDeliverRalphLoopFollowUp)({
+                signature: visibleSignature,
+                lastDeliveredAt: state.followUpAt,
+                now,
+                cooldownMs: helpers_js_1.DEFAULT_RALPH_LOOP_FOLLOW_UP_COOLDOWN_MS,
+                pending: state.followUpPending,
+                idle: ctx.isIdle?.() ?? true,
+            });
+        if (shouldDeliverFollowUp && followUpPrompt) {
+            deps.trySendFollowUp(followUpPrompt, () => {
+                state.followUpPending = true;
+                state.followUpAt = now;
+            });
+        }
+        if (state.pendingTaskAssignmentReport && (ctx.isIdle?.() ?? true)) {
+            const reportToDeliver = state.pendingTaskAssignmentReport;
+            deps.trySendFollowUp(reportToDeliver.message, () => {
+                state.taskAssignmentReportSignature = reportToDeliver.signature;
+                state.pendingTaskAssignmentReport = null;
+            });
+        }
+        const shouldWarn = ghostRewrite.newGhostIds.length > 0 ||
+            (nonGhostSignature.length > 0 && nonGhostSignature !== state.nonGhostSignature);
+        const shouldInform = ghostRewrite.clearedGhostIds.length > 0 && visibleEvaluation.anomalies.length > 0;
+        if (shouldWarn) {
+            ctx.ui.notify(ralphNotifications.anomalyStatus ?? "RALPH loop anomaly detected", "warning");
+        }
+        else if (shouldInform) {
+            ctx.ui.notify(ralphNotifications.anomalyStatus ?? "RALPH loop anomaly detected", "info");
+        }
+        else if (!hasOutstandingAnomalies && state.hadOutstandingAnomalies) {
+            ctx.ui.notify(ralphNotifications.recoveryStatus, "info");
+        }
+        if (shouldWarn || shouldInform) {
+            deps.logActivity({
+                kind: "ralph_event",
+                level: "actions",
+                title: shouldWarn ? "RALPH anomaly detected" : "RALPH status updated",
+                summary: ralphNotifications.anomalyStatus ?? "RALPH loop anomaly detected",
+                details: visibleEvaluation.anomalies,
+                fields: [
+                    { label: "Ghosts", value: visibleEvaluation.ghostAgentIds.length },
+                    { label: "Stuck", value: visibleEvaluation.stuckAgentIds.length },
+                    { label: "Nudged", value: visibleEvaluation.nudgeAgentIds.length },
+                    { label: "Backlog", value: pendingBacklogCount },
+                    { label: "Follow-up", value: shouldDeliverFollowUp },
+                ],
+                tone: shouldWarn ? "warning" : "info",
+            });
+        }
+        else if (!hasOutstandingAnomalies && state.hadOutstandingAnomalies) {
+            deps.logActivity({
+                kind: "ralph_event",
+                level: "actions",
+                title: "RALPH recovered",
+                summary: ralphNotifications.recoveryStatus,
+                details: ["Previous ghost/stall/backlog anomalies cleared."],
+                fields: [
+                    { label: "Backlog", value: pendingBacklogCount },
+                    { label: "Idle workers", value: visibleEvaluation.idleDrainAgentIds.length },
+                ],
+                tone: "success",
+            });
+        }
+        else {
+            deps.logActivity({
+                kind: "ralph_cycle",
+                level: "verbose",
+                title: "RALPH cycle",
+                summary: visibleEvaluation.anomalies.length > 0
+                    ? `${visibleEvaluation.anomalies.length} anomaly entries observed this cycle.`
+                    : "Broker health steady this cycle.",
+                details: visibleEvaluation.anomalies.length > 0 ? visibleEvaluation.anomalies : undefined,
+                fields: [
+                    { label: "Ghosts", value: visibleEvaluation.ghostAgentIds.length },
+                    { label: "Stuck", value: visibleEvaluation.stuckAgentIds.length },
+                    { label: "Nudged", value: visibleEvaluation.nudgeAgentIds.length },
+                    { label: "Idle", value: visibleEvaluation.idleDrainAgentIds.length },
+                    { label: "Backlog", value: pendingBacklogCount },
+                ],
+                tone: visibleEvaluation.anomalies.length > 0 ? "warning" : "info",
+            });
+        }
+        state.nonGhostSignature = nonGhostSignature;
+        state.hadOutstandingAnomalies = hasOutstandingAnomalies;
+        let recentRalphCycles = [];
+        try {
+            const cycleCompletedAt = new Date().toISOString();
+            db.recordRalphCycle({
+                startedAt: cycleStartedAt,
+                completedAt: cycleCompletedAt,
+                durationMs: Date.now() - cycleStartMs,
+                ghostAgentIds: visibleEvaluation.ghostAgentIds,
+                nudgeAgentIds: visibleEvaluation.nudgeAgentIds,
+                idleDrainAgentIds: visibleEvaluation.idleDrainAgentIds,
+                stuckAgentIds: visibleEvaluation.stuckAgentIds,
+                anomalies: visibleEvaluation.anomalies,
+                anomalySignature: visibleSignature,
+                followUpDelivered: shouldDeliverFollowUp,
+                agentCount: workloads.filter((w) => !w.disconnectedAt).length,
+                backlogCount: pendingBacklogCount,
+            });
+            recentRalphCycles = db.getRecentRalphCycles(5).map((cycle) => ({
+                startedAt: cycle.startedAt,
+                completedAt: cycle.completedAt,
+                durationMs: cycle.durationMs,
+                ghostAgentIds: cycle.ghostAgentIds,
+                stuckAgentIds: cycle.stuckAgentIds,
+                anomalies: cycle.anomalies,
+                followUpDelivered: cycle.followUpDelivered,
+                agentCount: cycle.agentCount,
+                backlogCount: cycle.backlogCount,
+            }));
+        }
+        catch {
+            /* best effort */
+        }
+        const controlPlaneInput = {
+            workloads,
+            evaluation: visibleEvaluation,
+            evaluationOptions,
+            maintenance: deps.getLastMaintenance(),
+            assignments: projectedAssignments,
+            recentCycles: recentRalphCycles,
+            cycleStartedAt,
+            cycleDurationMs: Date.now() - cycleStartMs,
+            currentBranch,
+            homedir: os.homedir(),
+        };
+        const controlPlaneSnapshot = deps.buildControlPlaneDashboardSnapshot(controlPlaneInput);
+        deps.setLastHomeTabSnapshot(controlPlaneSnapshot);
+        try {
+            await deps.refreshCanvasDashboard(ctx, controlPlaneInput);
+        }
+        catch (canvasErr) {
+            const canvasMessage = `Pinet broker control plane canvas refresh failed: ${errorMsg(canvasErr)}`;
+            if (canvasMessage !== deps.getLastCanvasError()) {
+                ctx.ui.notify(canvasMessage, "warning");
+            }
+            deps.setLastCanvasError(canvasMessage);
+        }
+        try {
+            await deps.refreshHomeTabs(ctx, controlPlaneSnapshot, cycleStartedAt);
+        }
+        catch (homeTabErr) {
+            const homeTabMessage = `Pinet Home tab publish failed: ${errorMsg(homeTabErr)}`;
+            if (homeTabMessage !== deps.getLastHomeTabError()) {
+                ctx.ui.notify(homeTabMessage, "warning");
+            }
+            deps.setLastHomeTabError(homeTabMessage);
+        }
+    }
+    catch (err) {
+        ctx.ui.notify((0, helpers_js_1.buildRalphLoopStatusMessage)(`failed: ${errorMsg(err)}`, cycleStartedAt), "error");
+        deps.logActivity({
+            kind: "ralph_error",
+            level: "errors",
+            title: "RALPH loop failed",
+            summary: errorMsg(err),
+            fields: [{ label: "Cycle", value: cycleStartedAt }],
+            tone: "error",
+        });
+    }
+    finally {
+        state.running = false;
+    }
+}
+// ─── Timer management ────────────────────────────────────
+function startRalphLoop(ctx, state, deps) {
+    stopRalphLoop(state);
+    state.timer = setInterval(() => {
+        void runRalphLoopCycle(ctx, state, deps);
+    }, helpers_js_1.DEFAULT_RALPH_LOOP_INTERVAL_MS);
+    state.timer.unref?.();
+    void runRalphLoopCycle(ctx, state, deps);
+}
+function stopRalphLoop(state) {
+    resetRalphLoopState(state);
+}
+function errorMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}