reflectt-node 0.1.5 → 0.1.7

package/dist/server.js

@@ -11,7 +11,7 @@ import { createHash } from 'crypto';
 import { promises as fs, existsSync, readFileSync, readdirSync } from 'fs';
 import { resolve, sep, join } from 'path';
 import { execSync } from 'child_process';
-import { serverConfig, openclawConfig, isDev, REFLECTT_HOME } from './config.js';
+import { serverConfig, openclawConfig, isDev, REFLECTT_HOME, DATA_DIR } from './config.js';
 import { trackRequest, getRequestMetrics } from './request-tracker.js';
 import { getPreflightMetrics, snapshotDailyMetrics, getDailySnapshots, startAutoSnapshot } from './alert-preflight.js';
 // ── Build info (read once at startup) ──────────────────────────────────────
@@ -37,6 +37,9 @@ import { chatManager } from './chat.js';
 import { taskManager } from './tasks.js';
 import { detectApproval, applyApproval } from './chat-approval-detector.js';
 import { inboxManager } from './inbox.js';
+import { getFocus, setFocus, clearFocus, getFocusSummary } from './focus.js';
+import { generatePulse, generateCompactPulse } from './pulse.js';
+import { scanScopeOverlap, scanAndNotify } from './scopeOverlap.js';
 import { getDb } from './db.js';
 import { isTestHarnessTask } from './test-task-filter.js';
 import { handleMCPRequest, handleSSERequest, handleMessagesRequest } from './mcp.js';
