Monitor Report Contract

The machine-readable source of truth is src/reporting/monitor-report-policy.ts. Agents and report renderers must read it through the read-only get_monitor_report_policy MCP tool rather than infer a report layout from a prompt.

Contract

monitor-report-v2 produces the scheduled-summary-plus-mailbox-ledger artifact family.

• Put the exact report period, complete/incomplete coverage status, and truthful changes-made status directly below the report heading and before the totals table.
• Start the summary with Mailbox | New | Action needed | Useful | Low priority | Applied, one row per configured mailbox and one total row.
• Assign the four stable markers 🟦, 🟪, 🟩, and 🟧 deterministically to the heartbeat's configured mailbox alias order.
• Always print the written alias with its marker. Color is a redundant cue, never the sole identifier or a correctness dependency.
• Include every newly covered message exactly once in a mailbox-grouped bulleted ledger.
• Sort workflow states Action needed, Useful reference, then Low priority; sort newest first within each state.
• Each ledger item shows priority, styled sender and subject, received time, one to three controlled labels, and one outcome: Applied, Not applied, Skipped, or Failed.
• Count Applied by message, and only after its receipt is verified against the same mailbox, exact message ID, exact frozen label plan, and exact controlled labels.
• State coverage and checkpoint status, receipt counts, skipped and failed counts, and the next action. Incomplete coverage, partial application, and failures must remain visible rather than being summarized away.

The label ceiling comes directly from organizationPolicy.maxLabelsPerMessage; report renderers must not duplicate or override it.

Independent Durable Cursors

Hourly processing and scheduled reporting are separate durable concerns:

• The coverage checkpoint advances after one complete exact poll has been classified and its label outcomes are known. Its sanitized results are appended idempotently to the private report ledger.
• The report checkpoint advances only after every page of one frozen scheduled report has been reconciled. Committing moves those exact entries into a replayable pending-delivery outbox and leaves later entries queued.
• An off-cadence urgent alert may set alertedAt, but it does not advance the report checkpoint. The message remains in the next scheduled report.
• Scheduled boundaries are derived in America/New_York and snap to the latest exact 9:00 AM or 5:00 PM boundary at or before the trigger. Heartbeat minute/second drift cannot move the reporting period.
• A restart reloads both cursors, the pending ledger, and any committed pending delivery. A failed or stale scheduled report does not consume entries.
• A report is classified as scheduled when its cursor equals the nominal prior boundary, partial-since-activation when its cursor begins later, and catch-up when it begins earlier. This classification is frozen into both the report poll and replayable delivery.
• The next heartbeat uses one deterministic four-entry bundle in configured-mailbox order. The gateway privately maps each immutable configured account to its exact durable-outbox token or NO_PENDING_DELIVERY; get_monitor_report_delivery_bundle and the alias-only custom CLI return only its SHA-256 digest, counts, and pending aliases. Bundle calculation is local-only and remains stable when a provider mailbox becomes unavailable; the exact acknowledgment still re-attests its mailbox. Tokens never enter digest-command arguments. Same-run acknowledgment is forbidden. A later run with the matching prior-response digest may clear only the token-bearing, correctly attested subset. Pending delivery blocks only that mailbox, so partial multi-mailbox commits can prepare missing deliveries or retry later without deadlock.
• Frozen reports are paginated in exact 100-entry pages. Every page digest is required at commit, so no oversized or partially rendered report can advance the report cursor.
• The first v2 report is explicitly Partial since activation when the pre-v2 coverage checkpoint began after the nominal scheduled-period start. A fresh seven-day bootstrap is explicitly Catch-up, not a normal scheduled report. Later reports become full-period after the first cutover delivery is acknowledged.
• Report state and frozen polls bind both organization-v4 and monitor-report-v2 versions and digests. Policy drift fails closed.
• Per-account durable writes use an operating-system advisory lock. The kernel releases the lock on process death, so an empty or stale lock-file artifact cannot steal a live lock or block later recovery.

Safety Boundary

Synthetic Preview

DOCS/evidence/active/1012_mailbox_report_and_routing_experience/report-preview.html is synthetic visual evidence. It contains no live addresses, sender identities, subjects, message IDs, or message content. Current-run desktop and narrow-width inspection passed for the synthetic artifact; scheduled-client rendering remains unverified.

Dataset Preview

• Raw CSV row/table content is available in the source artifact.