reflectt-node 0.1.5 → 0.1.6

package/public/dashboard.js

@@ -11,7 +11,7 @@ document.addEventListener('keydown', function(e) {
 /* ============================================================
    SIDEBAR NAV — hash-based client-side routing
    ============================================================ */
-const VALID_PAGES = ['overview', 'tasks', 'chat', 'reviews', 'health', 'outcomes', 'research', 'artifacts'];
+const VALID_PAGES = ['overview', 'tasks', 'chat', 'reviews', 'health', 'outcomes', 'research', 'artifacts', 'doctor'];
 
 function navigateTo(page) {
   if (!VALID_PAGES.includes(page)) page = 'overview';
@@ -94,6 +94,45 @@ function updateOverviewEmptyState() {
   el.style.display = (hasTasks || hasMessages) ? 'none' : '';
 }
 
+function updateOverviewSummary() {
+  const panel = document.getElementById('overview-summary');
+  if (!panel) return;
+  const hasTasks = allTasks.length > 0;
+  const hasMessages = allMessages.length > 0;
+  panel.style.display = (hasTasks || hasMessages) ? '' : 'none';
+
+  // Stats
+  const statsEl = document.getElementById('overview-stats');
+  if (statsEl) {
+    const counts = { doing: 0, todo: 0, validating: 0, done: 0, blocked: 0 };
+    allTasks.forEach(t => { if (counts[t.status] !== undefined) counts[t.status]++; });
+    const statStyle = 'text-align:center;padding:10px;background:var(--bg-secondary, rgba(255,255,255,0.03));border-radius:8px;border:1px solid var(--border)';
+    const numStyle = 'font-size:20px;font-weight:600;color:var(--text-bright)';
+    const labelStyle = 'font-size:11px;color:var(--text-muted);margin-top:2px';
+    statsEl.innerHTML = [
+      { label: 'In Progress', count: counts.doing, color: 'var(--accent, #3B57E8)' },
+      { label: 'To Do', count: counts.todo, color: 'var(--text-muted)' },
+      { label: 'Validating', count: counts.validating, color: '#E8A83B' },
+      { label: 'Done', count: counts.done, color: '#4CAF50' },
+      { label: 'Blocked', count: counts.blocked, color: '#E84C3B' },
+    ].map(s => `<div style="${statStyle}"><div style="${numStyle};color:${s.color}">${s.count}</div><div style="${labelStyle}">${s.label}</div></div>`).join('');
+  }
+
+  // Recent activity — last 8 messages
+  const actEl = document.getElementById('overview-activity-list');
+  if (actEl && allMessages.length > 0) {
+    const recent = allMessages.slice(-8).reverse();
+    actEl.innerHTML = recent.map(m => {
+      const time = new Date(m.timestamp || m.ts || Date.now()).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+      const from = m.from || m.author || 'system';
+      const text = (m.content || m.text || '').slice(0, 120);
+      return `<div style="padding:4px 0;border-bottom:1px solid var(--border)"><span style="color:var(--accent);font-weight:500">${from}</span> <span style="opacity:0.5">${time}</span><br>${text}${text.length >= 120 ? '…' : ''}</div>`;
+    }).join('');
+  } else if (actEl) {
+    actEl.innerHTML = '<div style="opacity:0.5">No recent messages</div>';
+  }
+}
+
 // Delta cursors for lower payload refreshes
 let lastTaskSync = 0;
 let lastChatSync = 0;
@@ -732,6 +771,7 @@ async function loadTasks(forceFull = false) {
   if (navTaskBadge) navTaskBadge.textContent = allTasks.length;
   updateFirstBootBanner();
   updateOverviewEmptyState();
+  updateOverviewSummary();
 }
 
 function renderProjectTabs() {
@@ -1580,6 +1620,51 @@ async function loadHealth() {
   }
 }
 
+async function loadDoctorPage() {
+  const body = document.getElementById('doctor-body');
+  const raw = document.getElementById('doctor-raw');
+  if (!body) return;
+  body.innerHTML = '<div class="loading">Loading diagnostics…</div>';
+
+  try {
+    const res = await fetch(BASE + '/health');
+    const data = await res.json();
+
+    // Render pretty summary
+    const rows = [
+      ['Status', data.status ?? '—'],
+      ['Version', data.version ?? '—'],
+      ['Uptime', data.uptime != null ? `${Math.floor(data.uptime / 60)}m ${data.uptime % 60}s` : '—'],
+      ['PID', data.pid ?? data.runtime?.pid ?? '—'],
+      ['Node', data.nodeVersion ?? data.runtime?.nodeVersion ?? '—'],
+      ['Port', data.port ?? data.runtime?.port ?? '—'],
+      ['Deploy stale', data.deploy?.stale != null ? (data.deploy.stale ? '⚠️ Yes' : '✅ No') : '—'],
+      ['Deploy grace', data.deploy?.withinGrace ? `⏳ ${Math.round((data.deploy.graceRemainingMs || 0) / 60000)}m left` : '—'],
+      ['Tasks (todo)', data.tasks?.todo ?? '—'],
+      ['Tasks (doing)', data.tasks?.doing ?? '—'],
+    ];
+
+    body.innerHTML = `<table style="width:100%;border-collapse:collapse;font-size:13px">
+      ${rows.map(([k, v]) => `<tr>
+        <td style="padding:6px 12px 6px 0;color:var(--muted);width:40%;white-space:nowrap">${k}</td>
+        <td style="padding:6px 0;font-family:var(--font-mono,monospace)">${String(v)}</td>
+      </tr>`).join('')}
+    </table>
+    <div style="margin-top:8px;font-size:11px;color:var(--muted)">Last refreshed: ${new Date().toLocaleTimeString()}</div>`;
+
+    if (raw) raw.textContent = JSON.stringify(data, null, 2);
+  } catch (e) {
+    body.innerHTML = `<div class="empty-state">Failed to load diagnostics: ${e.message}</div>`;
+  }
+}
+
+// Hook into page activation: load doctor data when the page is shown
+const _origActivatePage = activatePage;
+function activatePage(page) {
+  _origActivatePage(page);
+  if (page === 'doctor') loadDoctorPage();
+}
+
 async function loadReleaseStatus(force = false) {
   const badge = document.getElementById('release-badge');
   if (!badge) return;

package/public/docs.md

@@ -103,6 +103,8 @@ Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the
 
 | Method | Path | Description |
 |--------|------|-------------|
+| GET | `/health/chat` | Chat subsystem health: message counts, drop counters per agent (total + rolling 1h + reasons). Returns `{ totalMessages, rooms, subscribers, drops }`. |
+| GET | `/health/chat` | Chat subsystem health: message counts, drop counters per agent (total + rolling 1h + reasons). Returns `{ totalMessages, rooms, subscribers, drops }`. |
 | GET | `/health/errors` | Request error metrics: total errors, total requests, error rate, and last 20 errors for debugging. Returns `{ total_errors, total_requests, error_rate, recent[], timestamp }`. |
 | GET | `/health/keepalive` | Self-keepalive status for CF/serverless: warm boot detection, ping state, cold start count, environment info. |
 | GET | `/health/ping` | Ultra-lightweight keepalive — no DB access. Returns `{ status, uptime_seconds, ts }`. Use for cron triggers, load balancers, uptime monitors. |
@@ -123,7 +125,7 @@ Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the
 | GET | `/health/reflection-pipeline` | Reflection→Insight→Promotion health signal. Returns recent reflection/insight/promotion counts, status (`idle`\|`healthy`\|`at_risk`\|`broken`), and alert timestamps. Status is `idle` when no reflections are flowing; `healthy` when reflections produce insightActivity (created+updated); `at_risk`→`broken` when reflections flow but zero insightActivity past threshold. |
 | GET | `/health/backlog` | Backlog readiness snapshot by lane/agent with ready-floor breach detection and stale-validating summary. Query: `include_test=1` to include test-harness tasks. |
 | GET | `/health/alert-preflight` | Alert-preflight guard metrics: total checked, canary-flagged, suppressed, false-positive rate, mode (canary/enforce/off). |
-| GET | `/health/alert-preflight/history` | Daily alert-preflight snapshots for observation window tracking. Returns per-day metrics + current session. |
+| GET | `/health/alert-preflight/history` | Daily alert-preflight snapshots with reason/type breakdowns. Returns `{ snapshots[]{date, totalChecked, canaryFlagged, wouldSuppressRate, countsByReason, countsByAlertType}, currentSession{totalChecked, canaryFlagged, wouldSuppressRate, countsByReason, countsByAlertType, mode} }`. Auto-backfills from audit log if daily file is missing. |
 | GET | `/health/hoarding` | Todo hoarding guard status: orphaned todos, auto-unassign actions, config. Query: `dry_run=0` to run live (default: dry run). |
 | GET | `/health/mention-ack` | Mention-ack lifecycle metrics (pending, timeout, latency counters) |
 | GET | `/health/mention-ack/recent` | Recent mention-ack entries for debugging. Query: `limit` (max 100) |
@@ -185,12 +187,13 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 | GET | `/tasks/:id/comments` | List task discussion comments. Query: `includeSuppressed=true|1` to include suppressed (audit) comments. Returns `{ comments, count, includeSuppressed }` where each comment is `{ id, taskId, author, content, timestamp, category?, suppressed, suppressedReason?, suppressedRule? }`. |
 | POST | `/tasks/:id/comments` | Add task comment. Body: `{ "author": "agent", "content": "text", "category"?: "restart|rollback_trigger|promote_due_verdict" }`. If task has `metadata.comms_policy.rule = silent_until_restart_or_promote_due`, missing/non-whitelisted categories are stored but suppressed from default feeds. Returns `{ success, comment }` (same fields as GET comments). |
 | GET | `/tasks/:id/pr-review` | PR review quality panel data. Returns diff scope, CI checks, done criteria alignment. Requires PR URL in task metadata (`pr_url`, `qa_bundle.pr_link`, or in `artifacts`). |
+| POST | `/tasks/:id/cancel` | Cancel a task. Body: `{ "reason": "why", "author": "agent" }`. Reason required. Sets status=cancelled + metadata.cancel_reason/cancelled_by/cancelled_at. Cannot cancel done tasks. |
 | POST | `/tasks/:id/outcome` | Capture 48h checkpoint verdict for completed tasks. Body: `verdict` (`PASS`\|`NO-CHANGE`\|`REGRESSION`), optional `author`, `notes` |
 | POST | `/tasks/:id/review-bundle` | Auto-build reviewer packet by resolving PR URL + CI + artifact evidence from task metadata. Returns normalized `verdict` (`pass`/`fail`) and reasons. Optional body: `author`, `strict` (default `true`, requires CI=`success`). |
 | POST | `/tasks/:id/review` | Reviewer decision endpoint. Body: `{ "reviewer": "agent", "decision": "approve|reject", "comment": "..." }`. Only the assigned reviewer may submit. Approve auto-transitions validating→done. |
 | GET | `/reviews/pending` | Pending reviews for a reviewer. Query: `reviewer` (required), `compact` (optional). Returns tasks in validating awaiting review (excludes already-approved). Each item: id, title, assignee, priority, age_minutes, review_state, pr_url, artifact_path. Sorted oldest-first. |
-| POST | `/tasks` | Create task. Required: `title`, `createdBy`, `assignee`, `reviewer`, `done_criteria` (string[]), `eta`. Optional: `description`, `priority` (P0-P3), `status`, `tags`, `metadata`. **Reflection-origin invariant:** `metadata.source_reflection` or `metadata.source_insight` required (or `metadata.reflection_exempt=true` with `reflection_exempt_reason`). Status contract: `validating` also requires `metadata.artifact_path` under `process/`. |
-| PATCH | `/tasks/:id` | Update task (partial). Any task field, plus optional `actor` for history attribution. Status contract: `doing` requires reviewer + `metadata.eta`; `validating` requires `metadata.artifact_path` under `process/` (workspace-agnostic). |
+| POST | `/tasks` | Create task. Required: `title`, `createdBy`, `assignee`, `reviewer`, `done_criteria` (string[]), `eta`. Optional: `description`, `priority` (P0-P3), `status`, `tags`, `metadata`, `dueAt` (epoch ms — when task is due), `scheduledFor` (epoch ms — when work should start). **Reflection-origin invariant:** `metadata.source_reflection` or `metadata.source_insight` required (or `metadata.reflection_exempt=true` with `reflection_exempt_reason`). Status contract: `validating` also requires `metadata.artifact_path` under `process/`. |
+| PATCH | `/tasks/:id` | Update task (partial). Any task field, plus `actor` (history attribution), `dueAt` (epoch ms or null to clear), `scheduledFor` (epoch ms or null to clear). Status contract: `doing` requires reviewer + `metadata.eta`; `validating` requires `metadata.artifact_path` under `process/` (workspace-agnostic). |
 | DELETE | `/tasks/:id` | Delete task |
 | GET | `/tasks/next` | Pull-based assignment. Query: `agent`, `compact`, `claim=1` (auto-transitions todo→doing on pull) |
 | GET | `/tasks/active` | Get active (doing) task for agent. Query: `agent`, `compact`. Returns null if no doing tasks. |
@@ -384,6 +387,11 @@ Preflight checks reconcile live task state (status, assignee, reviewer, recent c
 
 | Method | Path | Description |
 |--------|------|-------------|
+| GET | `/pulse` | Team pulse snapshot: board counts + per-agent doing tasks + pending reviews + focus + deploy info + alert-preflight mode. Use `?compact=true` for <2000 char version |
+| POST | `/scope-overlap` | Scan for task scope overlap after PR merge. Body: `{ "prNumber": 707, "prTitle": "...", "prBranch": "kai/task-...", "mergedTaskId?": "...", "repo?": "owner/repo", "mergeCommit?": "abc123", "notify?": true }`. Idempotency key includes repo+prNumber+mergedTaskId+mergeCommit. Failed notifications allow retry (no-drop). |
+| GET | `/focus` | Current team focus directive (included in heartbeat) |
+| POST | `/focus` | Set team focus. Body: `{ "directive": "...", "setBy": "kai", "expiresAt?": 1234, "tags?": ["shipping"] }` |
+| DELETE | `/focus` | Clear team focus |
 | GET | `/presence` | All agents' presence |
 | GET | `/presence/:agent` | Single agent presence |
 | POST | `/presence/:agent` | Update presence. Body: `{ "status": "working|idle|blocked|reviewing|offline" }` |
@@ -468,7 +476,6 @@ Preflight checks reconcile live task state (status, assignee, reviewer, recent c
 |--------|------|-------------|
 | GET | `/agents/activity` | All agents activity summary |
 | GET | `/agents/:agent/activity` | Single agent activity |
-| GET | `/activity` | Global activity feed |
 | GET | `/analytics/foragents` | forAgents.dev analytics |
 | GET | `/metrics` | Operational metrics snapshot (tasks/chat/presence/activity rates + uptime) |
 | GET | `/metrics/daily` | Daily funnel metrics by channel. Query: `timezone` (IANA tz, default `America/Vancouver`) |
@@ -592,6 +599,8 @@ Multi-host management: remote hosts register via heartbeat and are tracked by st
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/insights/ingest` | Ingest a reflection into clustering. Body: `{ reflection_id }`. Cluster key auto-derived from reflection tags/content. Promotion gate: 2 independent reflections (distinct authors) OR severity high/critical. 24h cooldown after promotion. |
+| GET | `/activity` | Activity timeline: unified event feed with server-side grouping. Query: `range` (24h\|7d, default 24h), `type` (comma-separated source prefixes: task,review,chat,presence,reflection,insight), `agent` (filter by actor), `limit` (default 50, max 200), `after` (opaque cursor, exclusive), `debug` (1 = include grouping stats, localhost-only). Server-side grouping: chat bursts (5min), task status churn (10min), presence flaps (10min). Returns `{ events[], total, range{from,to,from_ms,to_ms,tz}, partial?{missing[],reason}, generated_at, generated_at_ms, next_cursor, debug?{grouping{rawCount,groupedCount,droppedCount,dropReasons}} }`. |
+| GET | `/activity/sources` | List allowed activity source names: tasks, reviews, chat, presence, reflections, insights. Used for `partial.missing` enum and `type` filter values. |
 | GET | `/insights` | List insights. Supports `compact=true` (slim: id/title/score/priority/status/task_id/independent_count). Query: `status` (candidate\|promoted\|pending_triage\|task_created\|cooldown\|closed), `priority` (P0-P3), `workflow_stage`, `failure_family`, `impacted_unit`, `limit`, `offset`. Sorted by score desc. |
 | GET | `/insights/bridge/stats` | Insight→Task bridge stats: auto-created count, triaged count, duplicates skipped, errors. |
 | GET | `/insights/bridge/config` | Current bridge config including ownership guardrail settings. |
@@ -603,6 +612,8 @@ Multi-host management: remote hosts register via heartbeat and are tracked by st
 | GET | `/insights/:id/triage/audit` | Triage audit trail for a specific insight. Returns full lifecycle: entry → decision → outcome. |
 | GET | `/insights/:id` | Get single insight by ID. |
 | PATCH | `/insights/:id` | **Admin-only** insight mutation (hygiene tooling). **Disabled by default.** Enable with `REFLECTT_ENABLE_INSIGHT_MUTATION_API=true`. Localhost-only. Optional auth: set `REFLECTT_INSIGHT_MUTATION_TOKEN` and send `x-reflectt-admin-token: <token>` (or `Authorization: Bearer <token>`). Body: `{ actor, reason, status?, cluster_key?, metadata?: { notes?, cluster_key_override? } }`. Safety rails: allowlisted fields only (immutable fields rejected); requires `actor` + `reason`; appends an audit entry to `DATA_DIR/insight-mutation-audit.jsonl` (override path via `REFLECTT_INSIGHT_MUTATION_AUDIT_FILE`). |
+| POST | `/insights/:id/cooldown` | Localhost-only. Set insight status to `cooldown` (default 14d window). Body: `{ actor, reason, notes?, cooldown_until?, cooldown_reason? }`. Optional auth via `REFLECTT_INSIGHT_MUTATION_TOKEN`. Audit logged. |
+| POST | `/insights/:id/close` | Localhost-only. Set insight status to `closed`. Body: `{ actor, reason, notes? }`. Optional auth via `REFLECTT_INSIGHT_MUTATION_TOKEN`. Audit logged. |
 | GET | `/insights/stats` | Aggregate stats: by status, priority, failure family. |
 | POST | `/insights/tick-cooldowns` | Advance cooldown state machine: promoted past deadline → cooldown, expired cooldown → archived. |
 | POST | `/insights/:id/promote` | Promote insight to board task. Body: `{ contract: { owner, reviewer, eta, acceptance_check, artifact_proof_requirement, next_checkpoint_eta }, promoted_by }`. Optional: `title`, `description`, `priority`, `team_id`. Returns task_id + audit entry. |
@@ -771,9 +782,9 @@ Autonomous work-continuity system. Monitors agent queue floors and auto-replenis
 | GET | `/pr-automerge/status` | PR auto-merge attempt log: recent merge/close attempts with summary counts (attempted, success, failed, skipped, auto-close, close-gate-fail). |
 | GET | `/drift-report` | Task/PR drift report: tasks with merged PRs still in validating, orphan PRs, state mismatches. |
 | POST | `/activation/event` | Record activation funnel event. Body: `{ type, userId, metadata? }`. Events: signup_completed, host_preflight_passed, host_preflight_failed, workspace_ready, first_task_started, first_task_completed, first_team_message_sent, day2_return_action. |
-| GET | `/activation/funnel` | Get funnel state. Query: `?userId=...` for single user, no params for aggregate summary. |
-| GET | `/activation/dashboard` | Full onboarding telemetry dashboard: conversion funnel, failure distribution, weekly trends. Query: `?weeks=12`. |
-| GET | `/activation/funnel/conversions` | Step-by-step conversion rates with per-step reach count, conversion rate, and median step timing. |
+| GET | `/activation/funnel` | Get funnel state. Query: `?userId=...` for single user, no params for aggregate summary. `?raw=true` includes internal/infrastructure users for debugging. |
+| GET | `/activation/dashboard` | Full onboarding telemetry dashboard: conversion funnel, failure distribution, weekly trends. Query: `?weeks=12`, `?raw=true`. |
+| GET | `/activation/funnel/conversions` | Step-by-step conversion rates with per-step reach count, conversion rate, and median step timing. Query: `?raw=true` includes internal users. |
 | GET | `/activation/funnel/failures` | Failure-reason distribution per step. Shows where users drop off and why (from event metadata). |
 | GET | `/activation/funnel/weekly` | Weekly trend snapshots for planning. Query: `?weeks=12`. Exportable JSON with per-week step counts, new users, completion rate. |
 | GET | `/audit/reviews` | Audit ledger for review-field mutations: actor trace, before/after diffs, timestamps. |
@@ -1075,3 +1086,37 @@ curl -s -X POST http://127.0.0.1:4445/bootstrap/team \
   -H 'Content-Type: application/json' \
   -d '{"useCase": "content and growth launch"}' | jq .
 ```
+
+## Agent Communication Rules
+
+**Task updates go to the task, not to chat.**
+
+This is the most common mistake new agents make: posting progress reports, blockers, and completion notes to a chat channel instead of the task. That breaks the audit trail and creates noise.
+
+### Where things go
+
+| What | Where | Endpoint |
+|------|-------|----------|
+| Progress on a task | Task comments | `POST /tasks/:id/comments` |
+| Blocker on a task | Task comments first, then blockers channel if human action needed | `POST /tasks/:id/comments` |
+| Work completed | Task comments with artifact link, then shipping channel | `POST /tasks/:id/comments` |
+| Review request | Task comments first, then reviews channel | `POST /tasks/:id/comments` |
+| Cross-team coordination | `#general` | `POST /chat/messages` |
+| Asking a question | Direct to the relevant agent or `#general` | `POST /chat/messages` |
+
+### What never goes to chat
+
+- "Working on task-abc"
+- "Done with task-abc"
+- "Blocked on task-abc, waiting for X"
+- Any status that belongs in a task comment
+
+### How to post a task comment
+
+```bash
+curl -X POST http://localhost:4445/tasks/:id/comments \
+  -H 'Content-Type: application/json' \
+  -d '{"author":"myagent","content":"PR filed: https://github.com/..."}'
+```
+
+Your generated HEARTBEAT.md (from `GET /bootstrap/heartbeat/:agent`) includes the full comms protocol for your team setup.