@@ -91,8 +94,9 @@ import { submitFeedback, listFeedback, getFeedback, updateFeedback, voteFeedback
 import { createEscalation, acknowledgeEscalation, resolveEscalation, tickEscalations, getEscalation, getEscalationByFeedback, listEscalations, } from './escalation.js';
 import { slotManager as canvasSlots } from './canvas-slots.js';
 import { createReflection, getReflection, listReflections, countReflections, reflectionStats, validateReflection, ROLE_TYPES, SEVERITY_LEVELS, recordReflectionDuplicate } from './reflections.js';
-import { ingestReflection, getInsight, listInsights, insightStats, extractClusterKey, tickCooldowns, updateInsightStatus, getOrphanedInsights, reconcileInsightTaskLinks, getLoopSummary } from './insights.js';
-import { patchInsightById } from './insight-mutation.js';
+import { ingestReflection, getInsight, listInsights, insightStats, extractClusterKey, tickCooldowns, updateInsightStatus, getOrphanedInsights, reconcileInsightTaskLinks, getLoopSummary, sweepShippedCandidates } from './insights.js';
+import { queryActivity, ACTIVITY_SOURCES } from './activity.js';
+import { patchInsightById, cooldownInsightById, closeInsightById } from './insight-mutation.js';
 import { promoteInsight, validatePromotionInput, generateRecurringCandidates, listPromotionAudits, getPromotionAuditByInsight } from './insight-promotion.js';
 import { runIntake, batchIntake, pipelineMaintenance, getPipelineStats } from './intake-pipeline.js';
 import { listLineage, getLineage, lineageStats } from './lineage.js';
@@ -154,6 +158,8 @@ const CreateTaskSchema = z.object({
     tags: z.array(z.string()).optional(),
     teamId: z.string().optional(),
     metadata: z.record(z.unknown()).optional(),
+    dueAt: z.number().int().positive().optional(), // epoch ms — when the task is due
+    scheduledFor: z.number().int().positive().optional(), // epoch ms — when work should start
 });
 /**
  * Definition-of-ready check: validates task quality at creation time.
@@ -279,6 +285,8 @@ const UpdateTaskSchema = z.object({
     tags: z.array(z.string()).optional(),
     metadata: z.record(z.unknown()).optional(),
     actor: z.string().trim().min(1).optional(),
+    dueAt: z.number().int().positive().nullable().optional(), // epoch ms, null to clear
+    scheduledFor: z.number().int().positive().nullable().optional(), // epoch ms, null to clear
 });
 const CreateTaskCommentSchema = z.object({
     author: z.string().trim().min(1),
@@ -582,10 +590,26 @@ function enforceQaBundleGateForValidating(status, metadata, expectedTaskId) {
             };
         }
     }
+    // Early format validation: PR URL must be a valid GitHub PR URL
+    if (reviewPacket?.pr_url && !/^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+$/.test(reviewPacket.pr_url)) {
+        return {
+            ok: false,
+            error: `Invalid PR URL format: "${reviewPacket.pr_url}"`,
+            hint: 'Expected format: https://github.com/owner/repo/pull/123',
+        };
+    }
+    // Early format validation: commit SHA must be 7-40 hex chars
+    if (reviewPacket?.commit && !/^[a-f0-9]{7,40}$/i.test(reviewPacket.commit)) {
+        return {
+            ok: false,
+            error: `Invalid commit SHA format: "${reviewPacket.commit}"`,
+            hint: 'Expected 7-40 hex characters, e.g. "a1b2c3d"',
+        };
+    }
     if (reviewPacket && !nonCodeLane && expectedTaskId && reviewPacket.task_id !== expectedTaskId) {
         return {
             ok: false,
-            error: `Review packet task mismatch: metadata.qa_bundle.review_packet.task_id must match ${expectedTaskId}`,
+            error: `Review packet task mismatch: got "${reviewPacket.task_id}", expected "${expectedTaskId}"`,
             hint: 'Set review_packet.task_id to the current task ID before moving to validating.',
         };
     }
@@ -593,7 +617,7 @@ function enforceQaBundleGateForValidating(status, metadata, expectedTaskId) {
     if (reviewPacket && !nonCodeLane && artifactPath && artifactPath !== reviewPacket.artifact_path) {
         return {
             ok: false,
-            error: 'Review packet mismatch: metadata.qa_bundle.review_packet.artifact_path must match metadata.artifact_path',
+            error: `Review packet artifact_path mismatch: got "${reviewPacket.artifact_path}", expected "${artifactPath}"`,
             hint: 'Use the same canonical process/... artifact path in both fields.',
         };
     }
@@ -857,7 +881,7 @@ function enforceReviewHandoffGateForValidating(status, taskId, metadata) {
     if (handoff.task_id !== taskId) {
         return {
             ok: false,
-            error: `Review handoff task_id mismatch: expected ${taskId}`,
+            error: `Review handoff task_id mismatch: got "${handoff.task_id}", expected "${taskId}"`,
             hint: 'Set metadata.review_handoff.task_id to the exact task being transitioned.',
         };
     }
@@ -1909,7 +1933,7 @@ export async function createServer() {
                 : {
                     status: 'not configured',
                     hint: 'Set OPENCLAW_GATEWAY_URL and OPENCLAW_GATEWAY_TOKEN environment variables, or run: openclaw gateway token',
-                    docs: 'https://reflectt.ai/bootstrap',
+                    docs: 'https://app.reflectt.ai',
                 },
             chat: chatManager.getStats(),
             tasks: taskManager.getStats({ includeTest }),
@@ -1922,6 +1946,15 @@ export async function createServer() {
         };
     });
     // ─── Request errors — last N errors for launch-day debugging ───
+    app.get('/health/chat', async () => {
+        const stats = chatManager.getStats();
+        return {
+            totalMessages: stats.totalMessages,
+            rooms: stats.rooms,
+            subscribers: stats.subscribers,
+            drops: stats.drops,
+        };
+    });
     app.get('/health/errors', async () => {
         const m = getRequestMetrics();
         return {
@@ -2310,8 +2343,17 @@ export async function createServer() {
                     done: done.length,
                     resolvedExternally: resolvedExternally.length,
                 },
+                // Top-level convenience aliases (never null)
+                readyCount: ready.length,
+                wipCount: doing.length,
                 compliance: {
                     status: floorBreaches.length > 0 ? 'breach' : ready.length >= config.readyFloor ? 'healthy' : 'warning',
+                    breaches: floorBreaches.map(a => ({
+                        agent: a.agent,
+                        ready: a.ready,
+                        required: config.readyFloor,
+                        deficit: config.readyFloor - a.ready,
+                    })),
                     floorBreaches: floorBreaches.map(a => ({
                         agent: a.agent,
                         ready: a.ready,
@@ -2684,6 +2726,8 @@ export async function createServer() {
             pid: build.pid,
             nodeVersion: build.nodeVersion,
             uptime: build.uptime,
+            dataDir: DATA_DIR,
+            reflecttHome: REFLECTT_HOME,
         };
     });
     // Error logs (for debugging)
@@ -2837,11 +2881,46 @@ export async function createServer() {
             const __dirname = dirname(__filename);
             const publicDir = join(__dirname, '..', 'public', 'avatars');
             if (safe) {
-                const filePath = join(publicDir, filename);
-                const data = await fs.readFile(filePath);
-                const ext = filename.toLowerCase().endsWith('.svg') ? 'image/svg+xml' : 'image/png';
-                reply.type(ext).header('Cache-Control', 'public, max-age=3600').send(data);
-                return;
+                const lower = filename.toLowerCase();
+                const ext = lower.endsWith('.svg') ? 'image/svg+xml' : 'image/png';
+                // 1) Exact avatar file
+                try {
+                    const filePath = join(publicDir, filename);
+                    const data = await fs.readFile(filePath);
+                    reply.type(ext).header('Cache-Control', 'public, max-age=3600').send(data);
+                    return;
+                }
+                catch {
+                    // fall through to fallback handling below
+                }
+                // 2) Some clients request generic agent-N.png assets. Serve a deterministic
+                // fallback PNG instead of returning 404 (noise) or a mismatched SVG.
+                if (lower.endsWith('.png')) {
+                    const match = /^agent-(\d+)\.png$/.exec(lower);
+                    const fallbackPool = [
+                        'kai.png',
+                        'link.png',
+                        'sage.png',
+                        'pixel.png',
+                        'echo.png',
+                        'scout.png',
+                        'harmony.png',
+                        'spark.png',
+                        'rhythm.png',
+                        'ryan.png',
+                    ];
+                    const n = match ? Number(match[1]) : NaN;
+                    const index = Number.isFinite(n) ? (Math.max(1, n) - 1) % fallbackPool.length : 0;
+                    const fallbackName = fallbackPool[index] || 'ryan.png';
+                    try {
+                        const data = await fs.readFile(join(publicDir, fallbackName));
+                        reply.type('image/png').header('Cache-Control', 'public, max-age=3600').send(data);
+                        return;
+                    }
+                    catch {
+                        // fall through to SVG default below
+                    }
+                }
             }
         }
         catch {
@@ -3018,7 +3097,7 @@ export async function createServer() {
         // Auto-update presence: if you're posting, you're active
         if (data.from) {
             presenceManager.recordActivity(data.from, 'message');
-            presenceManager.updatePresence(data.from, 'working');
+            presenceManager.touchPresence(data.from);
             // Activation funnel: first team message
             emitActivationEvent('first_team_message_sent', data.from, {
                 channel: data.channel || 'general',
@@ -3657,22 +3736,38 @@ export async function createServer() {
         const { metadata, description, done_criteria, ...slim } = task;
         return slim;
     };
-    const isCompact = (query) => query.compact === '1' || query.compact === 'true';
+    const isCompact = (query) => {
+        const v = Array.isArray(query.compact) ? query.compact[0] : query.compact;
+        return v === '1' || v === 'true';
+    };
     // List tasks
     app.get('/tasks', async (request, reply) => {
         const query = request.query;
-        const updatedSince = parseEpochMs(query.updatedSince || query.since);
-        const limit = boundedLimit(query.limit, DEFAULT_LIMITS.tasks, MAX_LIMITS.tasks);
-        const tagFilter = query.tag
-            ? [query.tag]
-            : (query.tags ? query.tags.split(',') : undefined);
-        const includeTest = query.include_test === '1' || query.include_test === 'true';
+        const updatedSince = parseEpochMs((Array.isArray(query.updatedSince) ? query.updatedSince[0] : query.updatedSince) || (Array.isArray(query.since) ? query.since[0] : query.since));
+        const limitRaw = Array.isArray(query.limit) ? query.limit[0] : query.limit;
+        const limit = boundedLimit(limitRaw, DEFAULT_LIMITS.tasks, MAX_LIMITS.tasks);
+        const tagRaw = Array.isArray(query.tag) ? query.tag[0] : query.tag;
+        const tagsRaw = Array.isArray(query.tags) ? query.tags[0] : query.tags;
+        const tagFilter = tagRaw
+            ? [tagRaw]
+            : (tagsRaw ? tagsRaw.split(',') : undefined);
+        const includeTestRaw = Array.isArray(query.include_test) ? query.include_test[0] : query.include_test;
+        const includeTest = includeTestRaw === '1' || includeTestRaw === 'true';
+        // Normalize status: supports ?status=todo, ?status[]=todo&status[]=doing,
+        // and repeated ?status=todo&status=doing (Fastify parses as array)
+        const VALID_STATUSES = ['todo', 'doing', 'blocked', 'validating', 'done', 'cancelled'];
+        const statusRaw = query.status;
+        const statusFilter = statusRaw === undefined
+            ? undefined
+            : (Array.isArray(statusRaw)
+                ? statusRaw.filter((s) => VALID_STATUSES.includes(s))
+                : VALID_STATUSES.includes(statusRaw) ? [statusRaw] : undefined);
         let tasks = taskManager.listTasks({
-            status: query.status,
-            assignee: query.assignee || query.assignedTo, // Support both for backward compatibility
-            createdBy: query.createdBy,
-            teamId: normalizeTeamId(query.teamId),
-            priority: query.priority,
+            status: statusFilter && statusFilter.length === 1 ? statusFilter[0] : (statusFilter && statusFilter.length > 1 ? statusFilter : undefined),
+            assignee: (Array.isArray(query.assignee) ? query.assignee[0] : query.assignee) || (Array.isArray(query.assignedTo) ? query.assignedTo[0] : query.assignedTo),
+            createdBy: Array.isArray(query.createdBy) ? query.createdBy[0] : query.createdBy,
+            teamId: normalizeTeamId(Array.isArray(query.teamId) ? query.teamId[0] : query.teamId),
+            priority: (Array.isArray(query.priority) ? query.priority[0] : query.priority),
             tags: tagFilter,
             includeTest,
         });
@@ -3680,7 +3775,8 @@ export async function createServer() {
             tasks = tasks.filter(task => task.updatedAt >= updatedSince);
         }
         // Text search filter
-        const searchQuery = (query.q || '').trim().toLowerCase();
+        const qRaw = Array.isArray(query.q) ? query.q[0] : query.q;
+        const searchQuery = (qRaw || '').trim().toLowerCase();
         if (searchQuery) {
             tasks = tasks.filter(task => (task.title || '').toLowerCase().includes(searchQuery) ||
                 (task.description || '').toLowerCase().includes(searchQuery) ||
@@ -3688,7 +3784,7 @@ export async function createServer() {
                 (task.id || '').toLowerCase().includes(searchQuery));
         }
         const total = tasks.length;
-        const offset = parsePositiveInt(query.offset) || 0;
+        const offset = parsePositiveInt(Array.isArray(query.offset) ? query.offset[0] : query.offset) || 0;
         tasks = tasks.slice(offset, offset + limit);
         const hasMore = offset + tasks.length < total;
         const enriched = tasks.map(enrichTaskWithComments);
@@ -4945,7 +5041,7 @@ export async function createServer() {
                 }
             }
             presenceManager.recordActivity(data.author, 'message');
-            presenceManager.updatePresence(data.author, 'working');
+            presenceManager.touchPresence(data.author);
             // Heartbeat discipline: compute gap since previous comment for doing tasks
             let heartbeatWarning;
             if (task && task.status === 'doing' && !comment.suppressed) {
@@ -5010,6 +5106,44 @@ export async function createServer() {
             return { success: false, error: err.message || 'Failed to capture outcome verdict' };
         }
     });
+    // ── Cancel a task (convenience endpoint) ──
+    app.post('/tasks/:id/cancel', async (request, reply) => {
+        const task = taskManager.getTask(request.params.id);
+        if (!task) {
+            reply.code(404);
+            return { success: false, error: 'Task not found' };
+        }
+        if (task.status === 'cancelled') {
+            return { success: true, message: 'Task already cancelled', task: enrichTaskWithComments(task) };
+        }
+        if (task.status === 'done') {
+            reply.code(400);
+            return { success: false, error: 'Cannot cancel a done task. Use metadata.reopen=true first.' };
+        }
+        const body = (request.body || {});
+        const reason = typeof body.reason === 'string' ? body.reason : undefined;
+        const author = typeof body.author === 'string' ? body.author : 'system';
+        if (!reason) {
+            reply.code(400);
+            return { success: false, error: 'Cancel reason required. Include { "reason": "..." } in request body.' };
+        }
+        try {
+            const updated = await taskManager.updateTask(task.id, {
+                status: 'cancelled',
+                metadata: {
+                    ...(task.metadata || {}),
+                    cancel_reason: reason,
+                    cancelled_by: author,
+                    cancelled_at: new Date().toISOString(),
+                },
+            });
+            return { success: true, task: updated ? enrichTaskWithComments(updated) : null };
+        }
+        catch (err) {
+            reply.code(400);
+            return { success: false, error: err.message || 'Failed to cancel task' };
+        }
+    });
     // Build normalized reviewer packet (PR + CI + artifacts)
     app.post('/tasks/:id/review-bundle', async (request, reply) => {
         const task = taskManager.getTask(request.params.id);
@@ -5319,7 +5453,12 @@ export async function createServer() {
     // Create task
     app.post('/tasks', async (request, reply) => {
         try {
-            const data = CreateTaskSchema.parse(request.body);
+            // Normalize legacy "in-progress" → "doing" before schema validation
+            const rawPostBody = request.body;
+            if (rawPostBody && typeof rawPostBody === 'object' && rawPostBody.status === 'in-progress') {
+                rawPostBody.status = 'doing';
+            }
+            const data = CreateTaskSchema.parse(rawPostBody);
             // Reject TEST: prefixed tasks in production to prevent CI pollution
             if (process.env.NODE_ENV === 'production' && typeof data.title === 'string' && data.title.startsWith('TEST:')) {
                 reply.code(400);
@@ -5429,9 +5568,10 @@ export async function createServer() {
                 ...(normalizedTeamId ? { teamId: normalizedTeamId } : {}),
                 metadata: newMetadata,
             });
-            // Auto-update presence: creating tasks = working
+            // Touch presence: creating tasks proves the agent is alive, but shouldn't
+            // override task-derived status (e.g. agent filing a task while reviewing)
             if (data.createdBy) {
-                presenceManager.updatePresence(data.createdBy, 'working');
+                presenceManager.touchPresence(data.createdBy);
             }
             // Fire-and-forget: index task for semantic search
             if (!data.title.startsWith('TEST:')) {
@@ -5439,6 +5579,21 @@ export async function createServer() {
                     .then(({ indexTask }) => indexTask(task.id, task.title, undefined, data.done_criteria))
                     .catch(() => { });
             }
+            // Auto-link insight when task is manually created with source_insight metadata.
+            // Mirrors the bridge's updateInsightStatus call so insights don't stay pending_triage
+            // after an agent manually files a task addressing them.
+            const sourceInsightId = typeof newMetadata.source_insight === 'string' ? newMetadata.source_insight : null;
+            if (sourceInsightId && !sourceInsightId.startsWith('ins-test-')) {
+                try {
+                    const linkedInsight = getInsight(sourceInsightId);
+                    if (linkedInsight && linkedInsight.status !== 'task_created' && linkedInsight.status !== 'closed') {
+                        updateInsightStatus(sourceInsightId, 'task_created', task.id);
+                    }
+                }
+                catch {
+                    // Non-fatal: insight link failure must not block task creation
+                }
+            }
             trackTaskEvent('created');
             return { success: true, task: enrichTaskWithComments(task), warnings: creationWarnings };
         }
@@ -5926,7 +6081,13 @@ export async function createServer() {
     // Update task
     app.patch('/tasks/:id', async (request, reply) => {
         try {
-            const parsed = UpdateTaskSchema.parse(request.body);
+            // Normalize legacy "in-progress" → "doing" before schema validation.
+            // Some agents (and older MCP callers) use the deprecated status name.
+            const rawBody = request.body;
+            if (rawBody && typeof rawBody === 'object' && rawBody.status === 'in-progress') {
+                rawBody.status = 'doing';
+            }
+            const parsed = UpdateTaskSchema.parse(rawBody);
             const lookup = taskManager.resolveTaskId(request.params.id);
             if (lookup.matchType === 'ambiguous') {
                 reply.code(400);
@@ -6089,6 +6250,29 @@ export async function createServer() {
                     hint: duplicateGate.hint,
                 };
             }
+            // Early format validation: catch bad PR URLs and commit SHAs on any update, not just at validating transition
+            const earlyReviewPacket = mergedMeta?.qa_bundle?.review_packet;
+            const earlyHandoff = mergedMeta?.review_handoff;
+            const earlyPrUrl = (earlyReviewPacket?.pr_url ?? earlyHandoff?.pr_url);
+            const earlyCommit = (earlyReviewPacket?.commit ?? earlyHandoff?.commit_sha);
+            if (earlyPrUrl && typeof earlyPrUrl === 'string' && !/^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+$/.test(earlyPrUrl)) {
+                reply.code(400);
+                return {
+                    success: false,
+                    error: `Invalid PR URL format: "${earlyPrUrl}"`,
+                    gate: 'format_validation',
+                    hint: 'Expected format: https://github.com/owner/repo/pull/123',
+                };
+            }
+            if (earlyCommit && typeof earlyCommit === 'string' && earlyCommit.length > 0 && !/^[a-f0-9]{7,40}$/i.test(earlyCommit)) {
+                reply.code(400);
+                return {
+                    success: false,
+                    error: `Invalid commit SHA format: "${earlyCommit}"`,
+                    gate: 'format_validation',
+                    hint: 'Expected 7-40 hex characters, e.g. "a1b2c3d"',
+                };
+            }
             // QA bundle gate: validating requires structured review evidence.
             const effectiveStatus = parsed.status ?? existing.status;
             const qaGate = enforceQaBundleGateForValidating(parsed.status, mergedMeta, existing.id);
@@ -6424,6 +6608,25 @@ export async function createServer() {
                     presenceManager.updatePresence(task.assignee, 'reviewing');
                 }
             }
+            // ── Reviewer notification: @mention reviewer when task enters validating ──
+            if (parsed.status === 'validating' && existing.status !== 'validating' && existing.reviewer) {
+                const taskMeta = task.metadata;
+                const prUrl = taskMeta?.review_handoff?.pr_url
+                    ?? taskMeta?.qa_bundle?.pr_url
+                    ?? '';
+                const prLine = prUrl ? `\nPR: ${prUrl}` : '';
+                chatManager.sendMessage({
+                    from: 'system',
+                    content: `@${existing.reviewer} [reviewRequested:${task.id}] ${task.title} → validating${prLine}`,
+                    channel: 'task-notifications',
+                    metadata: {
+                        kind: 'review_requested',
+                        taskId: task.id,
+                        reviewer: existing.reviewer,
+                        prUrl: prUrl || undefined,
+                    },
+                }).catch(() => { }); // Non-blocking
+            }
             // ── Activation funnel: track first_task_started / first_task_completed ──
             {
                 const funnelUserId = task.metadata?.userId || task.assignee || '';
@@ -6515,6 +6718,24 @@ export async function createServer() {
             }
             if (parsed.status === 'validating' && task.reviewer) {
                 statusNotifTargets.push({ agent: task.reviewer, type: 'reviewRequested' });
+                // ── Explicit reviewer routing: ping reviewer with PR link + ask ──
+                const prUrl = task.metadata?.pr_url
+                    || task.metadata?.qa_bundle?.pr_url
+                    || task.metadata?.review_handoff?.pr_url;
+                const prLink = typeof prUrl === 'string' && prUrl ? ` — ${prUrl}` : '';
+                const reviewMsg = `@${task.reviewer} review requested: **${task.title}** (${task.id})${prLink}. Please approve or flag issues.`;
+                chatManager.sendMessage({
+                    from: 'system',
+                    content: reviewMsg,
+                    channel: 'reviews',
+                    metadata: {
+                        kind: 'review_routing',
+                        taskId: task.id,
+                        reviewer: task.reviewer,
+                        assignee: task.assignee,
+                        prUrl: prUrl || null,
+                    },
+                }).catch(() => { }); // Non-blocking
             }
             if (parsed.status === 'done') {
                 if (task.assignee)
@@ -7675,8 +7896,41 @@ export async function createServer() {
         reply.code(201);
         return { success: true, insight, cluster_key: extractClusterKey(reflection) };
     });
+    // ── Activity Timeline ──────────────────────────────────────────────────
+    app.get('/activity', async (request) => {
+        const query = request.query;
+        const range = query.range === '7d' ? '7d' : '24h';
+        const type = query.type ? query.type.split(',').map(t => t.trim()).filter(Boolean) : undefined;
+        const agent = query.agent || undefined;
+        const limit = query.limit ? Number(query.limit) : undefined;
+        const after = query.after || undefined;
+        // debug=1 only allowed from localhost
+        const isLocalhost = request.ip === '127.0.0.1' || request.ip === '::1' || request.ip === '::ffff:127.0.0.1';
+        const debug = query.debug === '1' && isLocalhost;
+        try {
+            return queryActivity({ range, type, agent, limit, after, debug });
+        }
+        catch (err) {
+            request.log.error({ err }, 'Activity query failed');
+            throw err;
+        }
+    });
+    app.get('/activity/sources', async () => {
+        return {
+            sources: [...ACTIVITY_SOURCES],
+            description: 'Allowed values for partial.missing[] and type filter',
+        };
+    });
     app.get('/insights', async (request) => {
         const query = request.query;
+        // Hygiene: when listing candidate insights, proactively cool down any
+        // candidates whose promoted task is already done/cancelled so they don't resurface.
+        // Keep listInsights() itself pure (no DB writes on read).
+        if (query.status === 'candidate') {
+            const offset = query.offset ? Number(query.offset) || 0 : 0;
+            if (offset === 0)
+                sweepShippedCandidates();
+        }
         const result = listInsights({
             status: query.status,
             priority: query.priority,
@@ -7795,6 +8049,104 @@ export async function createServer() {
         }
         return { success: true, insight: result.insight };
     });
+    // Narrow localhost-only admin endpoints for routine hygiene: cooldown/close.
+    // These avoid enabling the broader PATCH /insights/:id mutation API.
+    app.post('/insights/:id/cooldown', async (request, reply) => {
+        const ip = String(request.ip || '');
+        const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+        if (!isLoopback) {
+            reply.code(403);
+            return {
+                success: false,
+                error: 'Forbidden: localhost-only endpoint',
+                hint: `Request ip (${ip || 'unknown'}) is not loopback`,
+            };
+        }
+        const requiredToken = process.env.REFLECTT_INSIGHT_MUTATION_TOKEN;
+        if (requiredToken) {
+            const raw = request.headers['x-reflectt-admin-token'];
+            let provided = Array.isArray(raw) ? raw[0] : raw;
+            const auth = request.headers.authorization;
+            if ((!provided || typeof provided !== 'string') && typeof auth === 'string' && auth.startsWith('Bearer ')) {
+                provided = auth.slice('Bearer '.length);
+            }
+            if (typeof provided !== 'string' || provided !== requiredToken) {
+                reply.code(403);
+                return {
+                    success: false,
+                    error: 'Forbidden: missing/invalid admin token',
+                    hint: 'Provide x-reflectt-admin-token header (or Authorization: Bearer ...) matching REFLECTT_INSIGHT_MUTATION_TOKEN.'
+                };
+            }
+        }
+        const body = (request.body ?? {});
+        const actor = typeof body.actor === 'string' ? body.actor : '';
+        const reason = typeof body.reason === 'string' ? body.reason : '';
+        const notes = typeof body.notes === 'string' ? body.notes : undefined;
+        const cooldown_reason = typeof body.cooldown_reason === 'string' ? body.cooldown_reason : undefined;
+        const cooldown_until = typeof body.cooldown_until === 'number' && Number.isFinite(body.cooldown_until)
+            ? body.cooldown_until
+            : (typeof body.cooldown_ms === 'number' && Number.isFinite(body.cooldown_ms)
+                ? Date.now() + Math.max(0, body.cooldown_ms)
+                : undefined);
+        const result = cooldownInsightById(request.params.id, {
+            actor,
+            reason,
+            ...(notes ? { notes } : {}),
+            ...(cooldown_until ? { cooldown_until } : {}),
+            ...(cooldown_reason ? { cooldown_reason } : {}),
+        });
+        if (!result.success) {
+            const notFound = result.error === 'Insight not found';
+            reply.code(notFound ? 404 : 400);
+            return { success: false, error: result.error };
+        }
+        return { success: true, insight: result.insight };
+    });
+    app.post('/insights/:id/close', async (request, reply) => {
+        const ip = String(request.ip || '');
+        const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+        if (!isLoopback) {
+            reply.code(403);
+            return {
+                success: false,
+                error: 'Forbidden: localhost-only endpoint',
+                hint: `Request ip (${ip || 'unknown'}) is not loopback`,
+            };
+        }
+        const requiredToken = process.env.REFLECTT_INSIGHT_MUTATION_TOKEN;
+        if (requiredToken) {
+            const raw = request.headers['x-reflectt-admin-token'];
+            let provided = Array.isArray(raw) ? raw[0] : raw;
+            const auth = request.headers.authorization;
+            if ((!provided || typeof provided !== 'string') && typeof auth === 'string' && auth.startsWith('Bearer ')) {
+                provided = auth.slice('Bearer '.length);
+            }
+            if (typeof provided !== 'string' || provided !== requiredToken) {
+                reply.code(403);
+                return {
+                    success: false,
+                    error: 'Forbidden: missing/invalid admin token',
+                    hint: 'Provide x-reflectt-admin-token header (or Authorization: Bearer ...) matching REFLECTT_INSIGHT_MUTATION_TOKEN.'
+                };
+            }
+        }
+        const body = (request.body ?? {});
+        const actor = typeof body.actor === 'string' ? body.actor : '';
+        const reason = typeof body.reason === 'string' ? body.reason : '';
+        const notes = typeof body.notes === 'string' ? body.notes : undefined;
+        const result = closeInsightById(request.params.id, {
+            actor,
+            reason,
+            ...(notes ? { notes } : {}),
+        });
+        if (!result.success) {
+            const notFound = result.error === 'Insight not found';
+            reply.code(notFound ? 404 : 400);
+            return { success: false, error: result.error };
+        }
+        return { success: true, insight: result.insight };
+    });
     app.get('/insights/stats', async () => {
         return insightStats();
     });
@@ -8412,7 +8764,31 @@ export async function createServer() {
         }
         const task = taskManager.getNextTask(agent, { includeTest });
         if (!task) {
-            return { task: null, message: 'No available tasks' };
+            const aliases = agent ? getAgentAliases(agent) : [];
+            // "Ready" counts: match /tasks/next selection semantics (blocked excluded)
+            const readyTodo = taskManager.listTasks({ status: 'todo', includeBlocked: false, includeTest });
+            const ready_todo_unassigned = readyTodo.filter(t => {
+                const a = String(t.assignee || '').trim().toLowerCase();
+                return a.length === 0 || a === 'unassigned';
+            }).length;
+            const ready_todo_assigned = agent
+                ? taskManager.listTasks({ status: 'todo', assigneeIn: aliases, includeBlocked: false, includeTest }).length
+                : 0;
+            const ready_doing_assigned = agent
+                ? taskManager.listTasks({ status: 'doing', assigneeIn: aliases, includeBlocked: false, includeTest }).length
+                : 0;
+            const ready_validating_assigned = agent
+                ? taskManager.listTasks({ status: 'validating', assigneeIn: aliases, includeBlocked: false, includeTest }).length
+                : 0;
+            const { formatTasksNextEmptyResponse } = await import('./tasks-next-diagnostics.js');
+            const payload = formatTasksNextEmptyResponse({
+                agent,
+                ready_doing_assigned,
+                ready_todo_unassigned,
+                ready_todo_assigned,
+                ready_validating_assigned,
+            });
+            return { task: null, ...payload };
         }
         // Rule C: auto-claim (todo→doing) when ?claim=1
         const shouldClaim = query.claim === '1' || query.claim === 'true';
@@ -8515,7 +8891,11 @@ export async function createServer() {
         }));
         const todoTasks = taskManager.listTasks({ status: 'todo', assigneeIn: getAgentAliases(agent) });
         const validatingTasks = taskManager.listTasks({ status: 'validating', assigneeIn: getAgentAliases(agent) });
-        const slim = (t) => t ? { id: t.id, title: t.title, status: t.status, priority: t.priority } : null;
+        const slim = (t) => t ? {
+            id: t.id, title: t.title, status: t.status, priority: t.priority,
+            ...(t.dueAt ? { dueAt: t.dueAt } : {}),
+            ...(t.scheduledFor ? { scheduledFor: t.scheduledFor } : {}),
+        } : null;
         presenceManager.recordActivity(agent, 'heartbeat');
         // Check pause status
         const pauseStatus = checkPauseStatus(agent);
@@ -8523,12 +8903,18 @@ export async function createServer() {
         const { getIntensity, checkPullBudget } = await import('./intensity.js');
         const intensity = getIntensity();
         const pullBudget = checkPullBudget(agent);
+        // Drop stats for this agent
+        const allDrops = chatManager.getDropStats();
+        const agentDrops = allDrops[agent];
+        const focusSummary = getFocusSummary();
         return {
             agent, ts: Date.now(),
             active: slim(activeTask), next: pauseStatus.paused ? null : slim(nextTask),
             inbox: slimInbox, inboxCount: inbox.length,
             queue: { todo: todoTasks.length, doing: doingTasks.length, validating: validatingTasks.length },
             intensity: { preset: intensity.preset, pullsRemaining: pullBudget.remaining, wipLimit: intensity.limits.wipLimit },
+            ...(focusSummary ? { focus: focusSummary } : {}),
+            ...(agentDrops ? { drops: { total: agentDrops.total, rolling_1h: agentDrops.rolling_1h } } : {}),
             ...(pauseStatus.paused ? { paused: true, pauseMessage: pauseStatus.message, resumesAt: pauseStatus.entry?.pausedUntil ?? null } : {}),
             action: pauseStatus.paused ? `PAUSED: ${pauseStatus.message}`
                 : activeTask ? `Continue ${activeTask.id}`
@@ -8571,12 +8957,16 @@ If your heartbeat shows **no active task** and **no next task**:
 4. If the board + signals are empty, write up what you checked and propose a next step in a problems/ideas channel if your team has one (otherwise use \`#general\`).
 5. If you’re still idle after checking, propose the next highest-leverage work item with evidence — don’t wait for someone else to assign it.
 
-## Comms Protocol (recommended)
-1. **Status updates belong in task comments first** (\`POST /tasks/:id/comments\`).
-2. **Shipped artifacts**: post in a shipping/release channel (if your team uses one) and include \`@reviewer\` + task ID + PR/artifact link.
-3. **Review requests**: post in a reviews channel (if your team uses one) and include \`@reviewer\` + task ID + exact ask.
-4. **Blockers**: post in a blockers channel (if your team uses one) and include **who you need** + task ID + concrete unblock needed.
-5. Keep \`#general\` for decisions/cross-team coordination (not routine heartbeat chatter).
+## Comms Protocol (required)
+**Rule: task updates go to the task, not to chat.**
+- \`POST /tasks/:id/comments\` for all progress, blockers, and decisions on a task.
+- Chat channels are for coordination, not status reports. Do not post "working on task-xyz" or "done with task-xyz" to chat.
+
+1. **Task progress, blockers, decisions** → \`POST /tasks/:id/comments\` (always first)
+2. **Shipped artifacts** → post in shipping channel after the task comment, include \`@reviewer\` + task ID + PR/artifact link
+3. **Review requests** → post in reviews channel after the task comment, include \`@reviewer\` + task ID + exact ask
+4. **Blockers needing human action** → post in blockers channel after the task comment, include **who you need** + task ID + concrete unblock needed
+5. \`#general\` is for decisions and cross-team coordination only — not task status updates
 
 ## API Quick Reference
 - Heartbeat check: \`GET /heartbeat/${agent}\`
@@ -8675,15 +9065,30 @@ If your heartbeat shows **no active task** and **no next task**:
                     { method: 'GET', path: '/reflections', hint: 'List. Query: author, limit' },
                 ],
             },
+            activity: {
+                description: 'Unified activity timeline',
+                endpoints: [
+                    { method: 'GET', path: '/activity', hint: 'Timeline feed. Query: range (24h|7d), type, agent, limit, after (cursor)' },
+                ],
+            },
             system: {
                 description: 'System health and discovery',
                 endpoints: [
                     { method: 'GET', path: '/health', hint: 'System health + version + stats' },
+                    { method: 'GET', path: '/pulse', compact: true, hint: 'Team pulse snapshot: deploy + board + per-agent doing + reviews. Query: compact' },
                     { method: 'GET', path: '/capabilities', hint: 'This endpoint. Query: category to filter' },
                     { method: 'GET', path: '/me/:agent', compact: true, hint: 'Full dashboard. Use /heartbeat/:agent for polls.' },
                     { method: 'GET', path: '/docs', hint: 'Full API reference (68K chars). Use /capabilities instead when possible.' },
                 ],
             },
+            hosts: {
+                description: 'Multi-host registry and cloud connection',
+                endpoints: [
+                    { method: 'GET', path: '/hosts', compact: true, hint: 'List registered hosts. Query: compact' },
+                    { method: 'GET', path: '/cloud/status', hint: 'Cloud connection state + health summary' },
+                    { method: 'GET', path: '/cloud/events', hint: 'Connection lifecycle event log. Query: limit' },
+                ],
+            },
             manage: {
                 description: 'Remote node management (auth-gated)',
                 endpoints: [
@@ -9120,21 +9525,71 @@ If your heartbeat shows **no active task** and **no next task**:
             return { success: false, error: err.message };
         }
     });
+    // ── Team Pulse ─────────────────────────────────────────────────────
+    app.get('/pulse', async (request) => {
+        const compact = request.query.compact === 'true' || request.query.compact === '1';
+        if (compact) {
+            return generateCompactPulse();
+        }
+        return generatePulse();
+    });
+    // ── Scope Overlap Scanner ──────────────────────────────────────────
+    // POST /scope-overlap — trigger scope overlap scan after a PR merge
+    app.post('/scope-overlap', async (request) => {
+        const { prNumber, prTitle, prBranch, mergedTaskId, repo, mergeCommit, notify } = request.body || {};
+        if (!prNumber || !prTitle || !prBranch) {
+            return { success: false, error: 'Required: prNumber, prTitle, prBranch' };
+        }
+        if (notify !== false) {
+            const result = await scanAndNotify(prNumber, prTitle, prBranch, mergedTaskId, repo, mergeCommit);
+            return { success: true, ...result };
+        }
+        const result = scanScopeOverlap(prNumber, prTitle, prBranch, mergedTaskId, repo);
+        return { success: true, ...result };
+    });
+    // ── Team Focus ─────────────────────────────────────────────────────
+    // GET /focus — current team focus directive
+    app.get('/focus', async () => {
+        const focus = getFocus();
+        return focus ? { focus } : { focus: null, message: 'No focus set. Use POST /focus to set one.' };
+    });
+    // POST /focus — set team focus directive
+    app.post('/focus', async (request) => {
+        const { directive, setBy, expiresAt, tags } = request.body || {};
+        if (!directive || !setBy) {
+            return { success: false, error: 'Required: directive, setBy' };
+        }
+        const focus = setFocus(directive, setBy, { expiresAt, tags });
+        return { success: true, focus };
+    });
+    // DELETE /focus — clear team focus
+    app.delete('/focus', async () => {
+        clearFocus();
+        return { success: true, message: 'Focus cleared' };
+    });
     // Get all agent presences
     app.get('/presence', async () => {
         const explicitPresences = presenceManager.getAllPresence();
         const allActivity = presenceManager.getAllActivity();
-        // Build map of explicit presence by agent
-        const presenceMap = new Map(explicitPresences.map(p => [p.agent, p]));
-        // Add inferred presence for agents with only activity
+        // Filter to agents known to this node's TEAM-ROLES registry
+        const knownAgentNames = new Set(getAgentRoles().map(r => r.name.toLowerCase()));
+        // Build map of explicit presence by agent (filtered to registry)
+        const presenceMap = new Map(explicitPresences
+            .filter(p => knownAgentNames.size === 0 || knownAgentNames.has(p.agent.toLowerCase()))
+            .map(p => [p.agent, p]));
+        // Add inferred presence for agents with only activity (registry-gated)
         const now = Date.now();
         for (const activity of allActivity) {
-            if (!presenceMap.has(activity.agent) && activity.last_active) {
+            if (!presenceMap.has(activity.agent) && activity.last_active
+                && (knownAgentNames.size === 0 || knownAgentNames.has(activity.agent.toLowerCase()))) {
                 const inactiveMs = now - activity.last_active;
                 let status = 'offline';
-                if (inactiveMs < 10 * 60 * 1000) { // Active in last 10 minutes
+                if (inactiveMs < 15 * 60 * 1000) { // Active in last 15 minutes — match presence.ts IDLE_THRESHOLD_MS
                     status = activity.tasks_completed_today > 0 ? 'working' : 'idle';
                 }
+                else if (inactiveMs < 30 * 60 * 1000) { // 15-30 min — idle grace period before offline
+                    status = 'idle';
+                }
                 presenceMap.set(activity.agent, {
                     agent: activity.agent,
                     status,
@@ -9180,11 +9635,14 @@ If your heartbeat shows **no active task** and **no next task**:
             if (activity && activity.last_active) {
                 const now = Date.now();
                 const inactiveMs = now - activity.last_active;
-                // Infer status based on recent activity
+                // Infer status based on recent activity — match presence.ts thresholds
                 let status = 'offline';
-                if (inactiveMs < 10 * 60 * 1000) { // Active in last 10 minutes
+                if (inactiveMs < 15 * 60 * 1000) { // Active in last 15 minutes
                     status = activity.tasks_completed_today > 0 ? 'working' : 'idle';
                 }
+                else if (inactiveMs < 30 * 60 * 1000) { // 15-30 min idle grace
+                    status = 'idle';
+                }
                 presence = {
                     agent: request.params.agent,
                     status,
@@ -9288,21 +9746,7 @@ If your heartbeat shows **no active task** and **no next task**:
         }
     });
     // ============ ACTIVITY FEED ENDPOINT ============
-    // Get recent activity across all systems
-    app.get('/activity', async (request, reply) => {
-        const query = request.query;
-        const events = eventBus.getEvents({
-            agent: query.agent,
-            limit: boundedLimit(query.limit, DEFAULT_LIMITS.activity, MAX_LIMITS.activity),
-            since: parseEpochMs(query.since),
-        });
-        const payload = { events, count: events.length };
-        const lastModified = events.length > 0 ? Math.max(...events.map(e => e.timestamp || 0)) : undefined;
-        if (applyConditionalCaching(request, reply, payload, lastModified)) {
-            return;
-        }
-        return payload;
-    });
+    // Legacy activity endpoint replaced by unified /activity timeline (see above)
     // ============ SECRET VAULT ENDPOINTS ============
     // List secrets (metadata only — no plaintext)
     app.get('/secrets', async () => {
@@ -9505,15 +9949,17 @@ If your heartbeat shows **no active task** and **no next task**:
      * GET /activation/funnel — per-user funnel state + aggregate summary.
      * Query params:
      *   ?userId=xxx — get single user's funnel state
-     *   (no params) — get aggregate summary across all users
+     *   ?raw=true   — include internal/infrastructure users (for debugging)
+     *   (no params) — get aggregate summary across all users (clean, external only)
      */
     app.get('/activation/funnel', async (request) => {
         const query = request.query;
         const userId = query.userId;
+        const raw = query.raw === 'true';
         if (userId) {
             return { funnel: getUserFunnelState(userId) };
         }
-        return { funnel: getFunnelSummary() };
+        return { funnel: getFunnelSummary({ raw }) };
     });
     /**
      * POST /activation/event — manually emit an activation event.
@@ -9550,14 +9996,17 @@ If your heartbeat shows **no active task** and **no next task**:
     app.get('/activation/dashboard', async (request) => {
         const query = request.query;
         const weeks = query.weeks ? parseInt(query.weeks, 10) : 12;
-        return { success: true, dashboard: getOnboardingDashboard({ weeks }) };
+        const raw = query.raw === 'true';
+        return { success: true, dashboard: getOnboardingDashboard({ weeks, raw }) };
     });
     /**
      * GET /activation/funnel/conversions — Step-by-step conversion rates.
      * Returns per-step reach count, conversion rate, and median step time.
      */
-    app.get('/activation/funnel/conversions', async () => {
-        return { success: true, conversions: getConversionFunnel() };
+    app.get('/activation/funnel/conversions', async (request) => {
+        const query = request.query;
+        const raw = query.raw === 'true';
+        return { success: true, conversions: getConversionFunnel({ raw }) };
     });
     /**
      * GET /activation/funnel/failures — Failure-reason distribution per step.
@@ -9803,10 +10252,10 @@ If your heartbeat shows **no active task** and **no next task**:
                 };
             }
             const publication = await contentManager.logPublication(body);
-            // Update presence: publishing content = working
+            // Touch presence: publishing content proves agent is alive
             if (body.publishedBy) {
                 presenceManager.recordActivity(body.publishedBy, 'message');
-                presenceManager.updatePresence(body.publishedBy, 'working');
+                presenceManager.touchPresence(body.publishedBy);
             }
             return { success: true, publication };
         }
@@ -9850,9 +10299,9 @@ If your heartbeat shows **no active task** and **no next task**:
                 };
             }
             const item = await contentManager.upsertCalendarItem(body);
-            // Update presence when adding content to calendar
+            // Touch presence when adding content to calendar
             if (body.createdBy) {
-                presenceManager.updatePresence(body.createdBy, 'working');
+                presenceManager.touchPresence(body.createdBy);
             }
             return { success: true, item };
         }