reflectt-node 0.1.7 → 0.1.8

package/dist/server.js

@@ -53,7 +53,7 @@ import { autoPopulateCloseGate, tryAutoCloseTask, getMergeAttemptLog } from './p
 import { getDuplicateClosureCanonicalRefError } from './duplicateClosureGuard.js';
 import { recordReviewMutation, diffReviewFields, getAuditEntries, loadAuditLedger } from './auditLedger.js';
 import { listSharedFiles, readSharedFile, resolveTaskArtifact } from './shared-workspace-api.js';
-import { normalizeTaskArtifactPaths, buildGitHubBlobUrl, buildGitHubRawUrl } from './artifact-resolver.js';
+import { normalizeArtifactPath, normalizeTaskArtifactPaths, buildGitHubBlobUrl, buildGitHubRawUrl } from './artifact-resolver.js';
 import { emitActivationEvent, getUserFunnelState, getFunnelSummary, hasCompletedEvent, isDay2Eligible, loadActivationFunnel, getConversionFunnel, getFailureDistribution, getWeeklyTrends, getOnboardingDashboard, } from './activationEvents.js';
 import { alertUnauthorizedApproval, alertFlipAttempt, getMutationAlertStatus, pruneOldAttempts } from './mutationAlert.js';
 import { mentionAckTracker } from './mention-ack.js';
@@ -71,7 +71,7 @@ import { getBuildInfo } from './buildInfo.js';
 import { appendStoredLog, readStoredLogs, getStoredLogPath } from './logStore.js';
 import { getAgentRoles, getAgentRolesSource, loadAgentRoles, startConfigWatch, suggestAssignee, suggestReviewer, checkWipCap, saveAgentRoles, scoreAssignment, getAgentRole, getAgentAliases, setAgentDisplayName, resolveAgentMention } from './assignment.js';
 import { initTelemetry, trackRequest as trackTelemetryRequest, trackError as trackTelemetryError, trackTaskEvent, getSnapshot as getTelemetrySnapshot, getTelemetryConfig } from './telemetry.js';
-import { recordUsage, recordUsageBatch, getUsageSummary, getUsageByAgent, getUsageByModel, getUsageByTask, setCap, listCaps, deleteCap, checkCaps, getRoutingSuggestions, estimateCost, ensureUsageTables } from './usage-tracking.js';
+import { recordUsage, recordUsageBatch, getUsageSummary, getUsageByAgent, getUsageByModel, getUsageByTask, getDailySpendByModel, getAvgCostByLane, getAvgCostByAgent, setCap, listCaps, deleteCap, checkCaps, getRoutingSuggestions, estimateCost, ensureUsageTables } from './usage-tracking.js';
 import { getTeamConfigHealth } from './team-config.js';
 import { SecretVault } from './secrets.js';
 import { initGitHubActorAuth, resolveGitHubTokenForActor } from './github-actor-auth.js';
@@ -80,6 +80,7 @@ import { computeCiFromCheckRuns, computeCiFromCombinedStatus } from './github-ci
 import { createGitHubIdentityProvider } from './github-identity.js';
 import { getProvisioningManager } from './provisioning.js';
 import { getWebhookDeliveryManager } from './webhooks.js';
+import { enrichWebhookPayload } from './github-webhook-attribution.js';
 import { exportBundle, importBundle } from './portability.js';
 import { getNotificationManager } from './notifications.js';
 import { getConnectivityManager } from './connectivity.js';
