[Spec 1313] afx send: mailbox-first delivery (never force-inject)

apps/vscode/package.json

@@ -960,6 +960,11 @@
           "default": true,
           "description": "Show a VSCode notification toast when a builder reaches a human-approval gate (plan-approval, code-review, etc.)"
         },
+        "codev.mailboxEscalationToasts.enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show a VSCode notification toast when a held afx-send message crosses the escalation age (default 60s). The persistent held-count status-bar indicator is unaffected by this toggle. Read or dismiss held messages with the `afx inbox` CLI."
+        },
         "codev.overviewRefreshSeconds": {
           "type": "number",
           "default": 60,

apps/vscode/src/__tests__/mailbox-escalation-toast.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Spec 1313 Phase 8: unit tests for the `mailbox-escalation` toast handler.
+ * `vscode` is mocked (this is a `src/__tests__` vitest unit, not the Electron
+ * `src/test` harness); we drive the SSE callback the handler subscribes to and
+ * assert on `window.showWarningMessage`.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const h = vi.hoisted(() => ({
+  showWarningMessage: vi.fn(),
+  getBool: vi.fn((_key: string, dflt: boolean) => dflt),
+}));
+
+vi.mock('vscode', () => ({
+  window: { showWarningMessage: h.showWarningMessage },
+  workspace: {
+    getConfiguration: () => ({ get: (key: string, dflt: boolean) => h.getBool(key, dflt) }),
+  },
+}));
+
+const { activateMailboxEscalationToasts } = await import('../notifications/mailbox-escalation-toast.js');
+
+type SSEHandler = (e: { type: string; data: string }) => void;
+
+function makeCtx() {
+  return { subscriptions: [] as { dispose(): void }[] };
+}
+
+function makeConnectionManager(workspacePath: string | null) {
+  let handler: SSEHandler | null = null;
+  return {
+    getWorkspacePath: () => workspacePath,
+    onSSEEvent: (fn: SSEHandler) => {
+      handler = fn;
+      return { dispose() {} };
+    },
+    /** Simulate Tower pushing an SSE `data:` payload. */
+    fire: (data: string) => handler?.({ type: 'message', data }),
+  };
+}
+
+function escalationEvent(overrides: Record<string, unknown> = {}): string {
+  const payload = {
+    workspacePath: '/ws',
+    toAgent: 'spir-1',
+    mailboxId: 'mb1',
+    ageMs: 65_000,
+    reason: 'busy',
+    ...overrides,
+  };
+  return JSON.stringify({ type: 'mailbox-escalation', body: JSON.stringify(payload) });
+}
+
+function activate(cm: ReturnType<typeof makeConnectionManager>) {
+  const ctx = makeCtx();
+  // Structural fakes stand in for vscode.ExtensionContext / ConnectionManager.
+  activateMailboxEscalationToasts(ctx as any, cm as any);
+  return ctx;
+}
+
+beforeEach(() => {
+  h.showWarningMessage.mockClear();
+  h.getBool.mockReset();
+  h.getBool.mockImplementation((_key: string, dflt: boolean) => dflt);
+});
+
+describe('activateMailboxEscalationToasts', () => {
+  it('raises a warning toast for a matching escalation, with metadata (no body)', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(escalationEvent({ toAgent: 'architect:main', ageMs: 63_000, reason: 'busy' }));
+
+    expect(h.showWarningMessage).toHaveBeenCalledTimes(1);
+    const msg = h.showWarningMessage.mock.calls[0][0] as string;
+    expect(msg).toContain('architect:main');
+    expect(msg).toContain('63s');
+    expect(msg).toContain('afx inbox');
+  });
+
+  it('dedupes by mailboxId — a redelivered event does not re-toast', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(escalationEvent({ mailboxId: 'dup' }));
+    cm.fire(escalationEvent({ mailboxId: 'dup' }));
+    expect(h.showWarningMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('toasts again for a different mailboxId', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(escalationEvent({ mailboxId: 'a' }));
+    cm.fire(escalationEvent({ mailboxId: 'b' }));
+    expect(h.showWarningMessage).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores escalations for a different workspace on a shared Tower', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(escalationEvent({ workspacePath: '/other' }));
+    expect(h.showWarningMessage).not.toHaveBeenCalled();
+  });
+
+  it('ignores non-escalation SSE envelope types', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(JSON.stringify({ type: 'overview-changed', body: '{}' }));
+    expect(h.showWarningMessage).not.toHaveBeenCalled();
+  });
+
+  it('ignores malformed (non-JSON) SSE data without throwing', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    expect(() => cm.fire('not-json')).not.toThrow();
+    expect(h.showWarningMessage).not.toHaveBeenCalled();
+  });
+
+  it('does not toast when disabled via codev.mailboxEscalationToasts.enabled', () => {
+    h.getBool.mockImplementation(() => false);
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(escalationEvent());
+    expect(h.showWarningMessage).not.toHaveBeenCalled();
+  });
+
+  it('ignores a payload missing its mailboxId', () => {
+    const cm = makeConnectionManager('/ws');
+    activate(cm);
+    cm.fire(escalationEvent({ mailboxId: '' }));
+    expect(h.showWarningMessage).not.toHaveBeenCalled();
+  });
+});

