gsxdsm 9c43736794 FN-8870: add structural approval and report mail ...

Add typed report and approval metadata to the mailbox contract.

- Define and validate structural mail kinds, report sections, and approval references.
- Let agents send validated reports while reserving approval mail for engine emission.
- Emit idempotent, fail-soft approval notifications and document the contract.

Files changed:
 .changeset/fn-8870-structural-mail-contract.md     |   7 ++
 docs/agents.md                                     |   2 +
 docs/architecture.md                               |   4 +
 .../message-metadata-structural-mail.test.ts       |  25 ++++
 packages/core/src/index.gate.ts                    |   2 +-
 packages/core/src/index.ts                         |   2 +-
 packages/core/src/types.ts                         |  30 +++++
 packages/core/src/types/messaging/messages.ts      |  21 ++++
 ...gent-tools-send-message-structural-mail.test.ts |  34 +++++
 .../src/__tests__/approval-mail-emission.test.ts   | 137 +++++++++++++++++++++
 packages/engine/src/agent-heartbeat.ts             |   3 +
 packages/engine/src/agent-tools.ts                 |  28 ++++-
 packages/engine/src/agents/approval-mail.ts        |  40 ++++++
 packages/engine/src/executor.ts                    |   3 +
 14 files changed, 334 insertions(+), 4 deletions(-)

Fusion-Task-Id: FN-8870

Fusion-Task-Lineage: 7d30b2f9-c004-4975-86b1-9600e2c8d76f

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>

2026-08-09 00:41:18 -07:00

..

__tests__

FN-8870: add structural approval and report mail

2026-08-09 00:41:18 -07:00

agents

FN-8870: add structural approval and report mail

2026-08-09 00:41:18 -07:00

auth

fix: self-heal executor credential resolution for custom providers

2026-08-03 10:58:19 -07:00

auto-recovery-handlers

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

cli-agent

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

cli-runtime

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

concurrency

FN-8822: prevent worktree capacity leaks

2026-08-07 21:43:28 -07:00

errors

FN-8799: suppress alerts during automatic task recovery

2026-08-04 22:17:06 -07:00

eval

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

execution

FN-8840: recognize duplicate redirects in task titles

2026-08-08 19:58:43 -07:00

executor

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

experiment

feat: migrate storage from SQLite to PostgreSQL (#1793)

2026-07-13 19:07:58 -07:00

external-integrations

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

goals

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

healing

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

ipc

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

mcp

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

merge

FN-8838: refresh automated PR heads before GitHub mutations

2026-08-08 22:35:59 -07:00

missions

FN-8824: enforce serial mission slice advancement

2026-08-07 20:56:52 -07:00

notification

FN-8867: prevent false task wedge notifications

2026-08-09 00:01:44 -07:00

overseer

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

plugins

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

project

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

providers

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

recovery

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

remote-access

…

research

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

review-artifacts

FN-8416: guard engine playwright-core dependency

2026-07-20 10:13:57 -07:00

runtimes

FN-8822: prevent worktree capacity leaks

2026-08-07 21:43:28 -07:00

sandbox

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

scheduling

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

spec-validation

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

test

…

triage-domain

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

types/node-pty

…

util

feat(workflow): add fn_workflow_step_resume operator escape hatch for stuck pending merge-review steps (#3339)

2026-08-07 00:26:15 -07:00

workflow-node-runners

FN-8823: respect shared member auto-merge holds

2026-08-07 20:27:04 -07:00

workflows

FN-8841: route Plan Review no-op verdicts to terminal close

2026-08-08 21:04:10 -07:00

worktree

FN-8825: move secrets fingerprints into private Git metadata

2026-08-07 21:18:24 -07:00

_layout.ts

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

agent-heartbeat.ts

FN-8870: add structural approval and report mail

2026-08-09 00:41:18 -07:00

agent-tools.ts

FN-8870: add structural approval and report mail

2026-08-09 00:41:18 -07:00

bash-containment.ts

fix(security): make the approval and permission gates actually enforce (#2457)

2026-07-30 21:50:37 -07:00

credential-instance-rotation.ts

FN-8654: rotate credential instances after provider limits

2026-08-01 08:20:29 -07:00

duplicate-marker-clear.ts

fix(FN-8785): ignore completed duplicate history

2026-08-04 10:52:12 -07:00

execution-block-classifier.ts

fix: stop blocking tasks on open-PR file claims — board tasks are the only blockers

2026-08-02 17:06:38 -07:00

executor.ts

FN-8870: add structural approval and report mail

2026-08-09 00:41:18 -07:00

index.ts

FN-8764: route workflow stages through durable role agents

2026-08-07 01:36:34 -07:00

logger.ts

fix: guard CE sessions against concurrent-turn displacement and harden JSON-protocol parsing

2026-07-23 10:31:22 -07:00

merger.ts

FN-8764: route workflow stages through durable role agents

2026-08-07 01:36:34 -07:00

pi.ts

FN-8764: route workflow stages through durable role agents

2026-08-07 01:36:34 -07:00

plan-artifact-writeback.ts

fix(engine): save worktree-written plans to the project and the database

2026-07-25 20:46:07 -07:00

plan-review-continuation.ts

FN-8792: resume Plan Review after approval

2026-08-04 19:31:06 -07:00

plan-review-feedback-history.ts

fix: prevent stale planning approvals and review churn (#3327)

2026-08-04 00:20:08 -07:00

planner-lane-resolution.ts

consolidate/u11: a hold column is a planner lane only if it precedes wip (real defect in merged code) + funnel aliases (triage 11 -> 10) (#2645)

2026-07-30 00:00:46 -07:00

planning-handoff-recovery.ts

fix: prevent stale planning approvals and review churn (#3327)

2026-08-04 00:20:08 -07:00

project-engine-manager.ts

feat: restart the development engine on source changes (#3329)

2026-08-04 08:57:30 -07:00

project-engine.ts

FN-8837: fix pull-request merge retry recovery

2026-08-08 22:43:45 -07:00

recovery-reconciler.ts

U4: scope the user-pause safeguard to lifecycle MUTATION, not observation (re-ratified) (#2486)

2026-07-27 17:37:20 -07:00

reports-health.ts

FN-8569: surface unrecoverable report health

2026-07-24 23:57:49 -07:00

scheduler.ts

FN-8840: recognize duplicate redirects in task titles

2026-08-08 19:58:43 -07:00

self-healing-git-evidence.ts

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

self-healing.ts

FN-8840: recognize duplicate redirects in task titles

2026-08-08 19:58:43 -07:00

surfacing-sweeps.ts

fix(engine,core): role resolution was half-done in two shared lifecycle predicates (surfacing family + file-scope leases) (#2975)

2026-07-30 23:13:34 -07:00

triage.ts

FN-8840: recognize duplicate redirects in task titles

2026-08-08 19:58:43 -07:00

workflow-column-boundary-hooks.ts

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00

workflow-event-subscribers.ts

Phase A: workflow-owned lifecycle foundation (U1, U2, U3) (#2467)

2026-07-27 13:30:13 -07:00

worktree-base-refresh.ts

refactor: domain folder layout (types, API, core, engine) (#2398)

2026-08-03 00:20:53 -07:00