@mrpatronz/nexusflow 0.2.18 → 0.2.19

package/src/core/workspace-state.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import {
+  loadWorkspaceState,
+  recordRepoSync,
+  markValidated,
+} from './workspace-state.js';
+import type { WorkspaceState } from '../types.js';
+
+vi.mock('node:fs/promises');
+
+/** Parses the JSON written by the most recent writeFile call. */
+function lastWritten(): WorkspaceState {
+  const calls = vi.mocked(fs.writeFile).mock.calls;
+  const data = calls[calls.length - 1][1] as string;
+  return JSON.parse(data) as WorkspaceState;
+}
+
+describe('workspace-state', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+  });
+
+  describe('loadWorkspaceState', () => {
+    it('returns an empty skeleton when the file is absent', async () => {
+      vi.mocked(fs.readFile).mockRejectedValue(new Error('ENOENT'));
+
+      const state = await loadWorkspaceState('/ws');
+
+      expect(state.workspacePath).toBe('/ws');
+      expect(state.repos).toEqual({});
+    });
+
+    it('round-trips an existing state file', async () => {
+      const existing: WorkspaceState = {
+        workspacePath: '/ws',
+        repos: { api: { repoName: 'api', lastSyncStatus: 'rebased' } },
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      };
+      vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(existing) as any);
+
+      const state = await loadWorkspaceState('/ws');
+
+      expect(state.repos.api.lastSyncStatus).toBe('rebased');
+    });
+  });
+
+  describe('recordRepoSync', () => {
+    beforeEach(() => {
+      vi.mocked(fs.readFile).mockRejectedValue(new Error('ENOENT'));
+    });
+
+    it('sets pendingValidation when a repo was rebased', async () => {
+      const entry = await recordRepoSync('/ws', 'api', {
+        status: 'rebased',
+        message: 'Rebased onto latest base',
+      });
+
+      expect(entry.pendingValidation).toBe(true);
+      expect(entry.lastSyncStatus).toBe('rebased');
+      expect(entry.lastSyncedAt).toBeTruthy();
+      expect(lastWritten().repos.api.pendingValidation).toBe(true);
+    });
+
+    it('does not set pendingValidation for an up-to-date repo', async () => {
+      const entry = await recordRepoSync('/ws', 'api', {
+        status: 'up-to-date',
+        message: 'Up to date',
+      });
+
+      expect(entry.pendingValidation).toBe(false);
+    });
+
+    it('preserves a prior pending flag on a later no-op sync', async () => {
+      const existing: WorkspaceState = {
+        workspacePath: '/ws',
+        repos: { api: { repoName: 'api', pendingValidation: true } },
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      };
+      vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(existing) as any);
+
+      const entry = await recordRepoSync('/ws', 'api', {
+        status: 'up-to-date',
+        message: 'Up to date',
+      });
+
+      expect(entry.pendingValidation).toBe(true);
+    });
+  });
+
+  describe('markValidated', () => {
+    it('records the result and clears the pending flag', async () => {
+      const existing: WorkspaceState = {
+        workspacePath: '/ws',
+        repos: { api: { repoName: 'api', pendingValidation: true } },
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      };
+      vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(existing) as any);
+
+      const entry = await markValidated('/ws', 'api', 'pass');
+
+      expect(entry.lastValidationResult).toBe('pass');
+      expect(entry.pendingValidation).toBe(false);
+      expect(entry.lastValidatedAt).toBeTruthy();
+    });
+  });
+});

package/src/core/workspace-state.ts

