## Summary
- Treat **shared PostgreSQL** (`DATABASE_URL`) as the multi-node durable
data plane; mesh HTTP is membership + optional auth, not task/settings
replication.
- **Peer exchange**: under Postgres backend mode, write queue is
**topology/auth-only**; non-topology pending rows fail rather than
replaying multi-leader task/settings payloads.
- **Mesh routes**: task-ID reserve/commit/abort always hit local shared
allocator rows (ignore remote `coordinatorNodeId`); mesh sync ignores
settings and only exchanges `authMaterial`.
- **Docs**: rewrite multi-project runbook, shared cluster protocol, and
architecture mesh sections for shared-Postgres + claims/leases.
## Context
Follows the SQLite→Postgres cutover. Multiple Fusion nodes can share one
external Postgres while keeping **per-node execution** (worktrees,
processes, claims via `central.task_claims`). Explicit non-goals remain:
scheduler failover and live process migration.
Plan:
`docs/plans/2026-07-15-001-refactor-mesh-shared-postgres-multinode-plan.md`
## Test plan
- [x] `pnpm --filter @fusion/engine exec vitest run
src/__tests__/peer-exchange-service.test.ts`
- [x] `pnpm --filter @fusion/dashboard exec vitest run
src/__tests__/mesh-routes.test.ts`
- [x] `pnpm --filter @fusion/core exec vitest run
src/__tests__/shared-mesh-state.test.ts`
- [ ] CI gate (lint/typecheck/build/gate)
- [ ] Manual (optional): two processes, same `DATABASE_URL`, create task
on A visible on B; settings change without mesh settings sync; claim
exclusivity
## Operator note
Multi-node shared board requires **external** `DATABASE_URL` on every
node. Default embedded Postgres is still single-host.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Improved multi-node deployments using shared PostgreSQL as the durable
source of execution state.
* Task ID reservation/commit/abort now run locally (no remote
coordinator forwarding).
* Mesh syncing now prioritizes topology visibility and authentication
material; settings replication is disabled in shared-Postgres mode.
* **Bug Fixes**
* Prevented task/settings replication over mesh HTTP in shared-Postgres
deployments.
* Refined lease ownership, recovery, and reconciliation to converge via
shared-database primitives.
* **Documentation**
* Updated architecture and shared-mesh protocol guidance, including
multi-node setup and lease/task-ID allocation behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Bundled plugins now persist shared runtime state in project-scoped
PostgreSQL tables instead of maintaining independent SQLite authority.
Reports, CLI Printing Press, Compound Engineering, Roadmap, Even
Realities, and WhatsApp all follow the same ownership and startup
contract as Fusion core.
## Design decisions
- Plugin schema hooks run through the host’s PostgreSQL owner and
enforce project isolation.
- The SDK exposes the host contract needed by bundled plugins without
importing engine internals.
- Legacy Roadmap ownership fixtures use the supported empty-owner
sentinel, preserving current composite primary/foreign keys while
exercising backfill behavior.
- The lockfile travels with the Even Realities PostgreSQL dependency so
packaged installs remain reproducible.
## Validation
- All six affected plugin builds pass.
- Affected plugin suites pass: 773 tests across Printing Press, Compound
Engineering, Even Realities, Reports, Roadmap, and WhatsApp.
- `pnpm test:gate` passes all 478 gate tests.
- This PR changes 40 files.
## Stack
- Depends on #2110 → #2109 → #2108.
- The documentation/release PR completes the stack.
Related: #2105
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Breaking Changes**
* PostgreSQL is now required for runtime storage; SQLite files are used
only as one-time migration inputs.
* The legacy `FUSION_NO_EMBEDDED_PG` fallback has been removed.
* **New Features**
* Added project-isolated PostgreSQL storage for plugins, reports, tasks,
notifications, and other plugin data.
* Added agent tools for reports and CLI service drafts.
* Added PostgreSQL schema initialization support for plugin authors.
* **Bug Fixes**
* Improved migration and recovery of legacy plugin state.
* Prevented cross-project data access and strengthened transactional
schema updates.
* **Documentation**
* Updated storage, migration, deployment, plugin authoring, CLI, and
dashboard guidance for PostgreSQL.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Docs-only change adding front-door discovery for the already-shipped planner-oversight feature (FN-7508 → FN-7583), which previously had no entry point outside internal reference docs.
- Add a README.md feature table row and a new "Planner oversight" section describing oversight levels (off/observe/steer/autonomous) and the always-on human-confirmation gate for merge/PR and destructive actions, linking to Settings Reference and Dashboard Guide
- Add a README.md capabilities bullet cross-linking the new section
- Add a docs/README.md hub row pointing to Settings Reference, Dashboard Guide, and Architecture for planner oversight, and extend the 'power user' reading path
- Add a one-line pointer in docs/getting-started.md workflow section noting per-task/workflow oversight controls
Files changed:
README.md | 11 +++++++++++
docs/README.md | 9 ++++++---
docs/getting-started.md | 3 +++
3 files changed, 20 insertions(+), 3 deletions(-)
Fusion-Task-Id: FN-7598
Fusion-Task-Lineage: 8141b44c-f007-45c0-a057-f4eeb34ae8d4
Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
Document the previously unlinked docs from the README index for easier discovery.
- Add Signals Connectors to the documentation guide section.
- Add testing baseline and audit reports to the audit reports index.
- Record the FN-7088 docs-index requirement in the existing FNXC DocsIndex note.
Files changed:
docs/README.md | 7 +++++++
1 file changed, 7 insertions(+)
Fusion-Task-Id: FN-7088
Fusion-Task-Lineage: df77fa9a-ba63-4df9-ac70-d144230eb8f3
Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
Add a canonical dashboard workflow editor guide and connect it from related docs.
- Add a new Workflow Editor guide covering entry points, canvas anatomy, authoring panels, settings values, templates, AI design, import/export, and mobile behavior.
- Link the guide from the docs index, settings reference, and Workflow IR overview.
- Require the workflow editor guide in the docs README index coverage test.
Files changed:
docs/README.md | 1 +
docs/settings-reference.md | 2 +-
docs/workflow-editor.md | 158 +++++++++++++++++++++
docs/workflow-steps.md | 2 +-
.../cli/src/__tests__/docs-readme-index.test.ts | 1 +
5 files changed, 162 insertions(+), 2 deletions(-)
Fusion-Task-Id: FN-6520
Fusion-Task-Lineage: 9a2525a5-6ff8-48de-ae13-a7c7c5844f99
Index the upstream ACP MCP forwarding sponsorship doc so the docs README and CLI index test keep it discoverable.
- Add the upstream ACP MCP passthrough and permission forwarding sponsorship doc link under Audit Reports.
- Add the upstream doc to the required docs README index coverage.
- Guard that CLI Printing Press docs remain indexed in Audit Reports only, not duplicated under Plugins.
Files changed:
docs/README.md | 5 +++++
.../cli/src/__tests__/docs-readme-index.test.ts | 21 +++++++++++++++++++++
2 files changed, 26 insertions(+)
Fusion-Task-Id: FN-6479
Fusion-Task-Lineage: f23afeba-a989-4552-8857-fe2984df6081
Add a durable proof-point runbook for validating external plugins against released Fusion CLI builds.
- Document release selection, npm integrity capture, scaffold/build/test/install/enable validation, and pass/fail criteria for external plugin proof points.
- Link the runbook from the docs index so it remains discoverable with other plugin authoring docs.
- Extend the docs README index test to require the new proof-point runbook entry.
Files changed:
docs/README.md | 1 +
docs/plugins/external-proof-point-runbook.md | 211 +++++++++++++++++++++
.../cli/src/__tests__/docs-readme-index.test.ts | 1 +
3 files changed, 213 insertions(+)
Fusion-Task-Id: FN-6438
Fusion-Task-Lineage: 5c768d7e-4465-42ac-9535-f16dc42ab6d0
Two engine merger tests created mkdtempSync workspaces directly in tmpdir()
under the tracked `fusion-test-` prefix; under full-suite concurrent load
the post-run check-test-isolation flagged them as leaks. Route both
(`merger-no-op-fix-finalize.test.ts`, `merger-verification-fix-already-on-main.test.ts`)
through FUSION_TEST_WORKER_ROOT like sibling merger tests so they nest
inside the already-tracked worker root.
Bump engine vitest subprocess guard from 60s to 120s and testTimeout to
30s — plain git commands (branch -d, worktree remove) queued behind
system contention during `pnpm -r --workspace-concurrency=2` runs were
timing out. The guard only fires on hangs, so healthy tests pay nothing.
Also bundles in-progress dashboard mobile-breakpoint regex/CSS test
updates and docs index additions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Completes FN-5153 by delivering the soft-delete verification gate with a new end-to-end test suite covering the full soft-delete lifecycle and a documentation matrix summarizing the gate behavior. Updates the dashboard test file and adds a brief entry to AGENTS.md to surface the new feature.
Fusion-Task-Id: FN-5153
- Add diagnostics.md and FN-4886/FN-5048 entries to docs/README.md index
- Fix test-project.test.ts spy target (updateSettings → init) to match fixture flow
- Remove unused DEFAULT_PROJECT_SETTINGS import and skip empty settings patch
- Add explanatory comments to empty catch blocks in secrets-env-writer
- Refine near-duplicate timestamp guard in triage for cleaner NaN handling
The merge implements optimistic room send with failure recovery in the ChatView and useChatRooms hook, including a reconciliation flow that handles send failures gracefully and documents the UX behavior. The dashboard guide and architecture docs are updated to reflect the new room messaging pattern.
Fusion-Task-Id: FN-4040
Canonicalizes the Fusion reports plugin's manifest ID and exports a reports schema alias from the package index, with tests aligned to the new identifiers.
Fusion-Task-Id: FN-3826
dropAutostashBySha resolved SHA→stash@{N} then ran git stash drop ${ref}
non-atomically. Any other process (interactive shell, parallel merger,
fix-agent) pushing a stash between resolve and drop shifted the index, so
we silently dropped the wrong entry while leaving ours behind. The task
log then claimed "Restored pre-merge autostash X cleanly" even though the
stash was still in the list — observed on FN-3558 (e81e922) and others.
Verify the ref still resolves to our SHA via git rev-parse before dropping;
on mismatch, re-resolve and retry up to 5x. Return success/failure so the
caller can record honest status to the task feed instead of unconditionally
logging "cleanly".
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/evals.md was not listed in the docs/README.md index despite being
referenced from architecture.md and dashboard-guide.md. Added it to the
Task & Project Management section.
Adds a native shell integration guide (FN-3577) with fusionShell bridge contract documentation, wired into the docs navigation, plus a regression test; also hardens the dependency graph's task filtering (FN-3085) to include in-review tasks and handle orphan edges, with corresponding test coverage ac
Fusion-Task-Id: FN-3577
The merge brings TaskDetailModal test coverage in line with the project's testing standards by splitting the monolithic 6,745-line test file into five focused suites. It also delivers merger reliability improvements including headline-step subject preference, redundant-merge verification skipping, a
Fusion-Task-Id: FN-3594
This merge adds a complete plugin management system to Fusion: a new `fn plugin` CLI command for installing/removing plugins, a plugin loader in core, a plugin runner in engine, and dashboard routes for plugin management UI, along with a plugin management guide in docs. It also documents task evalua
Fusion-Task-Id: FN-3565
The merge normalizes button utility classes in AgentsView, swapping 12 lines of CSS class references for their standardized counterparts for consistency and maintainability.
Fusion-Task-Id: FN-3448
- Restore workspace llama-cpp extension path resolution in CLI command handling
- Add missing docs/README.md index entries and keep README/doc links aligned
- Add regression coverage for docs README index completeness and docker docs references
- Carry forward related workspace stability updates and test hardening from the branch
Fusion-Task-Id: FN-3433
The merge introduces a canonical research guide (`docs/research.md`) as a central reference and updates cross-links across the documentation suite, including agents, architecture, dashboard-guide, settings-reference, and storage docs. The most significant addition is the 436-line research guide itse
Fusion-Task-Id: FN-3002
