Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

fix(fuse): preserve dirty workspace writes

OKNOTOKb76729b8c2d8
diff --git a/.github/workflows/agent-fuse.yml b/.github/workflows/agent-fuse.yml
new file mode 100644
index 0000000..89120f8
--- /dev/null
+++ b/.github/workflows/agent-fuse.yml
@@ -0,0 +1,34 @@
+name: Agent FUSE
+
+on:
+ pull_request:
+ branches: [main]
+ paths:
+ - "agent-fuse/**"
+ - ".github/workflows/agent-fuse.yml"
+ push:
+ branches: [main]
+ paths:
+ - "agent-fuse/**"
+ - ".github/workflows/agent-fuse.yml"
+
+permissions:
+ contents: read
+
+jobs:
+ test:
+ name: Go tests (race)
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ defaults:
+ run:
+ working-directory: agent-fuse
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-go@v5
+ with:
+ go-version-file: agent-fuse/go.mod
+ cache-dependency-path: agent-fuse/go.sum
+ - run: test -z "$(gofmt -l .)"
+ - run: go vet ./...
+ - run: go test -race ./...
diff --git a/agent-fuse/main.go b/agent-fuse/main.go
index 748b254..7bd645a 100644
--- a/agent-fuse/main.go
+++ b/agent-fuse/main.go
@@ -1,7 +1,7 @@
// cumora-fuse — a FUSE driver that maps the agent's slice of the
// `agent_workspace` table to a real filesystem at the mount point.
//
-// cumora-fuse "$CUMORA_AGENT_RUNTIME_URL" "$CUMORA_AGENT_RUNTIME_TOKEN" /workspace
+// cumora-fuse "$CUMORA_AGENT_RUNTIME_URL" "$CUMORA_AGENT_RUNTIME_TOKEN" /workspace
//
// Instead of connecting to Postgres directly, the FUSE driver issues
// HTTP requests to the cumora server's `/runtime/fs/*` endpoints.
@@ -126,7 +126,9 @@ func (w *ws) readFile(p string) ([]byte, syscall.Errno) {
log.Printf("[cumora-fuse] read(%q) http %d: %s", p, code, truncate(body))
return nil, syscall.EIO
}
- var out struct{ Body string `json:"body"` }
+ var out struct {
+ Body string `json:"body"`
+ }
if err := json.Unmarshal(body, &out); err != nil {
return nil, syscall.EIO
}
@@ -172,7 +174,9 @@ func (w *ws) listChildren(dir string) ([]dirent, syscall.Errno) {
if code != 200 {
return nil, syscall.EIO
}
- var out struct{ Entries []dirent `json:"entries"` }
+ var out struct {
+ Entries []dirent `json:"entries"`
+ }
if err := json.Unmarshal(body, &out); err != nil {
return nil, syscall.EIO
}
@@ -258,10 +262,15 @@ func (d *dirNode) Mkdir(ctx context.Context, name string, mode uint32, out *fuse
func (d *dirNode) Create(ctx context.Context, name string, flags uint32, mode uint32, out *fuse.EntryOut) (*fs.Inode, fs.FileHandle, uint32, syscall.Errno) {
child := joinRel(d.relPath, name)
+ // The kernel normally sends CREATE only after Lookup reported ENOENT, so
+ // an existing file is rejected by VFS before this callback for O_EXCL.
+ // The runtime endpoint is an upsert, however; closing the lookup/create
+ // race requires an atomic create-exclusive server operation, not a local
+ // stat-then-write sequence.
if errno := d.w.writeFile(child, nil); errno != 0 {
return nil, nil, 0, errno
}
- fn := &fileNode{w: d.w, relPath: child, cachedBody: []byte{}, cachedAt: time.Now()}
+ fn := &fileNode{w: d.w, relPath: child, cachedBody: []byte{}, cachedAt: time.Now(), loaded: true}
fn.fillAttr(&out.Attr, 0)
return d.NewInode(ctx, fn, fs.StableAttr{Mode: fuse.S_IFREG}), &fileHandle{f: fn}, 0, 0
}
@@ -296,9 +305,12 @@ type fileNode struct {
size int64
mu sync.Mutex
+ flushMu sync.Mutex
cachedBody []byte
cachedAt time.Time
+ loaded bool
dirty bool
+ generation uint64
}
func (f *fileNode) fillAttr(a *fuse.Attr, size int64) {
@@ -308,19 +320,36 @@ func (f *fileNode) fillAttr(a *fuse.Attr, size int64) {
a.Size = uint64(size)
}
-func (f *fileNode) loadIfStale() ([]byte, syscall.Errno) {
- f.mu.Lock()
- defer f.mu.Unlock()
- if !f.dirty && time.Since(f.cachedAt) < fileCacheTTL {
- return f.cachedBody, 0
+// ensureCurrentLocked hydrates the cache when it is uncached or stale. The
+// caller must hold f.mu. Keeping the HTTP read under the same lock as cache
+// updates means a partial write cannot race hydration and apply to the wrong
+// base. It deliberately does not clone the body; write callers mutate the
+// cache while snapshot-returning callers clone it below.
+func (f *fileNode) ensureCurrentLocked() syscall.Errno {
+ // A dirty cache is authoritative until its snapshot has been uploaded. Its
+ // TTL must not cause an in-flight local edit to be replaced by remote data.
+ if f.dirty || (f.loaded && time.Since(f.cachedAt) < fileCacheTTL) {
+ return 0
}
body, errno := f.w.readFile(f.relPath)
if errno != 0 {
- return nil, errno
+ return errno
}
f.cachedBody = body
f.cachedAt = time.Now()
- return body, 0
+ f.loaded = true
+ return 0
+}
+
+func (f *fileNode) loadIfStale() ([]byte, syscall.Errno) {
+ f.mu.Lock()
+ errno := f.ensureCurrentLocked()
+ var body []byte
+ if errno == 0 {
+ body = bytes.Clone(f.cachedBody)
+ }
+ f.mu.Unlock()
+ return body, errno
}
func (f *fileNode) Getattr(ctx context.Context, fh fs.FileHandle, out *fuse.AttrOut) syscall.Errno {
@@ -341,6 +370,9 @@ func (f *fileNode) Read(ctx context.Context, fh fs.FileHandle, dest []byte, off
if errno != 0 {
return nil, errno
}
+ if off < 0 {
+ return nil, syscall.EINVAL
+ }
end := off + int64(len(dest))
if end > int64(len(body)) {
end = int64(len(body))
@@ -354,6 +386,16 @@ func (f *fileNode) Read(ctx context.Context, fh fs.FileHandle, dest []byte, off
func (f *fileNode) Write(ctx context.Context, fh fs.FileHandle, data []byte, off int64) (uint32, syscall.Errno) {
f.mu.Lock()
defer f.mu.Unlock()
+ if off < 0 {
+ return 0, syscall.EINVAL
+ }
+ maxInt := int(^uint(0) >> 1)
+ if uint64(off) > uint64(maxInt-len(data)) {
+ return 0, syscall.EFBIG
+ }
+ if errno := f.ensureCurrentLocked(); errno != 0 {
+ return 0, errno
+ }
need := int(off) + len(data)
if need > len(f.cachedBody) {
grown := make([]byte, need)
@@ -362,6 +404,7 @@ func (f *fileNode) Write(ctx context.Context, fh fs.FileHandle, data []byte, off
}
copy(f.cachedBody[off:], data)
f.dirty = true
+ f.generation++
return uint32(len(data)), 0
}
@@ -374,40 +417,63 @@ func (f *fileNode) Fsync(ctx context.Context, fh fs.FileHandle, flags uint32) sy
}
func (f *fileNode) Setattr(ctx context.Context, fh fs.FileHandle, in *fuse.SetAttrIn, out *fuse.AttrOut) syscall.Errno {
+ f.mu.Lock()
+ if errno := f.ensureCurrentLocked(); errno != 0 {
+ f.mu.Unlock()
+ return errno
+ }
if size, ok := in.GetSize(); ok {
- f.mu.Lock()
+ maxInt := uint64(^uint(0) >> 1)
+ if size > maxInt {
+ f.mu.Unlock()
+ return syscall.EFBIG
+ }
if int(size) < len(f.cachedBody) {
- f.cachedBody = f.cachedBody[:size]
+ f.cachedBody = f.cachedBody[:int(size)]
} else if int(size) > len(f.cachedBody) {
grown := make([]byte, size)
copy(grown, f.cachedBody)
f.cachedBody = grown
}
f.dirty = true
- f.mu.Unlock()
- }
- body, errno := f.loadIfStale()
- if errno != 0 {
- return errno
+ f.generation++
}
+ body := bytes.Clone(f.cachedBody)
+ f.mu.Unlock()
f.fillAttr(&out.Attr, int64(len(body)))
return 0
}
func (f *fileNode) persist() syscall.Errno {
+ // FUSE can issue overlapping Flush/Fsync callbacks. Serialize the remote
+ // whole-file writes so an older request cannot complete after a newer one.
+ f.flushMu.Lock()
+ defer f.flushMu.Unlock()
+
f.mu.Lock()
- dirty := f.dirty
- body := append([]byte(nil), f.cachedBody...)
- f.mu.Unlock()
- if !dirty {
+ if !f.dirty {
+ f.mu.Unlock()
return 0
}
+ body := bytes.Clone(f.cachedBody)
+ generation := f.generation
+ f.mu.Unlock()
+
if errno := f.w.writeFile(f.relPath, body); errno != 0 {
+ // Keep dirty=true on network or HTTP failures. The next Flush/Fsync
+ // can retry the same local snapshot.
return errno
}
+
f.mu.Lock()
- f.dirty = false
- f.cachedAt = time.Now()
+ if f.generation == generation {
+ f.dirty = false
+ f.cachedAt = time.Now()
+ f.loaded = true
+ }
+ // A write may have raced the upload. Leave that newer generation dirty;
+ // the next Flush/Fsync will upload it without letting this older response
+ // clear the local change.
f.mu.Unlock()
return 0
}
diff --git a/agent-fuse/main_test.go b/agent-fuse/main_test.go
new file mode 100644
index 0000000..97259be
--- /dev/null
+++ b/agent-fuse/main_test.go
@@ -0,0 +1,362 @@
+package main
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "sync"
+ "syscall"
+ "testing"
+ "time"
+
+ "github.com/hanwen/go-fuse/v2/fuse"
+)
+
+type fuseTestBackend struct {
+ mu sync.Mutex
+
+ files map[string]string
+ readCalls int
+ writeCalls []string
+ failWrites bool
+
+ firstWriteStarted chan struct{}
+ allowFirstWrite chan struct{}
+ secondWriteStarted chan struct{}
+ allowSecondWrite chan struct{}
+ firstWriteRelease sync.Once
+ secondWriteRelease sync.Once
+}
+
+func newFuseTestBackend(files map[string]string) *fuseTestBackend {
+ copyOfFiles := make(map[string]string, len(files))
+ for path, body := range files {
+ copyOfFiles[path] = body
+ }
+ return &fuseTestBackend{files: copyOfFiles}
+}
+
+func (b *fuseTestBackend) handler(w http.ResponseWriter, r *http.Request) {
+ path := r.URL.Query().Get("path")
+ switch r.Method + " " + r.URL.Path {
+ case http.MethodGet + " /fs/read":
+ b.mu.Lock()
+ body, ok := b.files[path]
+ b.readCalls++
+ b.mu.Unlock()
+ if !ok {
+ w.WriteHeader(http.StatusNotFound)
+ return
+ }
+ _ = json.NewEncoder(w).Encode(map[string]string{"body": body})
+ case http.MethodPut + " /fs/write":
+ var req struct {
+ Path string `json:"path"`
+ Body string `json:"body"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ w.WriteHeader(http.StatusBadRequest)
+ return
+ }
+
+ b.mu.Lock()
+ b.writeCalls = append(b.writeCalls, req.Body)
+ writeNumber := len(b.writeCalls)
+ if writeNumber == 1 && b.firstWriteStarted != nil {
+ close(b.firstWriteStarted)
+ }
+ if writeNumber == 2 && b.secondWriteStarted != nil {
+ close(b.secondWriteStarted)
+ }
+ allowFirst, allowSecond := b.allowFirstWrite, b.allowSecondWrite
+ failWrite := b.failWrites
+ b.mu.Unlock()
+
+ if writeNumber == 1 && allowFirst != nil {
+ <-allowFirst
+ }
+ if writeNumber == 2 && allowSecond != nil {
+ <-allowSecond
+ }
+ if failWrite {
+ w.WriteHeader(http.StatusInternalServerError)
+ return
+ }
+
+ b.mu.Lock()
+ b.files[req.Path] = req.Body
+ b.mu.Unlock()
+ _ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+ default:
+ w.WriteHeader(http.StatusNotFound)
+ }
+}
+
+func newFuseTestWorkspace(t *testing.T, backend *fuseTestBackend) (*ws, func()) {
+ t.Helper()
+ server := httptest.NewServer(http.HandlerFunc(backend.handler))
+ return newWs(server.URL, "test-token"), server.Close
+}
+
+func newFileNodeForTest(w *ws, path string, body string) *fileNode {
+ return &fileNode{
+ w: w,
+ relPath: path,
+ cachedBody: []byte(body),
+ cachedAt: time.Now(),
+ loaded: true,
+ }
+}
+
+func (b *fuseTestBackend) body(path string) string {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ return b.files[path]
+}
+
+func (b *fuseTestBackend) reads() int {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ return b.readCalls
+}
+
+func (b *fuseTestBackend) writes() []string {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ return append([]string(nil), b.writeCalls...)
+}
+
+func (b *fuseTestBackend) releaseFirstWrite() {
+ if b.allowFirstWrite != nil {
+ b.firstWriteRelease.Do(func() { close(b.allowFirstWrite) })
+ }
+}
+
+func (b *fuseTestBackend) releaseSecondWrite() {
+ if b.allowSecondWrite != nil {
+ b.secondWriteRelease.Do(func() { close(b.allowSecondWrite) })
+ }
+}
+
+func TestWriteGetattrFlushPreservesDirtyBody(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "remote"})
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := &fileNode{w: w, relPath: "notes.txt"}
+
+ if written, errno := f.Write(nil, nil, []byte("local!"), 0); errno != 0 || written != 6 {
+ t.Fatalf("Write() = (%d, %d), want (6, 0)", written, errno)
+ }
+ var out fuse.AttrOut
+ if errno := f.Getattr(nil, nil, &out); errno != 0 {
+ t.Fatalf("Getattr() errno = %d", errno)
+ }
+ if got := out.Size; got != 6 {
+ t.Fatalf("Getattr() size = %d, want 6", got)
+ }
+ if errno := f.Flush(nil, nil); errno != 0 {
+ t.Fatalf("Flush() errno = %d", errno)
+ }
+ if got := backend.body("notes.txt"); got != "local!" {
+ t.Fatalf("backend body = %q, want %q", got, "local!")
+ }
+ if got := backend.reads(); got != 1 {
+ t.Fatalf("backend read calls = %d, want one hydration read", got)
+ }
+}
+
+func TestSetattrTruncateHydratesExistingContent(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "hello world"})
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := &fileNode{w: w, relPath: "notes.txt"}
+
+ var in fuse.SetAttrIn
+ in.Valid = fuse.FATTR_SIZE
+ in.Size = 5
+ var out fuse.AttrOut
+ if errno := f.Setattr(nil, nil, &in, &out); errno != 0 {
+ t.Fatalf("Setattr() errno = %d", errno)
+ }
+ if out.Size != 5 {
+ t.Fatalf("Setattr() size = %d, want 5", out.Size)
+ }
+ if errno := f.Flush(nil, nil); errno != 0 {
+ t.Fatalf("Flush() errno = %d", errno)
+ }
+ if got := backend.body("notes.txt"); got != "hello" {
+ t.Fatalf("backend body = %q, want %q", got, "hello")
+ }
+ if got := backend.reads(); got != 1 {
+ t.Fatalf("backend read calls = %d, want one hydration read", got)
+ }
+}
+
+func TestExpiredDirtyCacheIsNotReplaced(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "remote"})
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := newFileNodeForTest(w, "notes.txt", "local")
+ f.cachedAt = time.Now().Add(-fileCacheTTL - time.Second)
+ f.dirty = true
+
+ var out fuse.AttrOut
+ if errno := f.Getattr(nil, nil, &out); errno != 0 {
+ t.Fatalf("Getattr() errno = %d", errno)
+ }
+ if out.Size != uint64(len("local")) {
+ t.Fatalf("Getattr() size = %d, want local size", out.Size)
+ }
+ if got := backend.reads(); got != 0 {
+ t.Fatalf("backend read calls = %d, want zero for dirty cache", got)
+ }
+}
+
+func TestUncachedPartialWriteHydratesExistingContent(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "abcdef"})
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := &fileNode{w: w, relPath: "notes.txt"}
+
+ if written, errno := f.Write(nil, nil, []byte("XY"), 2); errno != 0 || written != 2 {
+ t.Fatalf("Write() = (%d, %d), want (2, 0)", written, errno)
+ }
+ if errno := f.Flush(nil, nil); errno != 0 {
+ t.Fatalf("Flush() errno = %d", errno)
+ }
+ if got := backend.body("notes.txt"); got != "abXYef" {
+ t.Fatalf("backend body = %q, want %q", got, "abXYef")
+ }
+ if got := backend.reads(); got != 1 {
+ t.Fatalf("backend read calls = %d, want one hydration read", got)
+ }
+}
+
+func TestReadReturnsSnapshotIsolatedFromLaterWrites(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "remote"})
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := newFileNodeForTest(w, "notes.txt", "old")
+
+ result, errno := f.Read(nil, nil, make([]byte, 3), 0)
+ if errno != 0 {
+ t.Fatalf("Read() errno = %d", errno)
+ }
+ readBody, status := result.Bytes(nil)
+ if status != fuse.OK {
+ t.Fatalf("Read() status = %v, want OK", status)
+ }
+ if got := string(readBody); got != "old" {
+ t.Fatalf("initial read = %q, want %q", got, "old")
+ }
+ if _, errno := f.Write(nil, nil, []byte("new"), 0); errno != 0 {
+ t.Fatalf("Write() after Read() errno = %d", errno)
+ }
+ if got := string(readBody); got != "old" {
+ t.Fatalf("read snapshot after later Write() = %q, want %q", got, "old")
+ }
+
+ body, errno := f.loadIfStale()
+ if errno != 0 {
+ t.Fatalf("loadIfStale() errno = %d", errno)
+ }
+ if got := string(body); got != "new" {
+ t.Fatalf("cache after later Write() = %q, want %q", got, "new")
+ }
+}
+
+func TestConcurrentWriteDuringFlushIsUploadedInOrder(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "old"})
+ backend.firstWriteStarted = make(chan struct{})
+ backend.allowFirstWrite = make(chan struct{})
+ backend.secondWriteStarted = make(chan struct{})
+ backend.allowSecondWrite = make(chan struct{})
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := newFileNodeForTest(w, "notes.txt", "old")
+ if _, errno := f.Write(nil, nil, []byte("one"), 0); errno != 0 {
+ t.Fatalf("initial Write() errno = %d", errno)
+ }
+
+ defer backend.releaseFirstWrite()
+ defer backend.releaseSecondWrite()
+
+ flushDone := make(chan syscall.Errno, 1)
+ go func() { flushDone <- f.Flush(nil, nil) }()
+ select {
+ case <-backend.firstWriteStarted:
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for first upload")
+ }
+
+ if _, errno := f.Write(nil, nil, []byte("two"), 0); errno != 0 {
+ t.Fatalf("racing Write() errno = %d", errno)
+ }
+ secondFlushDone := make(chan syscall.Errno, 1)
+ go func() { secondFlushDone <- f.Flush(nil, nil) }()
+ backend.releaseFirstWrite()
+ select {
+ case <-backend.secondWriteStarted:
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for second upload")
+ }
+
+ select {
+ case errno := <-flushDone:
+ if errno != 0 {
+ t.Fatalf("Flush() errno = %d", errno)
+ }
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for Flush()")
+ }
+ if got := backend.body("notes.txt"); got != "one" {
+ t.Fatalf("backend body = %q, want first generation %q", got, "one")
+ }
+ if !f.dirty {
+ t.Fatal("file lost dirty state after a newer write raced the upload")
+ }
+ backend.releaseSecondWrite()
+ select {
+ case errno := <-secondFlushDone:
+ if errno != 0 {
+ t.Fatalf("overlapping Flush() errno = %d", errno)
+ }
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for overlapping Flush()")
+ }
+ if got := backend.body("notes.txt"); got != "two" {
+ t.Fatalf("backend body after overlapping second Flush() = %q, want newest generation %q", got, "two")
+ }
+ if got := backend.writes(); len(got) != 2 || got[0] != "one" || got[1] != "two" {
+ t.Fatalf("upload bodies = %#v, want [one two]", got)
+ }
+ if f.dirty {
+ t.Fatal("file remains dirty after newest generation was uploaded")
+ }
+}
+
+func TestFlushFailureKeepsDirtyCacheForRetry(t *testing.T) {
+ backend := newFuseTestBackend(map[string]string{"notes.txt": "remote"})
+ backend.failWrites = true
+ w, closeServer := newFuseTestWorkspace(t, backend)
+ defer closeServer()
+ f := newFileNodeForTest(w, "notes.txt", "local")
+ f.dirty = true
+ f.generation = 1
+
+ if errno := f.Flush(nil, nil); errno == 0 {
+ t.Fatal("Flush() succeeded for a failed HTTP write")
+ }
+ if !f.dirty {
+ t.Fatal("file was marked clean after a failed upload")
+ }
+ backend.mu.Lock()
+ backend.failWrites = false
+ backend.mu.Unlock()
+ if errno := f.Flush(nil, nil); errno != 0 {
+ t.Fatalf("retry Flush() errno = %d", errno)
+ }
+ if got := backend.body("notes.txt"); got != "local" {
+ t.Fatalf("backend body after retry = %q, want %q", got, "local")
+ }
+}