apps/vscode/src/__tests__/mailbox-indicators.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Spec 1313 Phase 8: pure unit tests for the VSCode held-mail indicator
+ * helpers. No `vscode` mock — these are deliberately vscode-free so the
+ * count / tooltip / attention / toast-text math is testable in isolation.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  heldStatusSegment,
+  heldTooltipClause,
+  heldBadgeCount,
+  composeStatusBarText,
+  composeActivityBadge,
+  escalationToastText,
+  escalationMatchesWorkspace,
+} from '../mailbox-indicators.js';
+
+function makePayload(overrides: Partial<{
+  workspacePath: string;
+  toAgent: string;
+  mailboxId: string;
+  ageMs: number;
+  reason: string | null;
+}> = {}) {
+  return {
+    workspacePath: '/ws',
+    toAgent: 'spir-1',
+    mailboxId: 'mb1',
+    ageMs: 65_000,
+    reason: 'busy' as string | null,
+    ...overrides,
+  };
+}
+
+describe('heldStatusSegment', () => {
+  it('is empty when nothing is held', () => {
+    expect(heldStatusSegment(0, false)).toBe('');
+    expect(heldStatusSegment(0, true)).toBe('');
+  });
+
+  it('is empty for a negative or absent count (defensive)', () => {
+    expect(heldStatusSegment(-1, false)).toBe('');
+    // Simulates an older Tower that omits the field (undefined at runtime).
+    expect(heldStatusSegment(undefined as unknown as number, false)).toBe('');
+  });
+
+  it('renders a mail-icon segment when held and not escalated', () => {
+    expect(heldStatusSegment(2, false)).toBe(' · $(mail) 2 held');
+  });
+
+  it('swaps to the warning icon when escalated (the attention state)', () => {
+    expect(heldStatusSegment(2, true)).toBe(' · $(warning) 2 held');
+  });
+});
+
+describe('heldTooltipClause', () => {
+  it('is empty when nothing is held', () => {
+    expect(heldTooltipClause(0)).toBe('');
+    expect(heldTooltipClause(-3)).toBe('');
+  });
+
+  it('is singular for one and plural for many', () => {
+    expect(heldTooltipClause(1)).toBe('1 held message');
+    expect(heldTooltipClause(4)).toBe('4 held messages');
+  });
+});
+
+describe('heldBadgeCount', () => {
+  it('clamps negatives and absent values to 0', () => {
+    expect(heldBadgeCount(-1)).toBe(0);
+    expect(heldBadgeCount(0)).toBe(0);
+    expect(heldBadgeCount(undefined as unknown as number)).toBe(0);
+  });
+
+  it('passes a positive count through unchanged', () => {
+    expect(heldBadgeCount(5)).toBe(5);
+  });
+});
+
+describe('composeStatusBarText', () => {
+  it('renders the base builder count with no extras when nothing needs attention', () => {
+    expect(composeStatusBarText(2, 0, 0, 0, false)).toBe('$(server) Codev: 2 builders');
+  });
+
+  it('appends blocked, waiting, and held segments in order', () => {
+    expect(composeStatusBarText(3, 1, 2, 4, false)).toBe(
+      '$(server) Codev: 3 builders · $(bell) 1 blocked · $(comment-discussion) 2 waiting · $(mail) 4 held',
+    );
+  });
+
+  it('uses the warning icon for the held segment when escalated', () => {
+    expect(composeStatusBarText(1, 0, 0, 2, true)).toBe('$(server) Codev: 1 builders · $(warning) 2 held');
+  });
+
+  it('omits the held segment entirely when nothing is held', () => {
+    expect(composeStatusBarText(5, 1, 0, 0, true)).toBe('$(server) Codev: 5 builders · $(bell) 1 blocked');
+  });
+});
+
+describe('composeActivityBadge', () => {
+  it('is undefined when nothing needs the user', () => {
+    expect(composeActivityBadge(0, 0, 0)).toBeUndefined();
+    // A negative/absent held count is clamped, so it cannot fabricate a badge.
+    expect(composeActivityBadge(0, 0, -2)).toBeUndefined();
+  });
+
+  it('folds held-only into the badge with a held tooltip', () => {
+    expect(composeActivityBadge(0, 0, 3)).toEqual({ value: 3, tooltip: '3 held messages' });
+  });
+
+  it('preserves the singular/plural blocked-only phrasing', () => {
+    expect(composeActivityBadge(1, 0, 0)).toEqual({ value: 1, tooltip: '1 builder blocked at a human-approval gate' });
+    expect(composeActivityBadge(2, 0, 0)).toEqual({ value: 2, tooltip: '2 builders blocked at human-approval gates' });
+  });
+
+  it('preserves the idle-only phrasing', () => {
+    expect(composeActivityBadge(0, 1, 0)).toEqual({ value: 1, tooltip: '1 builder waiting on input' });
+  });
+
+  it('combines blocked + idle with the compact phrasing', () => {
+    expect(composeActivityBadge(2, 3, 0)).toEqual({ value: 5, tooltip: '2 blocked, 3 waiting on input' });
+  });
+
+  it('folds held into blocked + idle and joins the clauses', () => {
+    expect(composeActivityBadge(1, 1, 2)).toEqual({
+      value: 4,
+      tooltip: '1 blocked, 1 waiting on input · 2 held messages',
+    });
+    expect(composeActivityBadge(2, 0, 1)).toEqual({
+      value: 3,
+      tooltip: '2 builders blocked at human-approval gates · 1 held message',
+    });
+  });
+});
+
+describe('escalationToastText', () => {
+  it('names the recipient, the held duration in seconds, and the why-held reason', () => {
+    const text = escalationToastText(makePayload({ toAgent: 'architect:main', ageMs: 62_000, reason: 'busy' }));
+    expect(text).toContain('architect:main');
+    expect(text).toContain('62s');
+    expect(text).toContain('(busy)');
+    expect(text).toContain('afx inbox');
+  });
+
+  it('omits the reason parens when the reason is null', () => {
+    const text = escalationToastText(makePayload({ reason: null }));
+    expect(text).not.toContain('(');
+  });
+
+  it('rounds sub-second/odd ages and never goes negative', () => {
+    expect(escalationToastText(makePayload({ ageMs: 60_500 }))).toContain('61s');
+    expect(escalationToastText(makePayload({ ageMs: -10 }))).toContain('0s');
+  });
+
+  it('carries no message body (redaction — payload has none to leak)', () => {
+    // The payload type has no body field; assert the text is metadata only by
+    // confirming it is fully determined by the metadata we passed.
+    const text = escalationToastText(makePayload({ toAgent: 'b', ageMs: 60_000, reason: 'no-profile' }));
+    expect(text).toBe('Codev: a message to b has been held 60s (no-profile) — past the escalation age. Review with: afx inbox');
+  });
+});
+
+describe('escalationMatchesWorkspace', () => {
+  it('matches an identical path', () => {
+    expect(escalationMatchesWorkspace('/ws/a', '/ws/a')).toBe(true);
+  });
+
+  it('normalizes trailing slashes and . / .. segments', () => {
+    expect(escalationMatchesWorkspace('/ws/a/', '/ws/a')).toBe(true);
+    expect(escalationMatchesWorkspace('/ws/a/../a', '/ws/a')).toBe(true);
+  });
+
+  it('rejects a different workspace', () => {
+    expect(escalationMatchesWorkspace('/ws/a', '/ws/b')).toBe(false);
+  });
+
+  it('matches everything when no active workspace is known yet (startup)', () => {
+    expect(escalationMatchesWorkspace('/ws/a', null)).toBe(true);
+  });
+});