@@ -0,0 +1,130 @@
+/**
+ * @module core/workspace-state
+ * Persists per-repo sync/validation state for a workspace in a single
+ * `.nexusflow-state.json` file at the workspace root.
+ *
+ * Mirrors the lightweight state-file pattern used by `orchestration/runner.ts`
+ * for running services. Tracks, per repo: when it was last synced, the
+ * classified result, whether it is pending re-validation, and the last
+ * validation outcome — so agents no longer need to hand-roll their own state.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import type { RepoSyncState, SyncStatus, WorkspaceState } from '../types.js';
+
+/** Name of the per-repo state file, written at the workspace root. */
+const STATE_FILE = '.nexusflow-state.json';
+
+/**
+ * Returns the path to the workspace state file.
+ */
+function getStatePath(workspacePath: string): string {
+  return path.join(workspacePath, STATE_FILE);
+}
+
+/**
+ * Loads the workspace state from disk, returning an empty skeleton when the
+ * file does not exist or cannot be parsed.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ */
+export async function loadWorkspaceState(
+  workspacePath: string,
+): Promise<WorkspaceState> {
+  try {
+    const raw = await fs.readFile(getStatePath(workspacePath), 'utf-8');
+    const state = JSON.parse(raw) as WorkspaceState;
+    // Defend against a malformed/legacy file lacking the repos map.
+    if (!state.repos || typeof state.repos !== 'object') {
+      state.repos = {};
+    }
+    state.workspacePath = workspacePath;
+    return state;
+  } catch {
+    return {
+      workspacePath,
+      repos: {},
+      updatedAt: new Date().toISOString(),
+    };
+  }
+}
+
+/**
+ * Saves the workspace state to disk.
+ *
+ * @param state - The state to persist. Its `updatedAt` is refreshed on write.
+ */
+export async function saveWorkspaceState(state: WorkspaceState): Promise<void> {
+  const toWrite: WorkspaceState = { ...state, updatedAt: new Date().toISOString() };
+  const data = JSON.stringify(toWrite, null, 2) + '\n';
+  await fs.writeFile(getStatePath(state.workspacePath), data, 'utf-8');
+}
+
+/**
+ * Records the outcome of a sync attempt for a single repo and persists it.
+ *
+ * Sets `pendingValidation` to true when new commits were pulled in
+ * (`status === 'rebased'`), signalling that the repo should be re-validated.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ * @param repoName      - Directory name of the repo.
+ * @param result        - The classified sync status and message.
+ * @returns The updated per-repo state entry.
+ */
+export async function recordRepoSync(
+  workspacePath: string,
+  repoName: string,
+  result: { status: SyncStatus; message: string },
+): Promise<RepoSyncState> {
+  const state = await loadWorkspaceState(workspacePath);
+  const existing = state.repos[repoName] ?? { repoName };
+
+  const updated: RepoSyncState = {
+    ...existing,
+    repoName,
+    lastSyncedAt: new Date().toISOString(),
+    lastSyncStatus: result.status,
+    lastSyncMessage: result.message,
+    // New commits landed → the repo needs re-validation. Preserve an existing
+    // pending flag otherwise (a no-op sync doesn't clear prior pending work).
+    pendingValidation:
+      result.status === 'rebased' ? true : existing.pendingValidation ?? false,
+  };
+
+  state.repos[repoName] = updated;
+  await saveWorkspaceState(state);
+  return updated;
+}
+
+/**
+ * Records the result of a validation run (e.g. tests/e2e) for a repo and clears
+ * its pending-validation flag. Provided for the validation flow that consumes
+ * `pendingValidation`.
+ *
+ * @param workspacePath - Absolute path to the workspace root.
+ * @param repoName      - Directory name of the repo.
+ * @param result        - Whether validation passed or failed.
+ * @returns The updated per-repo state entry.
+ */
+export async function markValidated(
+  workspacePath: string,
+  repoName: string,
+  result: 'pass' | 'fail',
+): Promise<RepoSyncState> {
+  const state = await loadWorkspaceState(workspacePath);
+  const existing = state.repos[repoName] ?? { repoName };
+
+  const updated: RepoSyncState = {
+    ...existing,
+    repoName,
+    lastValidationResult: result,
+    lastValidatedAt: new Date().toISOString(),
+    pendingValidation: false,
+  };
+
+  state.repos[repoName] = updated;
+  await saveWorkspaceState(state);
+  return updated;
+}

