feat(FN-2564): merge fusion/fn-2564 (auto-resolved)

- feat(FN-2564): complete Step 5 — update routing docs
- feat(FN-2564): complete Step 1 — stabilize registrar wiring

packages/dashboard/src/routes.ts

@@ -13,8 +13,6 @@ import * as nodeFs from "node:fs";
 import type { TaskStore, ScheduleType, ActivityEventType, ModelPreset, RoutineTriggerType } from "@fusion/core";
 import { type Task, type PiExtensionEntry, type PiExtensionSettings, AutomationStore, RoutineStore, isWebhookTrigger, MemoryBackendError, listAgentMemoryFiles, readAgentMemoryFile, writeAgentMemoryFile, discoverPiExtensions, getFusionAgentDir, getLegacyPiAgentDir } from "@fusion/core";
 import type { ServerOptions } from "./server.js";
-import { terminalSessionManager } from "./terminal.js";
-import { getTerminalService } from "./terminal-service.js";
 import { verifyWebhookSignature } from "./github-webhooks.js";
 import { AiSessionStore, SESSION_CLEANUP_DEFAULT_MAX_AGE_MS } from "./ai-session-store.js";
 import { getSession as getPlanningSession, cleanupSession as cleanupPlanningSession } from "./planning.js";
@@ -42,7 +40,7 @@ import { registerChatRoutes } from "./routes/register-chat-routes.js";
 import { registerSettingsMemoryRoutes } from "./routes/register-settings-memory-routes.js";
 import { registerMessagingScriptRoutes } from "./routes/register-messaging-scripts.js";
 import { registerGitGitHubRoutes } from "./routes/register-git-github.js";
-import { registerFileWorkspaceRoutes } from "./routes/register-file-workspace-routes.js";
+import { registerFilesTerminalWorkspaceRoutes } from "./routes/register-files-terminal-workspaces.js";
 import { registerAgentsProjectsNodesRoutes } from "./routes/register-agents-projects-nodes.js";
 import { registerProjectRoutes } from "./routes/register-project-routes.js";
 import { registerNodeRoutes } from "./routes/register-node-routes.js";
@@ -61,8 +59,6 @@ import { registerModelRoutes } from "./routes/register-model-routes.js";
 import { registerUsageRoutes } from "./routes/register-usage-routes.js";
 import { registerAuthRoutes } from "./routes/register-auth-routes.js";
 import { registerIntegratedRouters, registerIntegratedDevServerRouter } from "./routes/register-integrated-routers.js";
-import { registerTerminalRoutes } from "./routes/register-terminal-routes.js";
-import { registerSessionDiffRoutes } from "./routes/register-session-diff-routes.js";
 import { runGitCommand } from "./routes/resolve-diff-base.js";
 
 const TASK_DETAIL_ACTIVITY_LOG_LIMIT = 500;
@@ -894,8 +890,7 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
   });
   registerMessagingScriptRoutes(routeContext);
   registerGitGitHubRoutes(routeContext);
-  registerSessionDiffRoutes(router, { getProjectContext });
-  registerFileWorkspaceRoutes(routeContext);
+  registerFilesTerminalWorkspaceRoutes(routeContext);
   registerAgentsProjectsNodesRoutes(routeContext);
   registerPluginsAutomationRoutes(routeContext);
 
@@ -1261,12 +1256,6 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
   // ---------- Auth routes ----------
   registerAuthRoutes(routeContext);
 