apps/vscode/src/extension.ts

@@ -32,6 +32,8 @@ import { connectTunnel, disconnectTunnel } from './commands/tunnel.js';
 import { listCronTasks } from './commands/cron.js';
 import { addReviewComment } from './commands/review.js';
 import { activateGateToasts } from './notifications/gate-toast.js';
+import { activateMailboxEscalationToasts } from './notifications/mailbox-escalation-toast.js';
+import { composeStatusBarText, composeActivityBadge } from './mailbox-indicators.js';
 import { activateReviewDecorations } from './review-decorations.js';
 import { activateReviewComments } from './comments/plan-review.js';
 import { MarkdownPreviewProvider } from './markdown-preview/preview-provider.js';
@@ -360,10 +362,19 @@ export async function activate(context: vscode.ExtensionContext) {
 		const now = Date.now();
 		const blockedCount = data.builders.filter(b => b.blocked).length;
 		const idleCount = data.builders.filter(b => isIdleWaiting(b, now)).length;
-		let text = `$(server) Codev: ${builderCount} builders`;
-		if (blockedCount > 0) { text += ` · $(bell) ${blockedCount} blocked`; }
-		if (idleCount > 0) { text += ` · $(comment-discussion) ${idleCount} waiting`; }
-		statusBarItem.text = text;
+		// Spec 1313 Phase 8: workspace-wide held-mail count (all recipients, incl.
+		// architects — the authoritative `data.heldCount`, not a per-builder sum),
+		// with a warning-flavored attention state once a held row has escalated.
+		// The text/fold logic is pure + unit-tested in `composeStatusBarText`.
+		const heldCount = data.heldCount;
+		const escalated = data.mailboxEscalated === true;
+		statusBarItem.text = composeStatusBarText(builderCount, blockedCount, idleCount, heldCount, escalated);
+		// Amber background is the persistent, log-free attention state for the count;
+		// it clears when the escalated row resolves (an overview refetch on the
+		// held-state-change broadcast flips `mailboxEscalated` back to false).
+		statusBarItem.backgroundColor = (heldCount > 0 && escalated)
+			? new vscode.ThemeColor('statusBarItem.warningBackground')
+			: undefined;
 	};
 
 	// List views show their item count in the title: "Agents (3)".
