Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(evendrive): epoch-guard breadcrumb reconstruction against stale retries

M4025100c1618
diff --git a/control-ui/components/GfsBrowser.tsx b/control-ui/components/GfsBrowser.tsx
index 48bb7fc4e..567f4daf9 100644
--- a/control-ui/components/GfsBrowser.tsx
+++ b/control-ui/components/GfsBrowser.tsx
@@ -86,6 +86,13 @@ interface Crumb {
version?: number
}
+/** Verdict of a breadcrumb ancestry reconstruction attempt (R7-M1 race).
+ * 'superseded' means a newer Move, reconstruction, rename, or navigation
+ * invalidated this attempt while its requests were in flight — callers must
+ * leave the breadcrumb trail AND the recovery notice untouched so the
+ * newer operation's state survives. */
+type TrailReconstructionOutcome = 'applied' | 'failed' | 'superseded'
+
const DRIVE = 'main'
const PENDING_GFS_UPLOAD_KEY = 'evenfire:gfs-upload-v2:pending'
const GFS_RESOURCE_DRAG_TYPE = 'application/x-evenfire-gfs-resource'
@@ -259,6 +266,16 @@ export function GfsBrowser(): React.JSX.Element {
resourceId: string
gfsUri: string
} | null>(null)
+ // Monotonic epoch for breadcrumb-reconstruction attempts (R7-M1 race). A
+ // reconstruction (a move's rebuild or a Retry) captures the epoch at start
+ // and may apply its result only while it is still the LATEST attempt. Any
+ // newer reconstruction, a later Move's rebuild, a rename, or a navigation
+ // that replaces/leaves the trail bumps the epoch, so a superseded in-flight
+ // response is discarded instead of overwriting the newer ancestry or
+ // clearing the newer operation's recovery notice. Appending a DESCENDANT
+ // (openDirectory) does not bump: it never invalidates the retry target's
+ // ancestors and the functional apply carries the live tail along.
+ const trailReconstructionEpochRef = useRef(0)
const draggingResourceRef = useRef<GfsChild | null>(null)
const movingResourceRef = useRef<string | null>(null)
const [imagePreview, setImagePreview] = useState<{
@@ -566,6 +583,10 @@ export function GfsBrowser(): React.JSX.Element {
function goToCrumb(index: number): void {
if (index === crumbs.length - 1) return
+ // A navigation that leaves the current trail supersedes any in-flight
+ // breadcrumb reconstruction (R7-M1): its late response must not re-anchor
+ // a trail the operator just navigated away from.
+ trailReconstructionEpochRef.current += 1
setRenameTarget(null)
setLoading(true)
setCrumbs(crumbs.slice(0, index + 1))
@@ -718,13 +739,15 @@ export function GfsBrowser(): React.JSX.Element {
: crumb
)
)
- const rebuilt = await rebuildTrailFromNewLocation(source.resourceId, source.gfsUri)
- if (!rebuilt) {
+ const outcome = await rebuildTrailFromNewLocation(source.resourceId, source.gfsUri)
+ if (outcome === 'failed') {
// The MOVE succeeded but the trail could not be reconstructed from
// the new location. Keep the trail the operator was looking at
// (explicitly stale — never a shortened path presented as
// authoritative) and surface a recovery notice with a retry until
- // reconstruction succeeds.
+ // reconstruction succeeds. ('applied' clears any older notice for
+ // this resource inside the rebuild; 'superseded' leaves state to
+ // the newer attempt that displaced this one.)
setTrailRecovery({ resourceId: source.resourceId, gfsUri: source.gfsUri })
}
return
@@ -751,23 +774,39 @@ export function GfsBrowser(): React.JSX.Element {
* mutation that landed while recovery was pending keeps its newer
* name/version — no move-time snapshot is ever replayed.
*
- * Reconstruction is ALL-OR-NOTHING and returns whether it succeeded: a
- * failed leaf resolve, a null `path`, or any failed ancestor by-path
- * lookup leaves the current trail UNTOUCHED (never a partial ancestry
- * presented as authoritative) so the caller can surface recovery state
- * instead. */
- async function rebuildTrailFromNewLocation(resourceId: string, gfsUri: string): Promise<boolean> {
+ * Each attempt is EPOCH-VERSIONED (R7-M1 race): it may apply its result
+ * only while it is still the latest reconstruction attempt. A newer Move,
+ * reconstruction, rename, or trail-replacing navigation that lands while
+ * this attempt's requests are in flight bumps the epoch, and the stale
+ * response is then discarded whole — it can neither overwrite the newer
+ * ancestry nor clear the newer operation's recovery notice.
+ *
+ * Reconstruction is ALL-OR-NOTHING: a failed leaf resolve, a null `path`,
+ * or any failed ancestor by-path lookup leaves the current trail
+ * UNTOUCHED (never a partial ancestry presented as authoritative) so the
+ * caller can surface recovery state instead. */
+ async function rebuildTrailFromNewLocation(
+ resourceId: string,
+ gfsUri: string
+ ): Promise<TrailReconstructionOutcome> {
+ const epoch = ++trailReconstructionEpochRef.current
+ // A displaced attempt is 'superseded' no matter how its own requests
+ // settle — its verdict must never reach breadcrumb or recovery state.
+ const verdict = (outcome: TrailReconstructionOutcome): TrailReconstructionOutcome =>
+ epoch === trailReconstructionEpochRef.current ? outcome : 'superseded'
let view: { path?: string | null }
try {
view = (await apiGet('/api/v1/gfs/resolve', { uri: gfsUri })) as {
path?: string | null
}
} catch {
- return false
+ return verdict('failed')
}
// A null path means the server could not name the new location — that is
// a failed reconstruction, not a root-level folder ('/org' is).
- if (typeof view.path !== 'string' || view.path.length <= 1) return false
+ if (typeof view.path !== 'string' || view.path.length <= 1) {
+ return verdict('failed')
+ }
const segments = view.path.split('/').filter(segment => segment.length > 0)
const ancestors: Crumb[] = []
for (let depth = 1; depth < segments.length; depth += 1) {
@@ -775,7 +814,7 @@ export function GfsBrowser(): React.JSX.Element {
try {
ancestor = await getGfsResourceByPath(DRIVE, '/' + segments.slice(0, depth).join('/'))
} catch {
- return false
+ return verdict('failed')
}
ancestors.push({
id: ancestor.resourceId,
@@ -785,7 +824,9 @@ export function GfsBrowser(): React.JSX.Element {
gfsUri: ancestor.gfsUri,
})
}
+ if (epoch !== trailReconstructionEpochRef.current) return 'superseded'
setCrumbs(prev => {
+ if (epoch !== trailReconstructionEpochRef.current) return prev
const index = prev.findIndex(crumb => crumb.id === resourceId)
// The user navigated while the resolve walk was in flight — never
// clobber the trail they navigated to.
@@ -797,19 +838,23 @@ export function GfsBrowser(): React.JSX.Element {
...prev.slice(index),
]
})
- return true
+ // The trail is canonical for this resource as of the LATEST attempt —
+ // any older recovery notice for it is obsolete.
+ setTrailRecovery(null)
+ return 'applied'
}
/** Retry a failed post-move trail ancestry reconstruction. Runs from the
* recovery snapshot's IMMUTABLE identity plus the live trail — never a
* captured name/version — so the rebuilt crumb reflects every mutation
- * that landed since the move. The notice stays up on a second failure;
- * the trail is only swapped once a retry has fully rebuilt it. */
+ * that landed since the move. The rebuild owns the notice entirely: an
+ * 'applied' retry clears it (the trail is canonical again), a 'failed'
+ * retry keeps it, and a 'superseded' retry touches NOTHING — a newer
+ * Move/reconstruction owns the breadcrumb and its recovery state now. */
async function retryTrailRecovery(): Promise<void> {
const recovery = trailRecovery
if (!recovery) return
- const rebuilt = await rebuildTrailFromNewLocation(recovery.resourceId, recovery.gfsUri)
- if (rebuilt) setTrailRecovery(null)
+ await rebuildTrailFromNewLocation(recovery.resourceId, recovery.gfsUri)
}
async function handleFolderDrop(
@@ -1211,6 +1256,10 @@ export function GfsBrowser(): React.JSX.Element {
setSelected(null)
setRenameOpen(false)
setDeleteOpen(false)
+ // Replacing the whole trail supersedes any in-flight breadcrumb
+ // reconstruction (R7-M1): its late response must not re-anchor the
+ // trail this link-open just replaced.
+ trailReconstructionEpochRef.current += 1
setCrumbs([
{ id: null, rid: null, name: '/' },
{
@@ -1252,7 +1301,10 @@ export function GfsBrowser(): React.JSX.Element {
)?.data?.version
showToast('Resource renamed.', { tone: 'success' })
// A crumb rename must retitle the breadcrumb segment too, not just the
- // listing rows refreshed below.
+ // listing rows refreshed below. It also supersedes any in-flight
+ // breadcrumb reconstruction (R7-M1): a stale retry response must not
+ // land over a trail the rename just advanced.
+ trailReconstructionEpochRef.current += 1
setCrumbs(prev =>
prev.map(crumb =>
crumb.id === child.resourceId
diff --git a/control-ui/components/__tests__/GfsBrowser.test.tsx b/control-ui/components/__tests__/GfsBrowser.test.tsx
index addc836ce..374123f60 100644
--- a/control-ui/components/__tests__/GfsBrowser.test.tsx
+++ b/control-ui/components/__tests__/GfsBrowser.test.tsx
@@ -2028,6 +2028,136 @@ describe('GfsBrowser', () => {
)
})
+ // R7-M1 (in-flight race): a Retry whose resolve/by-path responses land
+ // AFTER a newer Move completed must be discarded whole — the stale response
+ // can neither overwrite the newer ancestry nor clear the newer operation's
+ // recovery state.
+ it('discards a superseded Retry response that lands after a newer Move', async () => {
+ const rootId = '11111111-1111-1111-1111-111111111111'
+ const work = child('work', 'directory', 1, 3)
+ const org = child('org', 'directory', 2, 7)
+ const archive = child('archive', 'directory', 3, 5)
+ const dept = child('dept', 'directory', 4, 6)
+ const resolveView = (resourceId: string, rid: string, name: string, path: string) => ({
+ resourceId,
+ rid,
+ gfsUri: `gfs://main/${rid}`,
+ drive: 'main',
+ name,
+ kind: 'directory',
+ path,
+ updatedAt: '2026-09-24T00:00:00.000Z',
+ })
+ // resolve call order: 1 = Move A reconstruction (fails), 2 = Retry A
+ // (HELD pending), 3 = Move B reconstruction (succeeds → /dept/org).
+ let resolveCalls = 0
+ let releaseRetryResolve: ((view: unknown) => void) | null = null
+ mockApiGet.mockImplementation(async (path: string) => {
+ if (path === '/api/v1/gfs/tree' || path === `/api/v1/gfs/resources/${rootId}/children`) {
+ return { rootResourceId: rootId, items: [work, archive, dept], nextCursor: null }
+ }
+ if (path === `/api/v1/gfs/resources/${work.resourceId}/children`) {
+ return { items: [org], nextCursor: null }
+ }
+ if (path === '/api/v1/gfs/resolve') {
+ resolveCalls += 1
+ if (resolveCalls === 1) throw new Error('resolve unavailable')
+ if (resolveCalls === 2) {
+ return new Promise<unknown>(resolve => {
+ releaseRetryResolve = resolve
+ })
+ }
+ return resolveView(org.resourceId, org.rid, 'org', '/dept/org')
+ }
+ return { items: [], nextCursor: null }
+ })
+ mockGetGfsResourceByPath.mockReset()
+ mockGetGfsResourceByPath.mockImplementation(async (_drive: string, path: string) => {
+ if (path === '/dept') {
+ return resolveView(dept.resourceId, dept.rid, dept.name, '/dept')
+ }
+ // Retry A's ancestor lookup (after its release) answers with the OLD
+ // Move A ancestry — exactly the stale data that must be discarded.
+ return resolveView(archive.resourceId, archive.rid, archive.name, path)
+ })
+ mockApiSend
+ .mockResolvedValueOnce({
+ ok: true,
+ data: { resourceId: org.resourceId, version: 8 },
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ data: { resourceId: org.resourceId, version: 9 },
+ })
+ renderBrowser()
+
+ fireEvent.click(await screen.findByRole('button', { name: 'work' }))
+ fireEvent.click(await screen.findByRole('button', { name: 'org' }))
+ await screen.findByText('No resources are visible in this folder.')
+
+ const breadcrumb = screen.getByRole('navigation', { name: 'Breadcrumb' })
+ const labels = () =>
+ within(breadcrumb)
+ .getAllByRole('button')
+ .map(button => button.getAttribute('aria-label') ?? button.textContent)
+
+ // Move A: /work/org → /archive. Succeeds, reconstruction FAILS.
+ fireEvent.click(within(breadcrumb).getByRole('button', { name: 'Actions for org' }))
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Move to…' }))
+ let moveDialog = await screen.findByRole('dialog', { name: 'Move folder org' })
+ fireEvent.click(await within(moveDialog).findByRole('button', { name: 'archive' }))
+ fireEvent.click(within(moveDialog).getByRole('button', { name: 'Move here (archive)' }))
+ await waitFor(() =>
+ expect(mockApiSend).toHaveBeenNthCalledWith(
+ 1,
+ 'PATCH',
+ `/api/v1/gfs/resources/${org.resourceId}`,
+ { drive: 'main', newParentId: archive.resourceId, ifMatch: 7 },
+ { drive: 'main' }
+ )
+ )
+ const notice = await screen.findByRole('alert')
+ expect(within(notice).getByRole('button', { name: 'Retry' })).toBeTruthy()
+ expect(labels()).toEqual(['main', 'work', 'org', 'Actions for org'])
+
+ // Start Retry A and HOLD its resolve response pending.
+ fireEvent.click(within(notice).getByRole('button', { name: 'Retry' }))
+ await waitFor(() => expect(resolveCalls).toBe(2))
+ expect(releaseRetryResolve).toBeTruthy()
+
+ // While Retry A is held: Move B moves the same folder under /dept and
+ // completes — its reconstruction succeeds and refreshes the trail.
+ fireEvent.click(within(breadcrumb).getByRole('button', { name: 'Actions for org' }))
+ fireEvent.click(screen.getByRole('menuitem', { name: 'Move to…' }))
+ moveDialog = await screen.findByRole('dialog', { name: 'Move folder org' })
+ fireEvent.click(await within(moveDialog).findByRole('button', { name: 'dept' }))
+ fireEvent.click(within(moveDialog).getByRole('button', { name: 'Move here (dept)' }))
+ await waitFor(() =>
+ expect(mockApiSend).toHaveBeenNthCalledWith(
+ 2,
+ 'PATCH',
+ `/api/v1/gfs/resources/${org.resourceId}`,
+ { drive: 'main', newParentId: dept.resourceId, ifMatch: 8 },
+ { drive: 'main' }
+ )
+ )
+ await waitFor(() => expect(labels()).toEqual(['main', 'dept', 'org', 'Actions for org']))
+ // Move B's successful reconstruction retires Move A's stale notice.
+ await waitFor(() => expect(screen.queryByRole('alert')).toBeNull())
+
+ // Release Retry A's OLD response (Move A-era /archive ancestry) and let
+ // its full walk settle.
+ await act(async () => {
+ releaseRetryResolve!(resolveView(org.resourceId, org.rid, 'org', '/archive/org'))
+ await new Promise(resolve => setTimeout(resolve, 0))
+ })
+
+ // The superseded response was discarded: the breadcrumb still reflects
+ // Move B's ancestry, and no recovery state was resurrected or cleared.
+ expect(labels()).toEqual(['main', 'dept', 'org', 'Actions for org'])
+ expect(screen.queryByRole('alert')).toBeNull()
+ })
+
it('does not fall back to legacy when replacing a persisted resumable session', async () => {
const lastModified = 1_725_000_000_000
const uploadId = '66666666-6666-4666-8666-666666666666'
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 9ad09d12d..cf27ff65c 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.613",
+ "version": "0.1.614",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.613",
+ "version": "0.1.614",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index 89c0b1731..df7dcf033 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.613",
+ "version": "0.1.614",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",