tracefs: a changeset for every step a DSH agent takes, with undo (bundle, MIT)

[emmettlu]

tracefs: version every step a DSH agent takes, and undo it

A DSH bundle: the file-changing tool calls in each agent step become one changeset, and the model can inspect and undo its own work. No root, no VM; runs on macOS, Linux and Windows.
Open source (userspace MIT): github.com/emmettlu/tracefs

The problem

An agent runs a dozen bash / write / apply_patch calls in a turn, and halfway through you want the files back as they were before step three. Usually that means git stash, a manual diff, or asking the model to undo from memory. tracefs leaves it to the file system:

• One changeset per step: before the first file-writing call in a step it takes a "before" snapshot; when the step ends, all of that step's writing calls become one changeset (author, tool call id, first line of the command). Read-only calls and calls that changed nothing are not recorded.
• The model can undo its own work: the plugin registers a tracefs tool with action = status / log / diff / undo / merge. undo reverts only the paths that batch touched; if those paths changed again afterwards it reports a conflict and changes nothing.
• Branches and merges: the agent can work in a copy-on-write branch, merged three-way into main when each turn ends (turn/end). Text files changed on both sides go to git merge-file; anything that doesn't merge is reported as a conflict and main is left alone. Set merge: false to turn the automatic merge off.

Where it runs

The plugin is userspace only and ships its own cross-platform backend, tracefs-lite:

Platform	Store	Snapshots
macOS	APFS sparse image (hdiutil, no root)	clonefile, no extra space
Linux, directory on btrfs	btrfs directly	reflink
Linux, not on btrfs	a btrfs image file (mounted directly as root, via udisksctl otherwise)	reflink
Windows	NTFS VHDX (creating and mounting it needs admin)	full copies

When dsh runs under tracefs run on Linux, the plugin switches to the tracefsd daemon instead (btrfs subvolumes + overlayfs + a mount namespace that keeps the agent in its own branch).

Install

1. The plugin: open Plugins, switch on Custom plugin indexes under Experimental plugins, then on the Discover tab choose Add index source and enter:

   https://raw.githubusercontent.com/emmettlu/tracefs/main/market/index.json
   

   Search for tracefs and choose Install. The confirmation should show the Git repository github.com/emmettlu/tracefs, commit 0c6d711, directory sdk/dsh.

   Or skip the index and use the install spec directly:

   dsh plugin --profile <name> add "git+https://github.com/emmettlu/tracefs.git#0c6d7117dfe792f037a8b4adf6a39994123396b7&path:/sdk/dsh"

   Needs DSH >=0.2.1-alpha.4 <0.3.0; npm is not involved.

2. Put the project in a tracefs-lite store (the plugin records only in trees of a store; elsewhere it only offers the tracefs tool, which says how to turn it on):

   git clone https://github.com/emmettlu/tracefs && npm install -g ./tracefs/sdk/portable
   tracefs-lite init
   tracefs-lite register proj ~/proj        # prints the path of main
   tracefs-lite branch proj agent           # optional: a copy-on-write branch for the agent; prints its path

   Then point the DSH session's working directory at the printed path.

Tests and CI

Every commit runs on GitHub Actions (ci.yml):

• ubuntu / macOS / Windows: the backend (including the APFS image on macOS and the VHDX on Windows) and the DSH, Codex and pi plugins; Linux also runs the btrfs image as root and the backend on a btrfs volume.
• A real DeepSeek Harness, end to end (ubuntu, macOS): pins a DSH commit and runs a real session against DSH's own mock LLM server, checking that writing calls become changesets and merge into main at the end of the turn; validates the index above with DSH's own parser, and on ubuntu installs the spec it lists into a profile and loads it.
• Linux: tracefsd integration tests (root, btrfs, systemd) and the kernel module (Linux 7.3 in QEMU).

The same backend elsewhere

The repo also has a Codex plugin (hooks + skill) and a pi-coding-agent extension on the same backend.

Known limits

• tracefs-lite has no mount namespace, so it can't keep the agent inside a branch: it changes whichever tree its working directory is in.
• Snapshots are synchronous; a very large tree briefly blocks the plugin's process.
• Parallel tool calls land in the same changeset.

Feedback welcome — please file issues.