@@ -412,17 +423,12 @@ export async function activate(context: vscode.ExtensionContext) {
 		const now = Date.now();
 		const blockedCount = data.builders.filter(b => b.blocked).length;
 		const idleCount = data.builders.filter(b => isIdleWaiting(b, now)).length;
-		const total = blockedCount + idleCount;
-		if (total === 0) {
-			buildersView.badge = undefined;
-			return;
-		}
-		const tooltip = (blockedCount > 0 && idleCount > 0)
-			? `${blockedCount} blocked, ${idleCount} waiting on input`
-			: blockedCount > 0
-				? (blockedCount === 1 ? '1 builder blocked at a human-approval gate' : `${blockedCount} builders blocked at human-approval gates`)
-				: (idleCount === 1 ? '1 builder waiting on input' : `${idleCount} builders waiting on input`);
-		buildersView.badge = { value: total, tooltip };
+		// Spec 1313 Phase 8: fold the workspace held-mail count into the badge so the
+		// activity-bar icon reflects it even when the sidebar is collapsed. Held is a
+		// count only (not a per-builder "needs me" gate); the tooltip disambiguates it
+		// from the blocked/idle signals. The fold + tooltip composition (and the
+		// undefined-when-empty clear) is pure + unit-tested in `composeActivityBadge`.
+		buildersView.badge = composeActivityBadge(blockedCount, idleCount, data.heldCount);
 	};
 
 	// Close builder/dev terminal tabs when their builder disappears from the
@@ -1360,6 +1366,11 @@ export async function activate(context: vscode.ExtensionContext) {
 	// user to watch the Builders tree. Respects `codev.gateToasts.enabled`.
 	activateGateToasts(context, overviewCache);
 
+	// Spec 1313 Phase 8: toast when a held message crosses the escalation age
+	// (the `mailbox-escalation` SSE event). Visibility only — read/dismiss via
+	// `afx inbox`. Respects `codev.mailboxEscalationToasts.enabled`.
+	activateMailboxEscalationToasts(context, connectionManager);
+
 	// Auto-open builder terminals on Tower spawn events
 	const builderSpawnHandler = new BuilderSpawnHandler(connectionManager, terminalManager, outputChannel);
 	context.subscriptions.push(