26f2a2080a
Contain task lifecycle movement within the workflow graph so cards cannot wander between columns. - Enforce directional transition and containment policies across task, recovery, merge, and workspace flows. - Centralize lifecycle move execution, provenance, reason logging, and live-column rebound handling. - Add regression, forbidden-path, remediation-placement, and workspace reuse coverage. Files changed: .changeset/fn-207-lifecycle-containment.md | 7 + AGENTS.md | 2 + docs/architecture.md | 1 + docs/workflow-steps.md | 2 + .../__tests__/lifecycle-direction-policy.test.ts | 88 ++++++ .../lifecycle-move-provenance-emit.test.ts | 107 +++++++ .../__tests__/remediation-step-placement.test.ts | 51 ++++ packages/core/src/index.gate.ts | 11 +- packages/core/src/index.ts | 21 +- packages/core/src/store.ts | 25 +- packages/core/src/task-store/lifecycle-ops.ts | 21 +- packages/core/src/task-store/moves.ts | 28 +- .../core/src/task-store/remediation-step-ops.ts | 19 +- .../core/src/tasks/remediation-step-placement.ts | 43 +++ .../src/workflows/workflow-lifecycle-direction.ts | 167 +++++++++++ .../src/workflows/workflow-lifecycle-traits.ts | 32 +++ .../src/workflows/workflow-transition-policy.ts | 56 +++- .../auto-recovery-branch-worktree.test.ts | 25 +- .../executor-browser-verification.test.ts | 6 +- ...ecutor-execution-policy-renamed-columns.test.ts | 19 +- .../__tests__/executor-graph-requeue-gate.test.ts | 16 +- .../src/__tests__/executor-step-session.test.ts | 20 +- .../__tests__/fix-steps-from-failed-gates.test.ts | 66 ++++- .../__tests__/lifecycle-containment-resume.test.ts | 142 +++++++++ .../__tests__/lifecycle-forbidden-paths.test.ts | 319 +++++++++++++++++++++ .../__tests__/lifecycle-move-legibility.test.ts | 157 ++++++++++ .../__tests__/lifecycle-move-reason-census.test.ts | 101 +++++++ .../__tests__/merger-ai-renamed-columns.test.ts | 28 +- packages/engine/src/__tests__/merger-ai.test.ts | 22 +- .../merger-finalize-unproven.real-git.test.ts | 26 +- .../auto-revive-and-watchdog.test.ts | 10 +- .../merge-node-paused-abort-retryable.test.ts | 14 +- .../worktree-incomplete-session-start.test.ts | 13 +- .../engine/src/__tests__/replan-target.test.ts | 48 +++- .../__tests__/restart-recovery-coordinator.test.ts | 9 +- .../__tests__/review-history-preservation.test.ts | 32 ++- .../src/__tests__/reviewer-workspace.test.ts | 6 +- .../src/__tests__/self-healing-trait-rekey.test.ts | 15 +- packages/engine/src/__tests__/self-healing.test.ts | 163 ++++++++++- .../verification-failure-named-remediation.test.ts | 54 ++-- .../workflow-graph-optional-step-fix.test.ts | 62 +++- .../workflow-merge-rebound-live-e2e.pg.test.ts | 2 +- .../engine/src/__tests__/workspace-merger.test.ts | 6 +- .../workspace-node-worktree-reuse.test.ts | 188 ++++++++++++ .../src/auto-recovery-handlers/branch-worktree.ts | 28 +- .../src/auto-recovery-handlers/contamination.ts | 30 +- .../engine/src/execution/lifecycle-move-log.ts | 77 +++++ packages/engine/src/execution/lifecycle-move.ts | 63 ++++ packages/engine/src/execution/replan-target.ts | 51 +++- .../executor/append-review-remediation-steps.ts | 72 ++++- ...block-outer-dispatch-when-ephemeral-disabled.ts | 1 + .../src/executor/bounce-verification-failure.ts | 53 ++-- .../engine/src/executor/completion-finalization.ts | 1 + .../engine/src/executor/create-task-done-tool.ts | 29 +- .../src/executor/dependency-dispatch-gate.ts | 1 + .../executor/ensure-graph-custom-node-worktree.ts | 19 +- .../engine/src/executor/handle-graph-failure.ts | 7 +- .../engine/src/executor/recover-completed-task.ts | 4 +- .../request-pre-merge-optional-step-fix.ts | 40 ++- .../src/executor/required-artifact-recovery.ts | 7 +- .../src/executor/review-convergence-ladder.ts | 5 +- .../route-graph-failure-to-execution-resume.ts | 28 +- .../engine/src/executor/run-graph-custom-node.ts | 30 +- packages/engine/src/executor/run-implementation.ts | 6 +- .../engine/src/executor/workflow-rerun-bounce.ts | 54 ++-- .../engine/src/executor/workflow-rerun-watchdog.ts | 6 +- .../src/healing/restart-recovery-coordinator.ts | 30 +- packages/engine/src/merge/merger-ai.ts | 66 +++-- packages/engine/src/merger.ts | 46 +-- .../__tests__/notification-service.test.ts | 13 +- packages/engine/src/project-engine.ts | 7 +- .../src/recovery/foreign-only-contamination.ts | 30 +- packages/engine/src/scheduler.ts | 4 +- packages/engine/src/self-healing.ts | 120 +++++--- .../self-healing/auto-recover-worktree-session.ts | 32 ++- .../engine/src/workflow-column-boundary-hooks.ts | 1 + .../workflow-node-runners/parse-steps-runner.ts | 10 +- scripts/lib/lifecycle-column-census-baseline.json | 3 +- 78 files changed, 2750 insertions(+), 474 deletions(-) Fusion-Task-Id: FN-207 Fusion-Task-Lineage: a64a49f7-e06b-4b33-94c6-d43a4b027610 Co-authored-by: Fusion <noreply@runfusion.ai>
Fusion Documentation
Fusion is an AI-orchestrated task board that turns ideas into reviewed, merged code using a structured workflow: planning → todo → in-progress → in-review → done.
Quick Start
Start the local dashboard with pnpm dev dashboard, then create your first task from the board or CLI.
For a full walkthrough (installation, onboarding, first task, and daily workflow basics):
Documentation Index
Getting Started
| Guide | Description |
|---|---|
| Getting Started | Installation, first-run, first task, and daily workflow basics |
| Dashboard Guide | Board/list views, left/right sidebar navigation, Artifacts, Import Tasks, chat, workflow selection/editor, terminal, git manager, files, planning, and UI tools |
| CLI Reference | Complete fn command reference with subcommands, flags, and examples |
| Computer Use | fn computer desktop-app discovery, snapshots, actions, permissions, and JSON contract |
| Remote Access | Operator runbook for Tailscale/Cloudflare setup, tokenized login links, security caveats, and troubleshooting |
| Native Shell Connection Guide | Canonical mobile/desktop shell onboarding, profile management, QR/manual setup, and remote handoff behavior |
Task & Project Management
| Guide | Description |
|---|---|
| Task Management | Task creation modes, lifecycle, prompt specs, comments, archiving, and GitHub integration |
| Todo View | Canonical guide for the experimental Todo View, including enablement, usage, API routes, and storage |
| Missions | Mission hierarchy, planning flow, activation, progress tracking, and autopilot behavior |
| Goals Refinement Gate | Evidence gate for activating the conditional post-v1 goals refinement slice only after real usage pain is documented |
| Goals Refinement Evidence Pack | Structured observation template and two-observation threshold for conditional Slice 4 activation requests |
| Research | Research runs, provider setup, dashboard/CLI usage, findings, exports, and task integration |
| Research View UX Spec | Canonical layout and capability-state messaging spec for the Research dashboard view (FN-4138, informs FN-4134/FN-4135) |
| Workflow Steps | Workflow overview, built-in workflow catalog, per-task selection, runtime semantics, reusable quality gates, templates, phases, and execution results |
| Workflow Editor | Visual workflow editor guide for opening, viewing, authoring, validating, importing/exporting, custom fields/columns/settings, and tuning workflows |
| Custom Workflow Reliability Acceptance Map | End-to-end reliability acceptance criteria for custom workflow authoring, selection, execution, recovery, restart durability, and deferred journeys |
| Custom Non-Coding Workflows MVP Spec | MVP framing for user-authored non-coding workflows, lifecycle mapping, metrics, and risk checklist |
| Task Evaluations | Eval scoring contract, evidence persistence, score categories, and evaluation pipeline |
| Multi-Project | Central registry architecture, project management, isolation modes, and migration paths |
| Workspaces (Multi-Repository) | Workspace setup, per-repository execution and land, recovery, revert, and archive cleanup |
Configuration & Agents
| Settings Reference | Global/project settings, workflow setting values, model/fallback lane hierarchy, defaults, and API endpoints |
| MCP | Model Context Protocol server configuration, secret references, validation, CLI, dashboard, and import/export workflows |
| Agents | Agent management, presets, prompts, heartbeat behavior, spawning, and mailbox workflows |
| Planner Oversight (see Settings Reference, Dashboard Guide, Architecture) | Workflow-native oversight levels (off/observe/steer/autonomous), per-task overrides, notification verbosity, the human-confirmation gate on merge/PR and destructive actions, and the Task Detail overseer controls/Intervention Timeline |
Architecture & Development
| Guide | Description |
|---|---|
| Architecture | System architecture, package layout, storage model, and engine execution flow |
Secrets Store (SecretsStore) |
Core encrypted secret subsystem overview: scopes, AES-256-GCM at-rest model, policy semantics, and public store API surface |
| Dashboard Real-Time | Canonical event-stream architecture contract (shared /api/events bus + dedicated stream boundaries), with project/node scoping, reconnect/cleanup behavior, and realtime pitfalls |
| Agent Activity Contract | Canonical wire, cursor, and retention contract for the project-scoped GET /api/agent-activity durable activity-history API |
| Storage | PostgreSQL runtime storage, archive, migration compatibility, and file-backed payloads |
| Memory Backend Integration | Stash memory backend persistence: session capture, per-chat transcript backfill, and opt-in vector search |
| DAG Architecture Deliverables | Milestone A DAG architecture documents plus Milestone B prototype scaffold docs (schema migration plan, DagCoordinator design, implementation checklist) |
| Dev Server Module Audit | Analysis of parallel dashboard dev-server module families, production wiring, and consolidation guidance |
| Shared Cluster Protocol | Shared PostgreSQL multi-node contract: claims/leases, membership, auth, and retired multi-leader mesh replication |
| Signals Connectors | HMAC-signed external signal connectors for setup, payload mapping, and security notes across Sentry, Datadog, PagerDuty, and generic webhooks |
| Multi-Project Sequencing and Dependency Analysis | Sequencing guidance for FN-3448/FN-3449/FN-3503/FN-3182, including identity boundaries and recommended board dependency edges |
| Contributing | Local development setup, testing, release flow, and contributor conventions |
| Docker | Container builds, deployment, and persistence configuration |
| Code Signing | macOS and Windows code signing configuration for release binaries |
| Diagnostics | Engine diagnostic logging subsystems, structured log keys, and key diagnostic points catalog |
| Run-Audit Catalogue | Durable reference catalogue of delivery-pipeline run-audit events (finalization, self-healing reconciliation, durable-agent error-state) — the S4 reliability/durability/observability observability surface |
| Sandbox Backends | Pluggable sandbox backends for executor command isolation (bubblewrap, spawn-based) |
| Secrets | Encrypted secrets storage, per-secret access policies, scopes, and agent tool wiring |
| Testing | Full testing lanes, worker fanout guidance, test taxonomy, and file organization |
| Real iOS Safari Acceptance Surface | Provisioning runbook and harness usage for terminal verification gates on physical or cloud real-iOS Safari |
| Solutions Catalog | Documented solutions to past problems (bugs, architecture patterns, best practices) organized by category |
| Localization Contributing Guide | Conventions for contributing translations, locale file structure, and i18n tooling |
| Mobile | Capacitor/PWA mobile development setup and workflow |
Plugins
| Guide | Description |
|---|---|
| Plugin Management | End-user guide for discovering, installing, enabling, configuring, updating, uninstalling, and troubleshooting Fusion plugins |
| Plugin Authoring | Developer guide for building Fusion plugins (manifest, SDK hooks, routes, UI/runtime contributions) |
| Even Realities Glasses Plugin | Task-focused Even Realities glasses bridge with quick capture, polling notifications, and agent actions |
| Reports Plugin | Reports plugin rendering, export, standalone HTML generation, and section configuration |
| Even Realities Plugin API | Even Realities plugin API endpoint reference and test coverage matrix |
| Memory Plugin Contract | Pluggable memory backend architecture, interface contract, and migration strategy |
| Compound Engineering Plugin | CE workflow dashboard surface: artifact hub, interactive sessions, work→board bridge, and bidirectional sync |
| External Plugin Authoring | Step-by-step guide for authoring plugins using an installed fn CLI (no monorepo access needed) |
| External Plugin Proof-Point Runbook | Repeatable release-validation runbook for proving an external plugin runs against a published Fusion CLI build |
Audit Reports
| Report | Description |
|---|---|
| Test Feedback-Loop Baseline | Weekly FN-6612 signal-per-second baseline for gate/test wall-time, slowest files, and quarantine trends |
| Test Value Audit | Heuristic test-value audit generated by scripts/test-value-audit.mjs to support human deletion and review decisions |
| Test Velocity Baseline | Weekly feedback-loop velocity baseline for merge-gate, boot-smoke, changed-test, and quarantine metrics |
| UX Audit Report | Comprehensive UX audit with prioritized recommendations for dashboard improvements |
| Codebase Improvement Audit | Evidence-based technical debt and reliability gap audit with prioritized recommendations |
| Gap Analysis | System completeness analysis comparing Fusion to Paperclip feature set |
| Permanent Agent Heartbeat Playbooks | Worked manager/IC/message/blocked/no-task heartbeat scenarios and anti-patterns |
| Agent Sandbox Research | Research on agent isolation, capability enforcement, and sandboxing approaches |
| Even Realities Integration Research (FN-3737) | Research summary and recommended integration topology for Even Realities glasses + Fusion |
| pi-autoresearch Analysis for Fusion Port | Upstream architecture/license analysis and Fusion integration mapping for autoresearch capabilities |
| pi-autoresearch Audit vs Fusion Research | Audit comparing Fusion's research subsystem against upstream pi-autoresearch capabilities and parity gaps (FN-4136) |
| Research Hardening Preflight Baseline | Verified research subsystem baseline, lifecycle contracts, and hardening pressure points |
| Test Audit Report | Test coverage and effectiveness audit with recommendations |
| Skipped Test Inventory | Current intentional test-skip inventory and reconciliation status for older skip follow-ups |
| Dev Server Module Boundary Audit | Boundary/ownership audit for parallel dev-server-* vs devserver-* dashboard modules and FN-2212 prioritization guidance |
| spawn_agent Approval Evaluation (FN-3973) | Decision to keep fn_spawn_agent under generic action-gate governance rather than durable agent provisioning policy |
| Task Lineage Reconciliation Notes | Historical task-ID reuse patterns, confidence semantics for commit attribution, and reconciliation methodology (FN-3953, FN-3998) |
| Dashboard Load Performance (historical) | Pre-cutover SQLite index analysis retained for performance archaeology |
| CLI Printing Press Plugin Design | Architecture design for the CLI printing press bundled plugin (FN-3762) |
| CLI Printing Press Research | Upstream cli-printing-press analysis and Fusion integration mapping (FN-3761) |
| Research vs Experiment Session Naming Decision | Naming decision record: hybrid approach retaining research_* for cited-search/synthesis and adding experiment_session_* for upstream parity (FN-4223) |
| Experiment Executor Design | Experiment executor architecture: lifecycle, run state machine, and worktree isolation model |
| Experiment Finalize Flow | Experiment finalize contract: branch grouping, dry-run planning, and session completion semantics |
| Experiment Session Model | Experiment session data model: state transitions, iteration tracking, and persisted run state |
| Experiment Session MVP Spec | MVP specification for the experiment session feature: scope, invariants, and delivery milestones |
| Sandbox Options Research (FN-4635) | Pluggable sandbox options research: threat model, backend evaluation, and spawn-based isolation design |
| Triage Duplicate Detection Postmortem | Postmortem on duplicate task detection gaps and scheduler dedup hardening |
| Multi-Node Runtime Readiness (FN-4814) | Runtime readiness assessment for multi-node distributed coordination |
| Distributed Multi-Node Coordination Gap (FN-4819) | Gap analysis for distributed multi-node agent coordination and cross-node task assignment |
| Cross-Node Assignment Wake Contract (FN-4824) | Contract specification for cross-node task assignment wake signaling |
| Multi-Node Coordination Validation Findings (FN-4820) | Validation findings from multi-node coordination testing and edge-case analysis |
| Secrets Sync Auth Parity Review (FN-4886) | Review of node secrets sync API authentication parity and security boundaries |
| Test Speed Audit (FN-5048) | Measured baseline test performance, offender list, and optimization priorities |
| Soft-Delete Verification Matrix | Authoritative checklist for the FN-5105 → FN-5143 soft-delete stream: scenario × layer coverage |
| Self-Healing Backward Move Audit | Audit of self-healing backward-move safety checks and edge-case validation |
| Workflow Policy Ownership Map | U1 characterization map classifying production merge, retry, scheduling, and recovery policy branches before workflow-policy migration cutover |
| Test-Speed Baseline (2026-06-03) | Measured per-file test timing baseline and optimization targets (successor to FN-5048 audit) |
| ACP Runtime Contract | Agent Client Protocol plugin launch/readiness contract and failure taxonomy |
| ACP MCP Passthrough & Permission Forwarding Upstream Sponsorship (FN-6475) | Ready-to-file upstream sponsorship for claude-code-cli-acp ACP session/new.mcpServers passthrough and permission-gate traversal; Route A remains NOT GO until proven |
| Mission Completion Gate Contract | Decision record for mission completion gate invariants and acceptance flow |
| Lost-Work Tasks Incident (2026-05-23) | Incident catalog of 9 lost-work tasks from no-op finalize and reuse-handoff bugs |
| GitLab Parity Inventory (FN-7421) | Implementation map for first-class GitLab support: import, linked issue tracking, comments, auth/settings UI, CLI/extension, and Command Center surfaces to mirror or explicitly exclude |
| PostgreSQL Runtime Cutover Review (2026-07-14) | Current end-to-end authority inventory, intentional legacy SQLite readers, deployment contract, and verification record |
| SQLite → PostgreSQL Migration Review (2026-06-26, historical) | Historical multi-agent review of the incomplete migration branch and its original findings |
| Dashboard Theme & UI Plugin System Proposal (2026-07-01) | Feasibility-spike proposal for a controlled dashboard theme/UI shell extension point sharing one backend source of truth |
| Full-loop Agent Tool-Surface Audit and Delivery Plan | Source-grounded audit of engine-agent and dashboard chat tool factories, gap analysis for mission hierarchy integration, and delivery plan (FN-8280) |
| Dashboard Modal Inventory | Canonical classification of all 45 dashboard modal surfaces (classes A–D) with file:line evidence, FloatingWindow migration targets, and the shared migration contract (FN-8605 → FN-8617) |
| Workflow-Owned Lifecycle Closing Verification | Closing-bar verification runbook and recorded pass history for the workflow-owned lifecycle cutover programme — gate, verify:fast, E2E families, and census |
| Native spawn@:-1 Storm Source Attribution (RUFU-077) | Measured local contribution plus out-of-repo/native-dependency attribution for native spawn storms |
| Stash Vector/Semantic Search Evaluation (RUFU-126) | Decision record and opt-in prototype for Stash-backed vector/semantic recall; live-instance rollout is operator-gated |
External Resources
- GitHub repository: https://github.com/Runfusion/Fusion
- npm package: https://www.npmjs.com/package/@runfusion/fusion
- pi agent framework: https://github.com/earendil-works/pi
Suggested Reading Paths
-
New user: Getting Started → Dashboard Guide → Task Management
-
Workflow author: Dashboard Guide → Workflow Editor → Workflow Steps → Settings Reference
-
Power user / automation owner: Settings Reference → Workflow Steps → Agents → Planner Oversight (Settings Reference § Workflow Settings)
-
Maintainer / contributor: Architecture → Multi-Project → Contributing
-
Knowledge graph — deterministic committable codebase structure graph.