feat: add programmatic alerting for worker lifecycle events (#16) (#17)

Adds notification system for full visibility into the DevClaw pipeline:

Events and targets:
- workerStart: Posted to project group when worker spawns/resumes
- workerComplete: Posted to project group when DEV done/QA pass/fail/refine
- heartbeat: Posted to orchestrator DM with tick summary

Implementation:
- New lib/notify.ts module with buildMessage() and sendMessage()
- Integrated into task_pickup, task_complete, and heartbeat_tick
- Uses OpenClaw gateway to invoke message tool

Configuration (optional):
- orchestratorDm: Chat ID for heartbeat notifications
- notifications.heartbeatDm: Enable/disable heartbeat DM (default: true)
- notifications.workerStart: Enable/disable start notifications (default: true)
- notifications.workerComplete: Enable/disable completion notifications (default: true)

Notifications fail silently (logged but don't break main flow).

lib/tools/heartbeat-tick.ts

@@ -29,6 +29,7 @@ import type { ToolContext } from "../types.js";
 import { detectContext, generateGuardrails } from "../context-guard.js";
 import { type Tier } from "../tiers.js";
 import { log as auditLog } from "../audit.js";
+import { notify, getNotificationConfig } from "../notify.js";
 
 /** Labels that map to DEV role */
 const DEV_LABELS: StateLabel[] = ["To Do", "To Improve"];
@@ -496,6 +497,32 @@ export function createHeartbeatTickTool(api: OpenClawPluginApi) {
         skipped: result.skipped.length,
       });
 
+      // Send heartbeat notification to orchestrator DM
+      const notifyConfig = getNotificationConfig(pluginConfig);
+      const orchestratorDm = pluginConfig?.orchestratorDm as string | undefined;
+      
+      await notify(
+        {
+          type: "heartbeat",
+          projectsScanned: projectEntries.length,
+          healthFixes: result.healthFixes.length,
+          pickups: result.pickups.length,
+          skipped: result.skipped.length,
+          dryRun,
+          pickupDetails: result.pickups.map((p) => ({
+            project: p.project,
+            issueId: p.issueId,
+            role: p.role,
+          })),
+        },
+        {
+          workspaceDir,
+          config: notifyConfig,
+          orchestratorDm,
+          channel: "telegram",
+        },
+      );
+
       return jsonResult(result);
     },
   });

lib/tools/task-complete.ts

@@ -25,6 +25,7 @@ import {
   readProjects,
 } from "../projects.js";
 import type { ToolContext } from "../types.js";
+import { notify, getNotificationConfig } from "../notify.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -266,6 +267,42 @@ export function createTaskCompleteTool(api: OpenClawPluginApi) {
         output.announcement = `🤔 QA REFINE #${issueId}${summary ? ` — ${summary}` : ""}. Awaiting human decision.`;
       }
 
+      // Send notification to project group
+      const pluginConfig = api.pluginConfig as Record<string, unknown> | undefined;
+      const notifyConfig = getNotificationConfig(pluginConfig);
+      
+      // Determine next state for the notification
+      let nextState: string | undefined;
+      if (role === "dev" && result === "done") {
+        nextState = "QA queue";
+      } else if (role === "qa" && result === "pass") {
+        nextState = "Done!";
+      } else if (role === "qa" && result === "fail") {
+        nextState = "back to DEV";
+      } else if (role === "qa" && result === "refine") {
+        nextState = "awaiting human decision";
+      }
+
+      await notify(
+        {
+          type: "workerComplete",
+          project: project.name,
+          groupId,
+          issueId,
+          role,
+          result,
+          summary,
+          nextState,
+        },
+        {
+          workspaceDir,
+          config: notifyConfig,
+          groupId,
+          // Channel detection: default to telegram if not available
+          channel: "telegram",
+        },
+      );
+
       // Audit log
       await auditLog(workspaceDir, "task_complete", {
         project: project.name,

lib/tools/task-pickup.ts

@@ -21,6 +21,7 @@ import { getProject, getWorker, readProjects } from "../projects.js";
 import type { ToolContext } from "../types.js";
 import { detectContext, generateGuardrails } from "../context-guard.js";
 import { isDevTier, isTier, type Tier } from "../tiers.js";
+import { notify, getNotificationConfig } from "../notify.js";
 
 /** Labels that map to DEV role */
 const DEV_LABELS: StateLabel[] = ["To Do", "To Improve"];
@@ -300,7 +301,28 @@ export function createTaskPickupTool(api: OpenClawPluginApi) {
         pluginConfig,
       });
 
-      // 9. Build result
+      // 9. Send notification to project group
+      const notifyConfig = getNotificationConfig(pluginConfig);
+      await notify(
+        {
+          type: "workerStart",
+          project: project.name,
+          groupId,
+          issueId: issue.iid,
+          issueTitle: issue.title,
+          role,
+          model: dispatchResult.modelAlias,
+          sessionAction: dispatchResult.sessionAction,
+        },
+        {
+          workspaceDir,
+          config: notifyConfig,
+          groupId,
+          channel: context.channel,
+        },
+      );
+
+      // 10. Build result
       const result: Record<string, unknown> = {
         success: true,
         project: project.name,