@@ -115,7 +116,9 @@ import { getRoutingApprovalQueue, getRoutingSuggestion, buildApprovalPatch, buil
 import { calendarManager } from './calendar.js';
 import { calendarEvents } from './calendar-events.js';
 import { startReminderEngine, stopReminderEngine, getReminderEngineStats } from './calendar-reminder-engine.js';
+import { startDeployMonitor, stopDeployMonitor } from './deploy-monitor.js';
 import { exportICS, exportEventICS, importICS } from './calendar-ical.js';
+import { createScheduleEntry, getScheduleEntry, updateScheduleEntry, deleteScheduleEntry, getScheduleFeed } from './schedule.js';
 import { createDoc, getDoc, listDocs, updateDoc, deleteDoc } from './knowledge-docs.js';
 import { onTaskShipped, onDecisionComment, isDecisionComment } from './knowledge-auto-index.js';
 import { upsertHostHeartbeat, getHost, listHosts, removeHost } from './host-registry.js';
@@ -426,6 +429,9 @@ const QaBundleSchema = z.object({
 });
 const ReviewHandoffSchema = z.object({
     task_id: z.string().trim().regex(/^task-[a-zA-Z0-9-]+$/),
+    // Stored transactionally (server-side) from POST /tasks/:id/comments.
+    // This must always resolve via GET /tasks/:id/comments.
+    comment_id: z.string().trim().regex(/^tcomment-\d+-[a-z0-9]+$/i).optional(),
     repo: z.string().trim().min(1).optional(), // optional for config_only tasks
     artifact_path: z.string().trim().min(1), // relaxed: accepts any path (process/, ~/.reflectt/, etc.)
     test_proof: z.string().trim().min(1).optional(), // optional for non-code tasks
@@ -621,6 +627,29 @@ function enforceQaBundleGateForValidating(status, metadata, expectedTaskId) {
             hint: 'Use the same canonical process/... artifact path in both fields.',
         };
     }
+    // Canonical artifact reference (until central storage exists):
+    // For code tasks, artifact paths must be repo-relative under process/ (or a URL).
+    if (reviewPacket && !nonCodeLane) {
+        const packetArtifact = typeof reviewPacket.artifact_path === 'string' ? reviewPacket.artifact_path.trim() : '';
+        const packetIsUrl = /^https?:\/\//i.test(packetArtifact);
+        const packetIsProcess = packetArtifact.startsWith('process/');
+        if (packetArtifact && !packetIsUrl && !packetIsProcess) {
+            return {
+                ok: false,
+                error: 'Validating gate: metadata.qa_bundle.review_packet.artifact_path must be under process/ (repo-relative) or a URL',
+                hint: 'Set review_packet.artifact_path to process/TASK-...md (committed in the PR) or a PR/GitHub URL.',
+            };
+        }
+        const metaIsUrl = /^https?:\/\//i.test(artifactPath);
+        const metaIsProcess = artifactPath.startsWith('process/');
+        if (artifactPath && !metaIsUrl && !metaIsProcess) {
+            return {
+                ok: false,
+                error: 'Validating gate: metadata.artifact_path must be under process/ (repo-relative) or a URL',
+                hint: 'Set metadata.artifact_path to process/TASK-...md (committed in the PR) or a PR/GitHub URL.',
+            };
+        }
+    }
     // PR integrity: validate commit SHA + changed_files against live PR head
     if (!nonCodeLane && reviewPacket?.pr_url) {
         const overrideFlag = metadataObj.pr_integrity_override === true;
@@ -742,6 +771,40 @@ function applyReviewStateMetadata(existing, parsed, mergedMeta, now) {
             };
             console.log(`[ArtifactNormalize] task ${existing.id}: normalized`, normResult.warnings);
         }
+        // ── Review handoff comment pointer repair/fill ──
+        // If review_handoff exists, ensure comment_id points to a real comment.
+        // We do this *server-side* to avoid phantom/unresolvable pointers.
+        const rh = metadata.review_handoff;
+        if (rh && typeof rh === 'object' && !Array.isArray(rh)) {
+            const rhAny = rh;
+            const commentId = typeof rhAny.comment_id === 'string' ? rhAny.comment_id.trim() : '';
+            const all = taskManager.getTaskComments(existing.id, { includeSuppressed: true });
+            const resolves = commentId ? all.some(c => c.id === commentId) : false;
+            if (!resolves) {
+                // Prefer an explicit category tag; fallback to most recent comment by assignee.
+                const assignee = (existing.assignee || '').trim().toLowerCase();
+                const byHandoffCategory = all
+                    .filter(c => {
+                    const cat = String(c.category || '').toLowerCase();
+                    return cat === 'review_handoff' || cat === 'handoff';
+                });
+                const byAssignee = assignee
+                    ? all.filter(c => String(c.author || '').trim().toLowerCase() === assignee)
+                    : [];
+                const candidate = (byHandoffCategory.length > 0
+                    ? byHandoffCategory[byHandoffCategory.length - 1]
+                    : (byAssignee.length > 0 ? byAssignee[byAssignee.length - 1] : (all.length > 0 ? all[all.length - 1] : null)));
+                if (candidate) {
+                    metadata.review_handoff = { ...rhAny, comment_id: candidate.id };
+                    metadata.review_handoff_comment_id_autofilled = {
+                        previous: commentId || null,
+                        next: candidate.id,
+                        at: now,
+                        strategy: byHandoffCategory.length > 0 ? 'category:review_handoff' : (byAssignee.length > 0 ? 'latest_assignee_comment' : 'latest_comment'),
+                    };
+                }
+            }
+        }
     }
     if (previousStatus === 'validating' && nextStatus === 'doing' && !incomingReviewState) {
         metadata.review_state = 'needs_author';
@@ -859,7 +922,13 @@ function isEchoOutOfLaneTask(task) {
     // For Echo, anything classified outside content/docs voice lane gets flagged unless reassigned.
     return true;
 }
-function enforceReviewHandoffGateForValidating(status, taskId, metadata) {
+const reviewHandoffValidationStats = {
+    failures: 0,
+    lastFailureAt: 0,
+    lastFailureTaskId: '',
+    lastFailureError: '',
+};
+async function enforceReviewHandoffGateForValidating(status, taskId, metadata) {
     if (status !== 'validating')
         return { ok: true };
     if (isTaskAutomatedRecurring(metadata))
@@ -874,7 +943,7 @@ function enforceReviewHandoffGateForValidating(status, taskId, metadata) {
         return {
             ok: false,
             error: 'Review handoff required: metadata.review_handoff must include task_id, artifact_path, known_caveats (and pr_url + commit_sha unless doc_only=true, config_only=true, or non_code=true).',
-            hint: 'Example: { "review_handoff": { "task_id":"task-...", "artifact_path":"process/TASK-...md", "known_caveats":"none" } }. For non-code tasks (finance, legal, ops): set non_code=true. For config tasks: set config_only=true.',
+            hint: 'Example: { "review_handoff": { "task_id":"task-...", "artifact_path":"process/TASK-...md", "known_caveats":"none" } }. For non-code tasks: set non_code=true. Recommended: post the handoff comment with category="review_handoff" so the server stamps comment_id automatically.',
         };
     }
     const handoff = parsed.data;
@@ -885,6 +954,38 @@ function enforceReviewHandoffGateForValidating(status, taskId, metadata) {
             hint: 'Set metadata.review_handoff.task_id to the exact task being transitioned.',
         };
     }
+    // Ensure review_handoff.comment_id resolves to a real comment.
+    // If missing (or stale), we repair it from existing comments; if none exist,
+    // we create a server-authored pointer comment so reviewers always have a stable anchor.
+    const commentsAll = taskManager.getTaskComments(taskId, { includeSuppressed: true });
+    let commentId = typeof handoff.comment_id === 'string' ? handoff.comment_id.trim() : '';
+    let handoffComment = commentId ? (commentsAll.find(c => c.id === commentId) || null) : null;
+    if (!handoffComment) {
+        const byCategory = commentsAll.filter(c => {
+            const cat = String(c.category || '').toLowerCase();
+            return cat === 'review_handoff' || cat === 'handoff';
+        });
+        const candidate = byCategory.length > 0
+            ? byCategory[byCategory.length - 1]
+            : (commentsAll.length > 0 ? commentsAll[commentsAll.length - 1] : null);
+        if (candidate) {
+            commentId = candidate.id;
+            handoffComment = candidate;
+        }
+        else {
+            // No comments exist — create a stable anchor comment.
+            const created = await taskManager.addTaskComment(taskId, 'system', 'Auto-handoff: review_handoff is recorded in metadata.review_handoff (no explicit handoff comment was posted).', { category: 'review_handoff', provenance: { kind: 'auto_review_handoff', source: 'validating_gate' } });
+            commentId = created.id;
+            handoffComment = created;
+        }
+        // Persist repaired comment_id into the handoff metadata (server-side).
+        ;
+        handoff.comment_id = commentId;
+        const rhObj = root.review_handoff;
+        if (rhObj && typeof rhObj === 'object' && !Array.isArray(rhObj)) {
+            rhObj.comment_id = commentId;
+        }
+    }
     // config_only: artifacts live in ~/.reflectt/, no repo/PR required
     // doc_only/non_code/design/docs lanes: no PR/commit required
     const nonCodeLane = handoff.non_code === true || isDesignOrDocsLane(root);
@@ -904,7 +1005,43 @@ function enforceReviewHandoffGateForValidating(status, taskId, metadata) {
             };
         }
     }
-    return { ok: true };
+    // Artifact retrievability gate.
+    // If the artifact isn't accessible from this node (repo / shared-workspace / GitHub fallback),
+    // a reviewer on another host will almost certainly be blocked.
+    const artifactPath = typeof handoff.artifact_path === 'string' ? handoff.artifact_path.trim() : '';
+    const norm = normalizeArtifactPath(artifactPath);
+    if (norm.rejected || !norm.normalized) {
+        return {
+            ok: false,
+            error: `Validating gate: review_handoff.artifact_path is not a valid retrievable reference (${norm.rejectReason || 'invalid path'}).`,
+            hint: 'Use either (a) a PR/GitHub URL, or (b) a repo-relative path (e.g. process/TASK-...md) that exists on the referenced PR/commit, or (c) put the full spec in the handoff comment and point artifact_path at a stable URL.',
+        };
+    }
+    // URLs are assumed retrievable.
+    if (/^https?:\/\//i.test(norm.normalized))
+        return { ok: true };
+    // If the file is accessible locally (repo or shared-workspace), accept.
+    const repoRoot = resolve(import.meta.dirname || process.cwd(), '..');
+    const resolved = await resolveTaskArtifact(norm.normalized, repoRoot);
+    if (resolved.accessible)
+        return { ok: true };
+    // GitHub fallback: if PR+commit are known and artifact is process/*, we can build a stable blob URL.
+    const prUrl = root.pr_url || root.qa_bundle?.review_packet?.pr_url || root.review_handoff?.pr_url;
+    const commitSha = root.commit_sha || root.commit || root.qa_bundle?.review_packet?.commit || root.review_handoff?.commit_sha;
+    if (typeof prUrl === 'string' && typeof commitSha === 'string' && norm.normalized.startsWith('process/')) {
+        const blobUrl = buildGitHubBlobUrl(prUrl, commitSha, norm.normalized);
+        if (blobUrl)
+            return { ok: true };
+    }
+    // For non-code tasks, the handoff comment itself is considered the primary artifact.
+    // We only require that comment_id resolves (handled above).
+    if (nonCodeLane)
+        return { ok: true };
+    return {
+        ok: false,
+        error: 'Validating gate: review_handoff.artifact_path is not retrievable from repo/shared-workspace/GitHub fallback.',
+        hint: 'Move the artifact into shared-workspace process/, or reference a PR+commit so GitHub blob fallback can resolve it (process/* only).',
+    };
 }
 const DEFAULT_LIMITS = {
     chatMessages: 50,
@@ -1516,7 +1653,8 @@ export async function createServer() {
     await app.register(fastifyWebsocket);
     // Multipart file uploads (50MB limit)
     const fastifyMultipart = await import('@fastify/multipart');
-    await app.register(fastifyMultipart.default, { limits: { fileSize: 50 * 1024 * 1024 } });
+    const { MAX_SIZE_BYTES: _multipartMax } = await import('./files.js');
+    await app.register(fastifyMultipart.default, { limits: { fileSize: _multipartMax } });
     // Normalize error responses to a consistent envelope
     app.addHook('preSerialization', async (request, reply, payload) => {
         if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
@@ -1561,6 +1699,8 @@ export async function createServer() {
             envelope.gate = body.gate;
         if (body.problems !== undefined)
             envelope.problems = body.problems;
+        if (body.tombstone !== undefined)
+            envelope.tombstone = body.tombstone;
         if (alreadyEnvelope && body.data !== undefined)
             envelope.data = body.data;
         // Minimal persisted error log: enables /logs to return real entries.
@@ -1847,6 +1987,10 @@ export async function createServer() {
     // Board health execution worker — config from policy
     boardHealthWorker.updateConfig(policy.boardHealth);
     boardHealthWorker.start();
+    // Activate noise budget enforcement — the 24h canary period is complete.
+    // Canary mode (log-only) is still the default in case of fresh installs,
+    // but on a running server we want real duplicate suppression.
+    noiseBudgetManager.activateEnforcement();
     // Noise budget: wire digest flush handler to send batched messages to #ops
     noiseBudgetManager.setDigestFlushHandler(async (channel, entries) => {
         if (entries.length === 0)
@@ -1876,6 +2020,8 @@ export async function createServer() {
     startShippedHeartbeat();
     // Calendar reminder engine — polls for pending reminders every 30s
     startReminderEngine();
+    // Deploy monitor — alert within 5m when production deploys fail (Vercel + health URL)
+    startDeployMonitor();
     app.addHook('onClose', async () => {
         clearInterval(idleNudgeTimer);
         clearInterval(cadenceWatchdogTimer);
@@ -1885,6 +2031,7 @@ export async function createServer() {
         stopShippedHeartbeat();
         stopTeamPulse();
         stopReminderEngine();
+        stopDeployMonitor();
         stopKeepalive();
         stopSelfKeepalive();
         wsHeartbeat.stop();
@@ -2703,6 +2850,9 @@ export async function createServer() {
                 reflectionPipeline: { registered: Boolean(reflectionPipelineTimer), lastTickAt: ticks.reflection_pipeline, lastTickAgeSec: ageSec(ticks.reflection_pipeline) },
                 boardHealthWorker: { registered: board.running, lastTickAt: ticks.board_health || board.lastTickAt, lastTickAgeSec: ageSec(ticks.board_health || board.lastTickAt) },
             },
+            reviewHandoffValidation: {
+                ...reviewHandoffValidationStats,
+            },
             reflectionPipelineHealth: {
                 ...reflectionPipelineHealth,
             },
@@ -3037,6 +3187,23 @@ export async function createServer() {
             };
         }
         const data = parsedBody.data;
+        // Reserve system sender for server-internal control-plane messages.
+        // Prevent browser clients (dashboard.js) or external callers from spoofing system alerts.
+        //
+        // Allow explicit internal callers (tests/tools) via header:
+        //   x-reflectt-internal: true
+        if (data.from === 'system') {
+            const internal = String(request.headers['x-reflectt-internal'] || '').toLowerCase() === 'true';
+            if (!internal) {
+                reply.code(403);
+                return {
+                    success: false,
+                    error: 'Sender "system" is reserved (use from="dashboard" or your agent name).',
+                    code: 'SENDER_RESERVED',
+                    hint: 'Only internal callers may emit system messages. Add header x-reflectt-internal:true for test/tooling.',
+                };
+            }
+        }
         // Require at least content or attachments
         if (!data.content && (!data.attachments || data.attachments.length === 0)) {
             reply.code(400);
@@ -4306,6 +4473,24 @@ export async function createServer() {
             };
         }
         if (!resolved.task || !resolved.resolvedId) {
+            // Check if this task was deleted — return 410 Gone with tombstone metadata instead of 404.
+            const tombstone = taskManager.getTaskDeletionTombstone(request.params.id);
+            if (tombstone) {
+                reply.code(410);
+                return {
+                    success: false,
+                    error: 'Task has been deleted',
+                    code: 'TASK_DELETED',
+                    status: 410,
+                    tombstone: {
+                        taskId: tombstone.taskId,
+                        deletedAt: tombstone.deletedAt,
+                        deletedBy: tombstone.deletedBy,
+                        previousStatus: tombstone.previousStatus,
+                        title: tombstone.title,
+                    },
+                };
+            }
             reply.code(404);
             return {
                 error: 'Task not found',
@@ -4987,6 +5172,24 @@ export async function createServer() {
             // fan out inbox-visible notifications to assignee/reviewer + explicit @mentions.
             // Notification routing respects per-agent preferences (quiet hours, mute, filters).
             const task = taskManager.getTask(resolved.resolvedId);
+            // ── Transactional review_handoff.comment_id stamping ──
+            // If the author tags this comment as the handoff entrypoint, the server stamps
+            // metadata.review_handoff.comment_id from the persisted comment ID.
+            // This prevents clients from supplying phantom IDs.
+            const category = typeof data.category === 'string' ? String(data.category).trim().toLowerCase() : '';
+            if (task && (category === 'review_handoff' || category === 'handoff')) {
+                const meta = (task.metadata || {});
+                const rh = meta.review_handoff;
+                if (rh && typeof rh === 'object' && !Array.isArray(rh)) {
+                    const rhAny = rh;
+                    if (rhAny.comment_id !== comment.id) {
+                        taskManager.patchTaskMetadata(task.id, {
+                            review_handoff: { ...rhAny, comment_id: comment.id },
+                            review_handoff_comment_id_stamped_at: Date.now(),
+                        });
+                    }
+                }
+            }
             // Never fan out notifications for test-harness tasks.
             // Our repo contains a few "LIVE server" tests (BASE=127.0.0.1:4445) that create
             // tasks/comments with metadata.is_test=true. Without this guard, running `npm test`
@@ -6106,7 +6309,23 @@ export async function createServer() {
             }
             // Merge incoming metadata with existing for gate checks + persistence.
             // Apply auto-defaults (ETA, artifact_path) when not explicitly provided.
-            const incomingMeta = parsed.metadata || {};
+            // Do not accept caller-supplied review_handoff.comment_id (it must be stamped server-side from POST /tasks/:id/comments).
+            // If a client tries to patch it directly, we strip it to prevent phantom pointers.
+            const incomingMetaRaw = (parsed.metadata || {});
+            const incomingMeta = { ...incomingMetaRaw };
+            const incomingRh = incomingMeta.review_handoff;
+            if (incomingRh && typeof incomingRh === 'object' && !Array.isArray(incomingRh)) {
+                const rhAny = incomingRh;
+                if (typeof rhAny.comment_id === 'string') {
+                    const { comment_id, ...rest } = rhAny;
+                    incomingMeta.review_handoff = rest;
+                    incomingMeta.review_handoff_comment_id_stripped = {
+                        stripped: true,
+                        attempted: comment_id,
+                        at: Date.now(),
+                    };
+                }
+            }
             const effectiveTargetStatus = parsed.status ?? existing.status;
             const autoFilledMeta = applyAutoDefaults(lookup.resolvedId, effectiveTargetStatus, incomingMeta);
             const mergedRawMeta = { ...(existing.metadata || {}), ...autoFilledMeta };
@@ -6285,8 +6504,12 @@ export async function createServer() {
                     hint: qaGate.hint,
                 };
             }
-            const handoffGate = enforceReviewHandoffGateForValidating(effectiveStatus, lookup.resolvedId, mergedMeta);
+            const handoffGate = await enforceReviewHandoffGateForValidating(effectiveStatus, lookup.resolvedId, mergedMeta);
             if (!handoffGate.ok) {
+                reviewHandoffValidationStats.failures += 1;
+                reviewHandoffValidationStats.lastFailureAt = Date.now();
+                reviewHandoffValidationStats.lastFailureTaskId = lookup.resolvedId;
+                reviewHandoffValidationStats.lastFailureError = handoffGate.error;
                 reply.code(400);
                 return {
                     success: false,
@@ -6617,6 +6840,7 @@ export async function createServer() {
                 const prLine = prUrl ? `\nPR: ${prUrl}` : '';
                 chatManager.sendMessage({
                     from: 'system',
+                    to: existing.reviewer,
                     content: `@${existing.reviewer} [reviewRequested:${task.id}] ${task.title} → validating${prLine}`,
                     channel: 'task-notifications',
                     metadata: {
@@ -6726,6 +6950,7 @@ export async function createServer() {
                 const reviewMsg = `@${task.reviewer} review requested: **${task.title}** (${task.id})${prLink}. Please approve or flag issues.`;
                 chatManager.sendMessage({
                     from: 'system',
+                    to: task.reviewer,
                     content: reviewMsg,
                     channel: 'reviews',
                     metadata: {
@@ -6844,6 +7069,7 @@ export async function createServer() {
         const sourceInfo = getAgentRolesSource();
         return { success: true, agents: enriched, config: sourceInfo };
     };
+    app.get('/agents', async () => buildRoleRegistryPayload());
     app.get('/agents/roles', async () => buildRoleRegistryPayload());
     // Team-scoped alias for assignment-engine consumers
     app.get('/team/roles', async () => {
@@ -6860,6 +7086,13 @@ export async function createServer() {
     // ── File upload/download ──
     app.post('/files', async (request, reply) => {
         try {
+            const { MAX_SIZE_BYTES: maxBytes } = await import('./files.js');
+            // Early rejection via Content-Length before reading body
+            const declaredLength = parseInt(String(request.headers['content-length'] || ''), 10);
+            if (!Number.isNaN(declaredLength) && declaredLength > maxBytes) {
+                reply.code(413);
+                return { success: false, error: `File exceeds ${maxBytes / (1024 * 1024)}MB limit (Content-Length: ${declaredLength} bytes)` };
+            }
             const data = await request.file();
             if (!data) {
                 reply.code(400);
@@ -6869,10 +7102,10 @@ export async function createServer() {
             for await (const chunk of data.file)
                 chunks.push(chunk);
             const buffer = Buffer.concat(chunks);
-            // Check if stream was truncated (exceeds limit)
+            // Check if stream was truncated (exceeds multipart limit)
             if (data.file.truncated) {
                 reply.code(413);
-                return { success: false, error: 'File exceeds 50MB limit' };
+                return { success: false, error: `File exceeds ${maxBytes / (1024 * 1024)}MB limit` };
             }
             const fields = data.fields;
             const uploadedBy = typeof fields?.uploadedBy?.value === 'string' ? fields.uploadedBy.value : 'anonymous';
@@ -6894,10 +7127,11 @@ export async function createServer() {
             return result;
         }
         catch (err) {
+            const { MAX_SIZE_BYTES: maxBytes } = await import('./files.js');
             const msg = err instanceof Error ? err.message : String(err);
             if (msg.includes('Request file too large')) {
                 reply.code(413);
-                return { success: false, error: 'File exceeds 50MB limit' };
+                return { success: false, error: `File exceeds ${maxBytes / (1024 * 1024)}MB limit` };
             }
             reply.code(500);
             return { success: false, error: 'Upload failed' };
@@ -7093,6 +7327,137 @@ export async function createServer() {
             return { success: false, error: msg };
         }
     });
+    // POST /agents — Add a single agent to the team
+    app.post('/agents', async (request, reply) => {
+        const body = request.body;
+        const name = typeof body.name === 'string' ? body.name.trim().toLowerCase() : '';
+        const role = typeof body.role === 'string' ? body.role.trim() : '';
+        const description = typeof body.description === 'string' ? body.description.trim() : '';
+        if (!name) {
+            reply.code(400);
+            return { success: false, error: 'name is required' };
+        }
+        if (!role) {
+            reply.code(400);
+            return { success: false, error: 'role is required' };
+        }
+        if (/[^a-z0-9_-]/.test(name)) {
+            reply.code(400);
+            return { success: false, error: 'name must be lowercase alphanumeric (a-z, 0-9, -, _)' };
+        }
+        // Check if agent already exists
+        const existing = getAgentRoles().find(r => r.name === name);
+        if (existing) {
+            reply.code(409);
+            return { success: false, error: `Agent "${name}" already exists (role: ${existing.role})` };
+        }
+        // Read existing YAML and append new agent
+        const { readFileSync, writeFileSync, existsSync } = await import('node:fs');
+        const { join } = await import('node:path');
+        const filePath = join(REFLECTT_HOME, 'TEAM-ROLES.yaml');
+        let yaml = '';
+        if (existsSync(filePath)) {
+            yaml = readFileSync(filePath, 'utf-8');
+        }
+        if (!yaml.includes('agents:')) {
+            yaml = 'agents:\n';
+        }
+        // Build agent YAML entry
+        const affinityTags = Array.isArray(body.affinityTags) ? body.affinityTags : [role];
+        const wipCap = typeof body.wipCap === 'number' ? body.wipCap : 2;
+        const desc = description || `${role} agent.`;
+        const entry = [
+            `  - name: ${name}`,
+            `    role: ${role}`,
+            `    description: ${desc}`,
+            `    affinityTags: [${affinityTags.join(', ')}]`,
+            `    wipCap: ${wipCap}`,
+        ].join('\n');
+        // Insert before lanes: section (if present), otherwise append
+        const lanesIdx = yaml.indexOf('\nlanes:');
+        if (lanesIdx >= 0) {
+            yaml = yaml.slice(0, lanesIdx) + '\n' + entry + yaml.slice(lanesIdx);
+        }
+        else {
+            yaml = yaml.trimEnd() + '\n' + entry + '\n';
+        }
+        try {
+            writeFileSync(filePath, yaml, 'utf-8');
+            const { loadAgentRoles } = await import('./assignment.js');
+            const reloaded = loadAgentRoles();
+            // Scaffold agent workspace if it doesn't exist
+            let workspaceCreated = false;
+            try {
+                const { mkdirSync, existsSync: dirExists } = await import('node:fs');
+                const workspaceDir = join(REFLECTT_HOME, `workspace-${name}`);
+                if (!dirExists(workspaceDir)) {
+                    mkdirSync(workspaceDir, { recursive: true });
+                    writeFileSync(join(workspaceDir, 'SOUL.md'), `# ${name}\n\n*${desc}*\n`, 'utf-8');
+                    writeFileSync(join(workspaceDir, 'AGENTS.md'), `# ${name}\n\nRole: ${role}\n\n${desc}\n`, 'utf-8');
+                    workspaceCreated = true;
+                }
+            }
+            catch (wsErr) {
+                console.warn(`[Agents] Workspace scaffold failed for ${name}:`, wsErr.message);
+            }
+            return {
+                success: true,
+                agent: { name, role, description: desc, wipCap },
+                totalAgents: reloaded.roles.length,
+                workspaceCreated,
+                hint: `Agent "${name}" added to team and hot-reloaded. Start heartbeating: GET /heartbeat/${name}`,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : 'Failed to save agent';
+            reply.code(500);
+            return { success: false, error: msg };
+        }
+    });
+    // DELETE /agents/:name — Remove an agent from the team
+    app.delete('/agents/:name', async (request, reply) => {
+        const name = request.params.name.toLowerCase();
+        const existing = getAgentRoles().find(r => r.name === name);
+        if (!existing) {
+            reply.code(404);
+            return { success: false, error: `Agent "${name}" not found` };
+        }
+        const { readFileSync, writeFileSync } = await import('node:fs');
+        const { join } = await import('node:path');
+        const filePath = join(REFLECTT_HOME, 'TEAM-ROLES.yaml');
+        let yaml = readFileSync(filePath, 'utf-8');
+        // Remove the agent block: from "  - name: <name>" to the next "  - name:" or top-level key or EOF
+        const lines = yaml.split('\n');
+        const filtered = [];
+        let skipping = false;
+        for (const line of lines) {
+            if (line.match(new RegExp(`^\\s+-\\s+name:\\s+${name}\\s*$`))) {
+                skipping = true;
+                continue;
+            }
+            if (skipping) {
+                // Stop skipping at next agent entry, top-level key, or blank line before top-level
+                if (line.match(/^\s+-\s+name:\s/) || line.match(/^[a-z]/)) {
+                    skipping = false;
+                    filtered.push(line);
+                }
+                continue;
+            }
+            filtered.push(line);
+        }
+        yaml = filtered.join('\n');
+        try {
+            writeFileSync(filePath, yaml, 'utf-8');
+            const { loadAgentRoles } = await import('./assignment.js');
+            const reloaded = loadAgentRoles();
+            return { success: true, removed: name, totalAgents: reloaded.roles.length };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : 'Failed to remove agent';
+            reply.code(500);
+            return { success: false, error: msg };
+        }
+    });
     // Resolve a mention string (name, displayName, or alias) to an agent ID
     app.get('/resolve/mention/:mention', async (request) => {
         const agentName = resolveAgentMention(request.params.mention);
@@ -9063,6 +9428,7 @@ If your heartbeat shows **no active task** and **no next task**:
                 endpoints: [
                     { method: 'POST', path: '/reflections', hint: 'Submit. Required: pain, impact, evidence[], went_well, suspected_why, proposed_fix, confidence, role_type, author' },
                     { method: 'GET', path: '/reflections', hint: 'List. Query: author, limit' },
+                    { method: 'GET', path: '/reflections/schema', hint: 'Required/optional fields, role types, severity levels, dedup rules' },
                 ],
             },
             activity: {
@@ -9316,8 +9682,18 @@ If your heartbeat shows **no active task** and **no next task**:
             reply.code(404);
             return { success: false, error: 'Task not found', input: id, suggestions: lookup.suggestions };
         }
-        if (task.assignee) {
-            return { success: false, error: `Task already assigned to ${task.assignee}` };
+        const assignee = String(task.assignee || '').trim();
+        const isUnassigned = assignee.length === 0 || assignee.toLowerCase() === 'unassigned';
+        if (!isUnassigned) {
+            reply.code(409);
+            return {
+                success: false,
+                error: `Task already assigned to ${assignee}`,
+                code: 'TASK_ALREADY_ASSIGNED',
+                status: 409,
+                assignee,
+                hint: 'Task claims are atomic: first claim wins. Pull another task via GET /tasks/next.',
+            };
         }
         const shortId = lookup.resolvedId.replace(/^task-\d+-/, '');
         const branch = `${body.agent}/task-${shortId}`;
@@ -10170,6 +10546,42 @@ If your heartbeat shows **no active task** and **no next task**:
         const q = request.query;
         return { suggestions: getRoutingSuggestions({ since: q.since ? Number(q.since) : undefined }) };
     });
+    // ── Cost Dashboard ──
+    // GET /costs — aggregated spend: daily by model, avg per lane, top tasks
+    app.get('/costs', async (request) => {
+        const q = request.query;
+        const days = q.days ? Math.min(Number(q.days), 90) : 7;
+        const since = Date.now() - days * 24 * 60 * 60 * 1000;
+        const dailyByModel = getDailySpendByModel({ days });
+        const byLane = getAvgCostByLane({ days: Math.max(days, 30) }); // lane data needs more window
+        const byAgent = getAvgCostByAgent({ days: Math.max(days, 30) });
+        const topTasks = getUsageByTask({ since, limit: 20 });
+        const summary = getUsageSummary({ since });
+        // Roll up daily totals per day for the sparkline
+        const dailyTotals = {};
+        for (const row of dailyByModel) {
+            dailyTotals[row.date] = (dailyTotals[row.date] ?? 0) + row.total_cost_usd;
+        }
+        // Note: avg_cost_by_lane and avg_cost_by_agent use Math.max(days, 30) as their window.
+        // Lane/agent-level averages need task density to be meaningful — a 7-day window might
+        // have 0-1 closed tasks per agent/lane and produce misleading numbers. Using a 30-day
+        // floor is intentional. daily_by_model, daily_totals, and top_tasks_by_cost use the
+        // requested `days` window directly and will match the `window_days` field in the response.
+        const laneAgentWindow = Math.max(days, 30);
+        return {
+            window_days: days,
+            lane_agent_window_days: laneAgentWindow,
+            summary: Array.isArray(summary) ? summary[0] ?? null : summary,
+            daily_by_model: dailyByModel,
+            daily_totals: Object.entries(dailyTotals)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([date, total_cost_usd]) => ({ date, total_cost_usd })),
+            avg_cost_by_lane: byLane,
+            avg_cost_by_agent: byAgent,
+            top_tasks_by_cost: topTasks,
+            generated_at: Date.now(),
+        };
+    });
     // Operational metrics endpoint (lightweight dashboard contract)
     app.get('/metrics', async () => {
         const startedAt = Date.now();
@@ -10587,6 +10999,10 @@ If your heartbeat shows **no active task** and **no next task**:
             request.headers['x-request-id'] ||
             undefined;
         const idempotencyKey = deliveryId ? `${provider}_${deliveryId}` : undefined;
+        // Enrich GitHub webhook payloads with agent attribution
+        const enrichedBody = provider === 'github'
+            ? enrichWebhookPayload(body)
+            : body;
         // Enqueue through delivery engine for each configured target
         const events = [];
         for (const route of routes) {
@@ -10597,7 +11013,7 @@ If your heartbeat shows **no active task** and **no next task**:
             const event = webhookDelivery.enqueue({
                 provider,
                 eventType,
-                payload: body,
+                payload: enrichedBody,
                 targetUrl: `http://localhost:${serverConfig.port}${route.path}`,
                 idempotencyKey: idempotencyKey ? `${idempotencyKey}_${route.id}` : undefined,
                 metadata: {
@@ -11344,6 +11760,62 @@ If your heartbeat shows **no active task** and **no next task**:
     app.get('/calendar/reminders/stats', async () => {
         return getReminderEngineStats();
     });
+    // ── Schedule feed — team-wide time-awareness ──────────────────────────────
+    //
+    // Provides canonical records for deploy windows, focus blocks, and
+    // scheduled task work so agents can coordinate timing without chat.
+    //
+    // MVP scope: one-off windows only. No iCal/RRULE, no reminders.
+    // See src/schedule.ts for what is intentionally NOT included.
+    // GET /schedule/feed — upcoming entries in chronological order
+    app.get('/schedule/feed', async (request) => {
+        const q = request.query;
+        const kinds = q.kinds ? q.kinds.split(',') : undefined;
+        const entries = getScheduleFeed({
+            after: q.after ? parseInt(q.after, 10) : undefined,
+            before: q.before ? parseInt(q.before, 10) : undefined,
+            kinds,
+            owner: q.owner,
+            limit: q.limit ? parseInt(q.limit, 10) : undefined,
+        });
+        return { entries, count: entries.length };
+    });
+    // POST /schedule/entries — create a new schedule entry
+    app.post('/schedule/entries', async (request, reply) => {
+        try {
+            const entry = createScheduleEntry(request.body);
+            return reply.status(201).send({ entry });
+        }
+        catch (err) {
+            return reply.status(400).send({ error: err.message });
+        }
+    });
+    // GET /schedule/entries/:id
+    app.get('/schedule/entries/:id', async (request, reply) => {
+        const entry = getScheduleEntry(request.params.id);
+        if (!entry)
+            return reply.status(404).send({ error: 'Not found' });
+        return { entry };
+    });
+    // PATCH /schedule/entries/:id
+    app.patch('/schedule/entries/:id', async (request, reply) => {
+        try {
+            const entry = updateScheduleEntry(request.params.id, request.body);
+            if (!entry)
+                return reply.status(404).send({ error: 'Not found' });
+            return { entry };
+        }
+        catch (err) {
+            return reply.status(400).send({ error: err.message });
+        }
+    });
+    // DELETE /schedule/entries/:id
+    app.delete('/schedule/entries/:id', async (request, reply) => {
+        const deleted = deleteScheduleEntry(request.params.id);
+        if (!deleted)
+            return reply.status(404).send({ error: 'Not found' });
+        return reply.status(204).send();
+    });
     // ── iCal Import/Export ───────────────────────────────────────────────────
     // Export all events as .ics
     app.get('/calendar/export.ics', async (request, reply) => {