feat(FN-3863): add stash recovery dashboard surface and API routes

Merged FN-3863 brings stash recovery to the dashboard via three coordinated steps: engine-side orphan stash surfacing API in `merger.ts`, dashboard API routes for stash recovery data, and a new `StashRecoveryView` component with mobile support and inspect-diff row actions, integrated into the header

Fusion-Task-Id: FN-3863

packages/dashboard/src/routes/__tests__/stash-recovery-routes.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment node
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import express from "express";
+import type { TaskStore } from "@fusion/core";
+import { request as REQUEST } from "../../test-request.js";
+
+const engineMocks = vi.hoisted(() => ({
+  listAutostashOrphans: vi.fn(),
+  getAutostashDiff: vi.fn(),
+  applyAutostashBySha: vi.fn(),
+  dropAutostashBySha: vi.fn(),
+  notifyAutostashOrphans: vi.fn(),
+}));
+
+vi.mock("@fusion/engine", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@fusion/engine")>();
+  return {
+    ...actual,
+    ...engineMocks,
+  };
+});
+
+import { createApiRoutes } from "../../routes.js";
+
+function createMockStore(): TaskStore {
+  return {
+    getRootDir: vi.fn(() => "/tmp/project"),
+  } as unknown as TaskStore;
+}
+
+function buildApp(store: TaskStore) {
+  const app = express();
+  app.use(express.json());
+  app.use("/api", createApiRoutes(store));
+  return app;
+}
+
+describe("stash recovery routes", () => {
+  beforeEach(() => {
+    Object.values(engineMocks).forEach((mockFn) => mockFn.mockReset());
+  });
+
+  it("returns orphan records", async () => {
+    engineMocks.listAutostashOrphans.mockResolvedValue([
+      {
+        sha: "abcdef1",
+        ref: "stash@{0}",
+        label: "fusion-merger-autostash:FN-1:1",
+        sourceTaskId: "FN-1",
+        createdAt: null,
+        changedPaths: ["file.txt"],
+        classification: "live",
+      },
+    ]);
+
+    const res = await REQUEST(buildApp(createMockStore()), "GET", "/api/stash-recovery/orphans");
+    expect(res.status).toBe(200);
+    expect(res.body.count).toBe(1);
+    expect(res.body.records[0].sha).toBe("abcdef1");
+  });
+
+  it("returns diff + truncated flag", async () => {
+    engineMocks.getAutostashDiff.mockResolvedValue("diff text\n… (diff truncated)");
+    const res = await REQUEST(buildApp(createMockStore()), "GET", "/api/stash-recovery/orphans/abcdef1/diff");
+    expect(res.status).toBe(200);
+    expect(res.body.truncated).toBe(true);
+  });
+
+  it("applies stash with success and conflict responses", async () => {
+    engineMocks.applyAutostashBySha.mockResolvedValueOnce({ ok: true });
+    let res = await REQUEST(
+      buildApp(createMockStore()),
+      "POST",
+      "/api/stash-recovery/orphans/abcdef1/apply",
+      JSON.stringify({}),
+      { "content-type": "application/json" },
+    );
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ ok: true });
+
+    engineMocks.applyAutostashBySha.mockResolvedValueOnce({ ok: false, reason: "conflict", stderr: "CONFLICT" });
+    res = await REQUEST(
+      buildApp(createMockStore()),
+      "POST",
+      "/api/stash-recovery/orphans/abcdef1/apply",
+      JSON.stringify({}),
+      { "content-type": "application/json" },
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.ok).toBe(false);
+    expect(res.body.reason).toBe("conflict");
+  });
+
+  it("requires confirm for drop", async () => {
+    const app = buildApp(createMockStore());
+    let res = await REQUEST(
+      app,
+      "POST",
+      "/api/stash-recovery/orphans/abcdef1/drop",
+      JSON.stringify({}),
+      { "content-type": "application/json" },
+    );
+    expect(res.status).toBe(400);
+
+    engineMocks.dropAutostashBySha.mockResolvedValueOnce({ dropped: true });
+    res = await REQUEST(
+      app,
+      "POST",
+      "/api/stash-recovery/orphans/abcdef1/drop",
+      JSON.stringify({ confirm: true }),
+      { "content-type": "application/json" },
+    );
+    expect(res.status).toBe(200);
+    expect(engineMocks.dropAutostashBySha).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects invalid sha before calling engine", async () => {
+    const res = await REQUEST(buildApp(createMockStore()), "GET", "/api/stash-recovery/orphans/not-valid/diff");
+    expect(res.status).toBe(400);
+    expect(engineMocks.getAutostashDiff).not.toHaveBeenCalled();
+  });
+});

