feat(FN-4153): complete Steps 7-8 — verify gates and document toggle

Fusion-Task-Id: FN-4153
Fusion-Task-Lineage: 6ec09467-c7a0-4a9d-9a09-16d5ef6f7a86

.changeset/FN-4153-ephemeral-agents-toggle.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": minor
+---
+
+Add a General setting (`ephemeralAgentsEnabled`, default true) to toggle ephemeral task-worker agent usage. When disabled, the scheduler auto-assigns every dispatchable task to a permanent executor based on the agent reporting chain and refuses to spawn `executor-FN-XXXX` workers.

docs/settings-reference.md

@@ -243,6 +243,7 @@ Override precedence for direct merges is:
 | `verificationFixRetries` | `number` | `3` | In-merge auto-fix retry attempts after deterministic test/build verification failures (0-3). |
 | `buildTimeoutMs` | `number` | `300000` | Build timeout in milliseconds (5 minutes). |
 | `requirePlanApproval` | `boolean` | `false` | Require manual approval before planning → todo. |
+| `ephemeralAgentsEnabled` | `boolean` | `true` | When enabled (default), Fusion spawns short-lived `executor-FN-XXXX` workers for task execution. When disabled, only permanent executor agents run tasks; the scheduler auto-assigns dispatchable tasks using reporting-chain-aware load balancing, and tasks stay queued until an eligible permanent executor is available. |
 | `agentProvisioning` | `{ approvalMode?: "always" \| "trusted-only" \| "never"; trustedRoles?: string[]; trustedAgentIds?: string[]; alwaysApproveDelete?: boolean }` | `{}` | Approval policy for `fn_agent_create`/`fn_agent_delete` (`approvalMode` default `trusted-only`, delete approvals default on via `alwaysApproveDelete: true`). |
 | `completionDocumentationMode` | `"off" \| "changeset" \| "changelog"` | `"off"` | Controls triage prompt injection for release-note artifacts in future task specs. `"changeset"` requires `.changeset/*.md` workflow guidance; `"changelog"` requires updating an existing changelog file (without inventing a new one); `"off"` disables this automation. |
 | `specStalenessEnabled` | `boolean` | `false` | Enforce automatic re-planning for stale plans. |

packages/engine/src/__tests__/agent-assignment.test.ts

@@ -4,7 +4,6 @@ import { selectPermanentAgentForTask } from "../agent-assignment.js";
 
 function makeAgent(overrides: Partial<Agent> & Pick<Agent, "id">): Agent {
   return {
-    id: overrides.id,
     name: overrides.name ?? overrides.id,
     role: overrides.role ?? "executor",
     state: overrides.state ?? "idle",
@@ -17,7 +16,6 @@ function makeAgent(overrides: Partial<Agent> & Pick<Agent, "id">): Agent {
 
 function makeTask(overrides: Partial<Task> & Pick<Task, "id">): Task {
   return {
-    id: overrides.id,
     title: overrides.title ?? overrides.id,
     description: overrides.description ?? "",
     column: overrides.column ?? "todo",

packages/engine/src/__tests__/scheduler-ephemeral-toggle.test.ts

@@ -31,7 +31,6 @@ function makeTask(overrides: Partial<Task> = {}): Task {
 
 function makeAgent(overrides: Partial<Agent> & Pick<Agent, "id">): Agent {
   return {
-    id: overrides.id,
     name: overrides.name ?? overrides.id,
     role: overrides.role ?? "executor",
     state: overrides.state ?? "idle",