package/src/mcp/server.ts

@@ -9,6 +9,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { loadConfig } from '../core/config.js';
 import { loadFeatureConfig } from '../core/workspace.js';
+import { syncWorkspace } from '../core/sync.js';
 import { callLocalLlm } from '../utils/local-ai.js';
 
 export async function startMcpServer(workspacePath?: string) {
@@ -45,6 +46,19 @@ export async function startMcpServer(workspacePath?: string) {
           required: ['query'],
         },
       },
+      {
+        name: 'sync_workspace',
+        description: 'Rebase every repository in the NexusFlow workspace onto its base branch. Safe to call non-interactively: dirty working trees are auto-stashed and restored, so a dirty tree is never mis-reported as a conflict. Returns structured per-repo results (status: up-to-date | rebased | conflict | stash-conflict | error) and records them to the workspace state file.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            workspaceId: {
+              type: 'string',
+              description: 'Optional ID/branchName of the workspace to sync. If omitted, uses the currently active workspace.',
+            },
+          },
+        },
+      },
       {
         name: 'get_service_logs',
         description: 'Get the recent logs for a specific running service in the workspace to debug runtime issues.',
@@ -239,6 +253,36 @@ export async function startMcpServer(workspacePath?: string) {
       }
     }
 
+    if (name === 'sync_workspace') {
+      try {
+        const feature = await loadFeatureConfig(resolvedWorkspacePath);
+        if (!feature) {
+          throw new Error(`Workspace not found at ${resolvedWorkspacePath}. Make sure you are in a NexusFlow workspace or provide a valid workspaceId.`);
+        }
+
+        const report = await syncWorkspace(resolvedWorkspacePath);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(report, null, 2),
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error syncing workspace: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+
     if (name === 'get_service_logs') {
       const serviceName = (args as any).serviceName;
       const lines = (args as any).lines || 50;

package/src/server.ts

@@ -21,6 +21,7 @@ import { loadConfig, saveConfig, getConfigDir } from './core/config.js';
 import { listStorageProviders } from './core/adapters/registry.js';
 import { scanForRepos } from './core/scanner.js';
 import { createWorkspace, listWorkspaces, loadFeatureConfig, deleteWorkspace, addRepoToWorkspace } from './core/workspace.js';
+import { loadWorkspaceState } from './core/workspace-state.js';
 import { analyzeAllRepos } from './analyzers/index.js';
 import { generateContextFiles } from './generators/index.js';
 import { isOllamaModelAvailable, getOpenAiCompatibleUrl, callLocalLlm } from './utils/local-ai.js';
@@ -28,7 +29,8 @@ import { detectAIAssistants } from './utils/detect-ai.js';
 import { detectEditors } from './utils/detect-editors.js';
 import { findSessions, getSessionTranscript } from './utils/session-finder.js';
 import { scanSystemSpecs } from './utils/system-scanner.js';
-import { getWorkspaceRepos, rebaseRepo, commitAndPush, getRepoStatus } from './utils/multi-git.js';
+import { getWorkspaceRepos, commitAndPush, getRepoStatus } from './utils/multi-git.js';
+import { syncWorkspace } from './core/sync.js';
 import {
   detectAllServices,
   detectOrchestrationTools,
@@ -38,7 +40,7 @@ import {
 } from './orchestration/index.js';
 import { checkForUpdates, getCurrentVersion, getToolsStatus } from './utils/update-check.js';
 import { getWorkflowTemplates, saveWorkflowTemplate, deleteWorkflowTemplate } from './utils/workflows.js';
-import type { Feature, RepoInfo, WorkspaceContext } from './types.js';
+import type { Feature, RepoInfo, WorkspaceContext, SyncStatus, RepoSyncState } from './types.js';
 import { suggestWorkflow } from './utils/workflow-advisor.js';
 
 // Resolve static files directory
@@ -149,6 +151,91 @@ app.get('/api/workspaces', async (c) => {
   }
 });
 
+// Severity ranking for picking the worst per-repo sync outcome in a workspace.
+const SYNC_SEVERITY: Record<SyncStatus, number> = {
+  conflict: 4,
+  'stash-conflict': 3,
+  error: 2,
+  rebased: 1,
+  'up-to-date': 0,
+};
+
+/** Returns the most severe recorded sync status across a workspace's repos. */
+function worstSyncStatus(states: RepoSyncState[]): SyncStatus | 'unknown' {
+  let worst: SyncStatus | 'unknown' = 'unknown';
+  let worstSeverity = -1;
+  for (const s of states) {
+    if (!s.lastSyncStatus) continue;
+    const severity = SYNC_SEVERITY[s.lastSyncStatus];
+    if (severity > worstSeverity) {
+      worstSeverity = severity;
+      worst = s.lastSyncStatus;
+    }
+  }
+  return worst;
+}
+
+// 4b. Aggregate at-a-glance status for every workspace (for the listing overview).
+// Cheap on purpose: git status + cached running/sync state only — never fetch/rebase.
+app.get('/api/workspaces/status', async (c) => {
+  try {
+    const config = await loadConfig();
+    const workspaces = await listWorkspaces(config.workspacesDir);
+
+    const entries = await Promise.all(
+      workspaces.map(async (ws) => {
+        const workspacePath =
+          ws.workspacePath || path.join(config.workspacesDir, ws.branchName);
+        const status = {
+          id: ws.id,
+          branchName: ws.branchName,
+          changedFiles: 0,
+          dirtyRepos: 0,
+          runningServices: 0,
+          syncStatus: 'unknown' as SyncStatus | 'unknown',
+          pendingValidation: false,
+        };
+
+        try {
+          // Uncommitted changes across the workspace's repo worktrees.
+          for (const repoPath of ws.repos) {
+            const worktreePath = path.join(workspacePath, path.basename(repoPath));
+            const repoStatus = await getRepoStatus(worktreePath);
+            if (repoStatus.hasChanges) {
+              status.dirtyRepos += 1;
+              status.changedFiles += repoStatus.changedFiles.length;
+            }
+          }
+
+          // Running services (cached running-state, PM2-verified — same source as
+          // the Services tab; only workspaces that ever started services touch PM2).
+          const runningState = await loadRunningState(workspacePath);
+          status.runningServices = runningState?.services?.length ?? 0;
+
+          // Sync state: worst-case classification + any repo pending validation.
+          const wsState = await loadWorkspaceState(workspacePath);
+          const repoStates = Object.values(wsState.repos);
+          status.syncStatus = worstSyncStatus(repoStates);
+          status.pendingValidation = repoStates.some((r) => r.pendingValidation);
+        } catch {
+          // Leave defaults on any per-workspace failure so one bad repo doesn't
+          // fail the whole response.
+        }
+
+        return status;
+      })
+    );
+
+    // Keyed by branchName to match how the GUI looks up a workspace.
+    const byWorkspace: Record<string, (typeof entries)[number]> = {};
+    for (const entry of entries) byWorkspace[entry.branchName] = entry;
+    return c.json(byWorkspace);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+  }
+});
+
 // 5. Detect available AI assistants
 app.get('/api/ai-detect', async (c) => {
   try {
@@ -861,20 +948,21 @@ app.post('/api/workspace/:id/sync', async (c) => {
     const config = await loadConfig();
     const workspacePath = path.join(config.workspacesDir, id);
 
-    const repos = await getWorkspaceRepos(workspacePath);
-    const results = [];
-
-    for (const repo of repos) {
-      const result = await rebaseRepo(repo.path, repo.defaultBranch || 'main');
-      results.push({
-        repoName: repo.name,
-        success: result.success,
-        message: result.message,
-        conflict: result.conflict,
-      });
-    }
+    const report = await syncWorkspace(workspacePath);
+    const results = report.repos.map((repo) => ({
+      repoName: repo.name,
+      success: repo.status !== 'conflict' && repo.status !== 'error',
+      status: repo.status,
+      message: repo.message,
+      conflict: repo.conflict,
+    }));
 
-    return c.json({ results });
+    return c.json({
+      results,
+      syncedCount: report.syncedCount,
+      conflictCount: report.conflictCount,
+      errorCount: report.errorCount,
+    });
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
     return c.json({ error: msg }, 500);

package/src/types.ts

@@ -397,6 +397,42 @@ export interface RunningState {
   updatedAt: string;
 }
 
+// ─── Per-Repo Sync State ──────────────────────────────────────────────────
+
+/**
+ * Classified outcome of a sync/rebase attempt for a single repo.
+ * See `utils/multi-git.ts` for the meaning of each value.
+ */
+export type SyncStatus = 'up-to-date' | 'rebased' | 'conflict' | 'stash-conflict' | 'error';
+
+/** Persisted sync/validation state for a single repo in a workspace. */
+export interface RepoSyncState {
+  /** Directory name of the repo. */
+  repoName: string;
+  /** ISO timestamp of the last sync attempt. */
+  lastSyncedAt?: string;
+  /** Classified result of the last sync. */
+  lastSyncStatus?: SyncStatus;
+  /** Human-readable message from the last sync. */
+  lastSyncMessage?: string;
+  /** True when the repo pulled in new commits and has not yet been re-validated. */
+  pendingValidation?: boolean;
+  /** Result of the last validation run (e.g. test/e2e), if any. */
+  lastValidationResult?: 'pass' | 'fail' | null;
+  /** ISO timestamp of the last validation run. */
+  lastValidatedAt?: string;
+}
+
+/** State file saved to track per-repo sync/validation status (`.nexusflow-state.json`). */
+export interface WorkspaceState {
+  /** Workspace path this state belongs to. */
+  workspacePath: string;
+  /** Per-repo state, keyed by repo name. */
+  repos: Record<string, RepoSyncState>;
+  /** Timestamp when the state was last updated. */
+  updatedAt: string;
+}
+
 // ─── Phase 3: Dependency Graph Types ──────────────────────────────────────
 
 /** A node in the workspace dependency graph. */

package/src/utils/multi-git.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { execa } from 'execa';
+import { rebaseRepo } from './multi-git.js';
+
+vi.mock('execa');
+
+/** Builds an execa-style error carrying stderr (as execa does on non-zero exit). */
+function gitError(stderr: string): Error {
+  return Object.assign(new Error('git failed'), { stderr });
+}
+
+interface GitMockOpts {
+  fetchError?: Error;
+  statusStdout?: string;      // output of `git status --porcelain` ('' = clean)
+  stashPushError?: Error;
+  stashPopError?: Error;
+  rebaseError?: Error;
+  rebaseStdout?: string;
+}
+
+/** Resolves a single mocked `git` call by subcommand. */
+async function routeGit(a: string[], opts: GitMockOpts): Promise<{ stdout: string }> {
+  const sub = a[0];
+  if (sub === 'fetch') {
+    if (opts.fetchError) throw opts.fetchError;
+    return { stdout: '' };
+  }
+  if (sub === 'status') {
+    return { stdout: opts.statusStdout ?? '' };
+  }
+  if (sub === 'stash' && a[1] === 'push') {
+    if (opts.stashPushError) throw opts.stashPushError;
+    return { stdout: '' };
+  }
+  if (sub === 'stash' && a[1] === 'pop') {
+    if (opts.stashPopError) throw opts.stashPopError;
+    return { stdout: '' };
+  }
+  if (sub === 'rebase' && a[1] === '--abort') {
+    return { stdout: '' };
+  }
+  if (sub === 'rebase') {
+    if (opts.rebaseError) throw opts.rebaseError;
+    return { stdout: opts.rebaseStdout ?? 'Successfully rebased.' };
+  }
+  return { stdout: '' };
+}
+
+/** Routes mocked `git` calls by subcommand so each test declares only what matters. */
+function mockGit(opts: GitMockOpts): void {
+  vi.mocked(execa).mockImplementation(((_file: any, args: any) =>
+    routeGit(args as string[], opts)) as any);
+}
+
+/** Returns the recorded execa calls as arrays of git args. */
+function gitCalls(): string[][] {
+  return vi.mocked(execa).mock.calls.map((c) => c[1] as string[]);
+}
+
+describe('rebaseRepo', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('reports "rebased" for a clean tree with new base commits', async () => {
+    mockGit({ statusStdout: '', rebaseStdout: 'Successfully rebased and updated.' });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    expect(result.success).toBe(true);
+    expect(result.status).toBe('rebased');
+    expect(result.stashed).toBeFalsy();
+    // No stash should be created for a clean tree.
+    expect(gitCalls().some((c) => c[0] === 'stash')).toBe(false);
+  });
+
+  it('reports "up-to-date" when already current', async () => {
+    mockGit({ statusStdout: '', rebaseStdout: 'Current branch feature is up to date.' });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    expect(result.success).toBe(true);
+    expect(result.status).toBe('up-to-date');
+  });
+
+  it('auto-stashes a dirty tree and restores it (the regression fix)', async () => {
+    mockGit({ statusStdout: ' M src/app.ts\n', rebaseStdout: 'Successfully rebased.' });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    expect(result.success).toBe(true);
+    expect(result.status).toBe('rebased');
+    expect(result.stashed).toBe(true);
+
+    const calls = gitCalls();
+    // Stash push (with untracked) before rebase, stash pop after.
+    expect(calls).toContainEqual(['stash', 'push', '-u', '-m', 'nexusflow-autostash']);
+    expect(calls).toContainEqual(['stash', 'pop']);
+  });
+
+  it('classifies a fetch failure as "error", not a conflict', async () => {
+    mockGit({ fetchError: gitError('fatal: unable to access origin: Could not resolve host') });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe('error');
+    expect(result.message).toMatch(/^Fetch failed:/);
+    expect(result.conflict).toBeUndefined();
+    // Should never attempt a rebase if fetch failed.
+    expect(gitCalls().some((c) => c[0] === 'rebase')).toBe(false);
+  });
+
+  it('classifies a real merge conflict as "conflict" and aborts', async () => {
+    mockGit({
+      statusStdout: '',
+      rebaseError: gitError('CONFLICT (content): Merge conflict in src/app.ts'),
+    });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    expect(result.success).toBe(false);
+    expect(result.status).toBe('conflict');
+    expect(result.conflict).toContain('CONFLICT');
+    expect(gitCalls()).toContainEqual(['rebase', '--abort']);
+  });
+
+  it('restores the stash after aborting a conflicting rebase on a dirty tree', async () => {
+    mockGit({
+      statusStdout: ' M src/app.ts\n',
+      rebaseError: gitError('CONFLICT (content): Merge conflict'),
+    });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    expect(result.status).toBe('conflict');
+    expect(result.stashed).toBe(true);
+    const calls = gitCalls();
+    expect(calls).toContainEqual(['rebase', '--abort']);
+    expect(calls).toContainEqual(['stash', 'pop']); // local work restored
+  });
+
+  it('reports "stash-conflict" when the rebase lands but the stash pop conflicts', async () => {
+    mockGit({
+      statusStdout: ' M src/app.ts\n',
+      rebaseStdout: 'Successfully rebased.',
+      stashPopError: gitError('CONFLICT (content): Merge conflict in src/app.ts'),
+    });
+
+    const result = await rebaseRepo('/repo', 'main');
+
+    // The rebase itself succeeded, so success is true, but it needs attention.
+    expect(result.success).toBe(true);
+    expect(result.status).toBe('stash-conflict');
+    expect(result.stashed).toBe(true);
+    expect(result.message).toMatch(/stash preserved/i);
+  });
+});