-  registerTerminalRoutes(router, {
-    getProjectContext,
-    terminalSessionManager,
-    getTerminalService,
-  });
-
   /**
    * POST /api/ai/refine-text
    * AI-powered text refinement for task descriptions.

packages/dashboard/src/routes/README.md

@@ -43,6 +43,10 @@ The context provides core cross-cutting plumbing:
 - `register-model-routes.ts` — `/models` endpoint, favorites projection, and `useClaudeCli` filtering for `pi-claude-cli` entries
 - `register-auth-routes.ts` — auth/provider domain (`/auth/status`, `/auth/login`, `/auth/logout`, `/auth/api-key`, `/auth/claude-cli`, `/providers/claude-cli/status`)
 - `register-usage-routes.ts` — `/usage` endpoint with `fetchAllProviderUsage(options?.authStorage)` integration
+- `register-files-terminal-workspaces.ts` — infrastructure aggregator for file/workspace + session-diff + terminal routes
+  - Calls `register-session-diff-routes.ts` first (session changed files + task diff endpoints)
+  - Calls `register-file-workspace-routes.ts` second (task/workspace file browsing and file operations)
+  - Calls `register-terminal-routes.ts` last (terminal command/session + PTY lifecycle endpoints)
 - `register-file-workspace-routes.ts` — task/workspace file domain:
   - Task files: `/tasks/:id/files`, `/tasks/:id/files/{*filepath}` (read/write)
   - Workspace discovery/files: `/workspaces`, `/files`, `/files/markdown-list`, `/files/search`, `/files/{*filepath}`
@@ -77,6 +81,28 @@ The context provides core cross-cutting plumbing:
     6. `ALL /proxy/:nodeId/{*splat}` (generic wildcard forwarder)
   - Shared diagnostics: imports `emitRemoteRouteDiagnostic` and `classifyRemoteRouteError` from `routes/context.ts` so proxy and non-proxy registrars (for example mesh/sync routes) keep one diagnostic classification contract.
 
+## createApiRoutes mount sequence (current)
+
+`createApiRoutes()` mounts registrars in this precedence-sensitive order:
+
+1. `registerSettingsMemoryRoutes(...)`
+2. `registerTaskWorkflowRoutes(...)`
+3. `registerPlanningSubtaskRoutes(...)`
+4. `registerChatRoutes(...)`
+5. `registerMessagingScriptRoutes(...)`
+6. `registerGitGitHubRoutes(...)`
+7. `registerFilesTerminalWorkspaceRoutes(...)`
+8. `registerAgentsProjectsNodesRoutes(...)`
+9. `registerPluginsAutomationRoutes(...)`
+10. (later) `registerAgentSkillsRoutes(...)`
+11. (last) `registerProxyRoutes(...)`
+
+Compatibility re-exports that must remain on `routes.ts` for tests and existing importers:
+
+- `resolveDiffBase` + `ResolveDiffBaseTaskInput` (from `resolve-diff-base.ts`)
+- `__resetBatchImportRateLimiter` (from `register-git-github.ts`)
+- `__setCreateFnAgentForRefine` (defined in `routes.ts`)
+
 ## Ordering rules (critical)
 
 Express matches in registration order. Keep registrar and in-registrar route ordering stable:

packages/dashboard/src/routes/register-files-terminal-workspaces.ts

@@ -1,5 +1,26 @@
+import { terminalSessionManager } from "../terminal.js";
+import { getTerminalService } from "../terminal-service.js";
+import { registerFileWorkspaceRoutes } from "./register-file-workspace-routes.js";
+import { registerSessionDiffRoutes } from "./register-session-diff-routes.js";
+import { registerTerminalRoutes } from "./register-terminal-routes.js";
 import type { ApiRoutesContext } from "./types.js";
 
-export function registerFilesTerminalWorkspaceRoutes(_ctx: ApiRoutesContext): void {
-  // Step scaffold: route extraction lands in subsequent steps.
+/**
+ * Registers filesystem/workspace, session-diff, and terminal infrastructure routes.
+ *
+ * Ordering is part of the API contract:
+ * 1) session/diff routes
+ * 2) file/workspace routes
+ * 3) terminal routes
+ */
+export function registerFilesTerminalWorkspaceRoutes(ctx: ApiRoutesContext): void {
+  const { router, getProjectContext } = ctx;
+
+  registerSessionDiffRoutes(router, { getProjectContext });
+  registerFileWorkspaceRoutes(ctx);
+  registerTerminalRoutes(router, {
+    getProjectContext,
+    terminalSessionManager,
+    getTerminalService,
+  });
 }