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

AGENTS.md

@@ -603,6 +603,15 @@ Agents within a workspace communicate through `afx send`. Four addressing forms
 | `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect. This is the sibling-architect messaging form. **Builders**: allowed ONLY when `<name>` matches the builder's own `spawnedByArchitect`. Mismatches are rejected by the spoofing check at `tower-messages.ts:213-218`. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
 | `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
 
+### Send outcomes: delivered vs held (Spec 1313)
+
+`afx send` reports the real first outcome, not an unconditional success:
+
+- **delivered** — written to the recipient's prompt after a clean render-gate pass (a verified-empty prompt).
+- **held** — the prompt wasn't clear, so the message is persisted in Tower's durable mailbox and delivers automatically once the prompt is clean (after a submit, on output quiescence, or a poll backstop). The response carries a why-held reason — `busy` (a draft/menu/dialog/wrapper occupies the prompt), `no-profile` (unknown app; only `claude`, `codex`, and `agy` are modeled), or `no-live-pty` (no live terminal — delivers on respawn, since rows address agents not PTYs) — plus a mailbox id.
+
+A held message is **never force-injected** onto a busy line, so it can't fuse with a half-typed draft, and held rows survive Tower restart/shutdown. See held mail with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>` (dismissal is CLI-only; the dashboard and VSCode held-count indicators are read-only). `afx send --interrupt` remains the explicit, deliberate bypass (it interrupts the agent and skips holding).
+
 ### Sibling-architect messaging
 
 When a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example:

CLAUDE.md

@@ -603,6 +603,15 @@ Agents within a workspace communicate through `afx send`. Four addressing forms
 | `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect. This is the sibling-architect messaging form. **Builders**: allowed ONLY when `<name>` matches the builder's own `spawnedByArchitect`. Mismatches are rejected by the spoofing check at `tower-messages.ts:213-218`. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
 | `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
 
+### Send outcomes: delivered vs held (Spec 1313)
+
+`afx send` reports the real first outcome, not an unconditional success:
+
+- **delivered** — written to the recipient's prompt after a clean render-gate pass (a verified-empty prompt).
+- **held** — the prompt wasn't clear, so the message is persisted in Tower's durable mailbox and delivers automatically once the prompt is clean (after a submit, on output quiescence, or a poll backstop). The response carries a why-held reason — `busy` (a draft/menu/dialog/wrapper occupies the prompt), `no-profile` (unknown app; only `claude`, `codex`, and `agy` are modeled), or `no-live-pty` (no live terminal — delivers on respawn, since rows address agents not PTYs) — plus a mailbox id.
+
+A held message is **never force-injected** onto a busy line, so it can't fuse with a half-typed draft, and held rows survive Tower restart/shutdown. See held mail with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>` (dismissal is CLI-only; the dashboard and VSCode held-count indicators are read-only). `afx send --interrupt` remains the explicit, deliberate bypass (it interrupts the agent and skips holding).
+
 ### Sibling-architect messaging
 
 When a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example:

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);
+  });
+});