packages/dashboard/src/routes/register-integrated-routers.ts

@@ -8,6 +8,7 @@ import { createResearchRouter } from "../research-routes.js";
 import { createTodoRouter } from "../todo-routes.js";
 import { createDevServerRouter } from "../dev-server-routes.js";
 import type { AiSessionStore } from "../ai-session-store.js";
+import { createStashRecoveryRouter } from "./register-stash-recovery-routes.js";
 
 interface IntegratedRoutersOptions {
   router: Router;
@@ -36,6 +37,7 @@ export function registerIntegratedRouters({
   router.use("/evals", createEvalsRouter(store));
   router.use("/research", createResearchRouter(store));
   router.use("/todos", createTodoRouter(store));
+  router.use("/stash-recovery", createStashRecoveryRouter(store));
 }
 
 export function registerIntegratedDevServerRouter({ router, store }: DevServerRouterOptions): void {

packages/dashboard/src/routes/register-stash-recovery-routes.ts

@@ -0,0 +1,68 @@
+import { Router, type Request, type Response } from "express";
+import type { TaskStore } from "@fusion/core";
+import {
+  applyAutostashBySha,
+  dropAutostashBySha,
+  getAutostashDiff,
+  listAutostashOrphans,
+  notifyAutostashOrphans,
+} from "@fusion/engine";
+import { badRequest } from "../api-error.js";
+
+const SHA_RE = /^[0-9a-f]{7,40}$/;
+
+function validateSha(sha: string): boolean {
+  return SHA_RE.test(sha);
+}
+
+function getRootDir(store: TaskStore): string {
+  return store.getRootDir();
+}
+
+export function createStashRecoveryRouter(store: TaskStore): Router {
+  const router = Router();
+
+  router.get("/orphans", async (_req: Request, res: Response) => {
+    const rootDir = getRootDir(store);
+    const records = await listAutostashOrphans(rootDir);
+    res.json({ count: records.length, records, rootDir });
+  });
+
+  router.get("/orphans/:sha/diff", async (req: Request, res: Response) => {
+    const sha = String(req.params.sha ?? "").trim();
+    if (!validateSha(sha)) throw badRequest("Invalid stash sha");
+    const rootDir = getRootDir(store);
+    const diff = await getAutostashDiff(rootDir, sha);
+    const truncated = diff.includes("… (diff truncated)");
+    res.json({ sha, diff, truncated });
+  });
+
+  router.post("/orphans/:sha/apply", async (req: Request, res: Response) => {
+    const sha = String(req.params.sha ?? "").trim();
+    if (!validateSha(sha)) throw badRequest("Invalid stash sha");
+    const rootDir = getRootDir(store);
+    const result = await applyAutostashBySha(rootDir, sha);
+    res.status(200).json(result);
+  });
+
+  router.post("/orphans/:sha/drop", async (req: Request, res: Response) => {
+    const sha = String(req.params.sha ?? "").trim();
+    if (!validateSha(sha)) throw badRequest("Invalid stash sha");
+    if (req.body?.confirm !== true) throw badRequest("confirm: true is required");
+    const rootDir = getRootDir(store);
+    const result = await dropAutostashBySha(rootDir, "stash-recovery", sha);
+    if (!result.dropped) {
+      res.status(200).json({ ok: false, reason: result.reason ?? "drop_failed" });
+      return;
+    }
+    res.status(200).json({ ok: true });
+  });
+
+  router.post("/refresh", async (_req: Request, res: Response) => {
+    const rootDir = getRootDir(store);
+    const records = await notifyAutostashOrphans(store, rootDir);
+    res.json({ count: records.length, records, rootDir });
+  });
+
+  return router;
+}