feat(tools): checkpoint files before mutating write and edit

The built-in workspace write and edit tools replaced file content with
no recoverable pre-state. Each now snapshots its target immediately
before the write and refuses the mutation when the snapshot cannot be
taken, so a checkpoint is never silently skipped.

Checkpoints land in .git/archie-checkpoints inside the workspace, the
same per-task state directory that already holds the task brief and the
prepared sentinel: nothing under .git can be swept onto the task branch
by go-git's Add{All:true}. A checkpoint records either the file's bytes
or its absence, so creating a file restores by removing it;
RestoreLatest returns the most recent pre-state for a path.

Shell, Go-script, MCP and plugin tools are deliberately not covered:
the set of files they can touch is not enumerable from the call.
This commit is contained in:
sam committed 2026-10-02 09:18:47 +10:00
1 parent 721968eeff
commit e10d862f6a
4 files changed
+429 -6

No files matched your search

+199
View File
@@ -0,0 +1,199 @@
// Not lifted from tau: archie-original. It gives the lifted write and edit
// tools something tau never had -- a pre-mutation checkpoint -- and stores it
// in the per-workspace state directory those tools already run against.
package builtin
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"time"
)
// checkpointDir is the workspace-relative directory a task's pre-mutation
// file checkpoints live under. It sits inside .git for the same reason the
// task brief (container.WriteTaskJSON) and the prepared sentinel
// (worktree.preparedSentinel) do: the workspace is a git worktree the agent
// commits from, and go-git's Add{All:true} honours neither .gitignore nor
// .git/info/exclude, so anything outside .git can be swept onto the task
// branch. Nothing under .git can ever be tracked.
const checkpointDir = ".git/archie-checkpoints"
// Checkpoint is a file's pre-mutation state: its bytes, or the fact that it
// did not exist.
type Checkpoint struct {
// ID identifies this checkpoint and names its file on disk.
ID string `json:"id"`
// Path is the absolute path the snapshot was taken from.
Path string `json:"path"`
// Existed reports whether the file was present. False means restore
// removes Path.
Existed bool `json:"existed"`
// Mode is the file's permission bits when it existed.
Mode os.FileMode `json:"mode"`
// Content is the file's bytes when it existed.
Content []byte `json:"content,omitempty"`
// CreatedAt orders checkpoints for RestoreLatest.
CreatedAt time.Time `json:"created_at"`
}
// CheckpointStore keeps pre-mutation file checkpoints for one workspace. It
// is written by the mutating built-in tools (write, edit) and read by a
// rollback caller; it is not itself a tool.
type CheckpointStore struct {
root string
now func() time.Time
}
// NewCheckpointStore returns the store rooted at workspace's per-workspace
// state directory. workspace is the same directory the file tools are rooted
// at, so the store travels with the workspace it protects.
func NewCheckpointStore(workspace string) *CheckpointStore {
return &CheckpointStore{
root: filepath.Join(workspace, filepath.FromSlash(checkpointDir)),
now: time.Now,
}
}
// Snapshot records path's current state and returns the checkpoint. It must
// be called before the mutation it guards: an error means the mutation must
// not proceed, because the pre-mutation state could not be preserved.
//
// A missing file is a valid snapshot (Existed=false) so that creating a file
// is restorable too. Non-regular files are refused: a checkpoint can restore
// bytes, not a socket, device or directory.
func (s *CheckpointStore) Snapshot(path string) (Checkpoint, error) {
abs, err := filepath.Abs(path)
if err != nil {
return Checkpoint{}, fmt.Errorf("checkpoint %s: resolve path: %w", path, err)
}
cp := Checkpoint{Path: abs, CreatedAt: s.now()}
info, err := os.Stat(abs)
switch {
case errors.Is(err, os.ErrNotExist):
// New file: the checkpoint records absence so restore removes it.
case err != nil:
return Checkpoint{}, fmt.Errorf("checkpoint %s: stat: %w", abs, err)
case info.IsDir() || !info.Mode().IsRegular():
return Checkpoint{}, fmt.Errorf("checkpoint %s: refusing to checkpoint non-regular file (%s)", abs, info.Mode())
default:
content, readErr := os.ReadFile(abs)
if readErr != nil {
return Checkpoint{}, fmt.Errorf("checkpoint %s: read: %w", abs, readErr)
}
cp.Existed = true
cp.Mode = info.Mode().Perm()
cp.Content = content
}
sum := sha256.Sum256(append([]byte(abs+"\x00"), cp.Content...))
cp.ID = fmt.Sprintf("%019d-%s", cp.CreatedAt.UnixNano(), hex.EncodeToString(sum[:6]))
if err := s.write(cp); err != nil {
return Checkpoint{}, err
}
return cp, nil
}
// write persists one checkpoint atomically.
func (s *CheckpointStore) write(cp Checkpoint) error {
if err := os.MkdirAll(s.root, 0o700); err != nil {
return fmt.Errorf("checkpoint %s: create store %s: %w", cp.Path, s.root, err)
}
data, err := json.Marshal(cp)
if err != nil {
return fmt.Errorf("checkpoint %s: encode: %w", cp.Path, err)
}
if err := writeFileAtomic(filepath.Join(s.root, cp.ID+".json"), data, 0o600); err != nil {
return fmt.Errorf("checkpoint %s: persist: %w", cp.Path, err)
}
return nil
}
// RestoreLatest puts path back to its most recently taken checkpoint and
// returns that checkpoint. A path with no checkpoint is an error, never a
// silent no-op: a rollback that quietly does nothing is worse than one that
// says it could not.
func (s *CheckpointStore) RestoreLatest(path string) (Checkpoint, error) {
abs, err := filepath.Abs(path)
if err != nil {
return Checkpoint{}, fmt.Errorf("restore %s: resolve path: %w", path, err)
}
cp, ok, err := s.latest(abs)
if err != nil {
return Checkpoint{}, err
}
if !ok {
return Checkpoint{}, fmt.Errorf("restore %s: no checkpoint recorded", abs)
}
if err := s.restore(cp); err != nil {
return Checkpoint{}, err
}
return cp, nil
}
// latest returns the newest checkpoint recorded for abs.
func (s *CheckpointStore) latest(abs string) (Checkpoint, bool, error) {
entries, err := os.ReadDir(s.root)
if errors.Is(err, os.ErrNotExist) {
return Checkpoint{}, false, nil
}
if err != nil {
return Checkpoint{}, false, fmt.Errorf("restore %s: read store: %w", abs, err)
}
var matches []Checkpoint
for _, entry := range entries {
if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") {
continue
}
data, readErr := os.ReadFile(filepath.Join(s.root, entry.Name()))
if readErr != nil {
return Checkpoint{}, false, fmt.Errorf("restore %s: read checkpoint %s: %w", abs, entry.Name(), readErr)
}
var cp Checkpoint
if jsonErr := json.Unmarshal(data, &cp); jsonErr != nil {
return Checkpoint{}, false, fmt.Errorf("restore %s: decode checkpoint %s: %w", abs, entry.Name(), jsonErr)
}
if cp.Path == abs {
matches = append(matches, cp)
}
}
if len(matches) == 0 {
return Checkpoint{}, false, nil
}
sort.Slice(matches, func(i, j int) bool {
if matches[i].CreatedAt.Equal(matches[j].CreatedAt) {
return matches[i].ID > matches[j].ID
}
return matches[i].CreatedAt.After(matches[j].CreatedAt)
})
return matches[0], true, nil
}
// restore writes a checkpoint's state back to its path.
func (s *CheckpointStore) restore(cp Checkpoint) error {
if !cp.Existed {
if err := os.Remove(cp.Path); err != nil && !errors.Is(err, os.ErrNotExist) {
return fmt.Errorf("restore %s: remove: %w", cp.Path, err)
}
return nil
}
mode := cp.Mode
if mode == 0 {
mode = 0o644
}
if err := writeFileAtomic(cp.Path, cp.Content, mode); err != nil {
return fmt.Errorf("restore %s: write: %w", cp.Path, err)
}
return nil
}
+209
View File
@@ -0,0 +1,209 @@
package builtin
import (
"context"
"encoding/json"
"os"
"path/filepath"
"testing"
)
// A write takes a checkpoint of the file it is about to replace, and that
// checkpoint puts the original bytes back.
func TestWriteTool_CheckpointRestoresOriginal(t *testing.T) {
tmp := t.TempDir()
path := filepath.Join(tmp, "f.txt")
original := "original\n"
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
t.Fatal(err)
}
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
res, err := tool.Execute(context.Background(), json.RawMessage(
`{"path":"f.txt","content":"changed\n","overwrite":true}`,
), nil)
if err != nil {
t.Fatalf("execute: %v", err)
}
if res.IsError {
t.Fatalf("write failed: %s", res.Content)
}
store := NewCheckpointStore(tmp)
if _, err := store.RestoreLatest(path); err != nil {
t.Fatalf("RestoreLatest: %v", err)
}
got, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if string(got) != original {
t.Fatalf("restored content = %q, want %q", got, original)
}
}
// A checkpoint taken before creating a file restores by removing it: the
// recorded pre-state is "did not exist".
func TestWriteTool_CheckpointOfNewFileRestoresAbsence(t *testing.T) {
tmp := t.TempDir()
path := filepath.Join(tmp, "created.txt")
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
res, err := tool.Execute(context.Background(), json.RawMessage(
`{"path":"created.txt","content":"new\n"}`,
), nil)
if err != nil {
t.Fatalf("execute: %v", err)
}
if res.IsError {
t.Fatalf("write failed: %s", res.Content)
}
store := NewCheckpointStore(tmp)
if _, err := store.RestoreLatest(path); err != nil {
t.Fatalf("RestoreLatest: %v", err)
}
if _, statErr := os.Stat(path); !os.IsNotExist(statErr) {
t.Fatalf("expected restore to remove the created file, stat err = %v", statErr)
}
}
// Edit is a mutating tool too, and its checkpoint restores the original.
func TestEditTool_CheckpointRestoresOriginal(t *testing.T) {
tmp := t.TempDir()
path := filepath.Join(tmp, "f.txt")
original := "one\ntwo\nthree\n"
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
t.Fatal(err)
}
tool := NewEditTool(tmp, NewMutationQueue(), nil)
res, err := tool.Execute(context.Background(), json.RawMessage(
`{"path":"f.txt","edits":[{"old_text":"two","new_text":"TWO"}]}`,
), nil)
if err != nil {
t.Fatalf("execute: %v", err)
}
if res.IsError {
t.Fatalf("edit failed: %s", res.Content)
}
store := NewCheckpointStore(tmp)
if _, err := store.RestoreLatest(path); err != nil {
t.Fatalf("RestoreLatest: %v", err)
}
got, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if string(got) != original {
t.Fatalf("restored content = %q, want %q", got, original)
}
}
// Two mutations in a row leave two checkpoints; restore returns the most
// recent pre-state, not the oldest.
func TestWriteTool_CheckpointRestoresMostRecentState(t *testing.T) {
tmp := t.TempDir()
path := filepath.Join(tmp, "f.txt")
if err := os.WriteFile(path, []byte("v1\n"), 0o644); err != nil {
t.Fatal(err)
}
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
for _, content := range []string{"v2", "v3"} {
res, err := tool.Execute(context.Background(), json.RawMessage(
`{"path":"f.txt","content":"`+content+`\n","overwrite":true}`,
), nil)
if err != nil {
t.Fatalf("execute: %v", err)
}
if res.IsError {
t.Fatalf("write failed: %s", res.Content)
}
}
store := NewCheckpointStore(tmp)
if _, err := store.RestoreLatest(path); err != nil {
t.Fatalf("RestoreLatest: %v", err)
}
got, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if string(got) != "v2\n" {
t.Fatalf("restored content = %q, want %q", got, "v2\n")
}
}
// A mutation whose checkpoint cannot be taken must not happen. Blocking the
// store (.git/archie-checkpoints is a regular file) must leave the file
// untouched and the tool reporting an error, never a silent write.
func TestWriteTool_RefusesMutationWhenCheckpointFails(t *testing.T) {
tmp := t.TempDir()
path := filepath.Join(tmp, "f.txt")
original := "original\n"
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
t.Fatal(err)
}
blockCheckpointStore(t, tmp)
tool := NewWriteTool(tmp, NewMutationQueue(), nil)
res, err := tool.Execute(context.Background(), json.RawMessage(
`{"path":"f.txt","content":"changed\n","overwrite":true}`,
), nil)
if err != nil {
t.Fatalf("execute: %v", err)
}
if !res.IsError {
t.Fatalf("expected the write to be refused without a checkpoint, got: %#v", res)
}
got, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if string(got) != original {
t.Fatalf("file was mutated without a checkpoint: %q", got)
}
}
// Same fail-closed rule for edit.
func TestEditTool_RefusesMutationWhenCheckpointFails(t *testing.T) {
tmp := t.TempDir()
path := filepath.Join(tmp, "f.txt")
original := "one\ntwo\n"
if err := os.WriteFile(path, []byte(original), 0o644); err != nil {
t.Fatal(err)
}
blockCheckpointStore(t, tmp)
tool := NewEditTool(tmp, NewMutationQueue(), nil)
res, err := tool.Execute(context.Background(), json.RawMessage(
`{"path":"f.txt","edits":[{"old_text":"two","new_text":"TWO"}]}`,
), nil)
if err != nil {
t.Fatalf("execute: %v", err)
}
if !res.IsError {
t.Fatalf("expected the edit to be refused without a checkpoint, got: %#v", res)
}
got, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if string(got) != original {
t.Fatalf("file was mutated without a checkpoint: %q", got)
}
}
// blockCheckpointStore makes the checkpoint store's parent a regular file so
// MkdirAll of the store directory cannot succeed.
func blockCheckpointStore(t *testing.T, workspace string) {
t.Helper()
if err := os.MkdirAll(filepath.Join(workspace, ".git"), 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(workspace, ".git", "archie-checkpoints"), []byte("blocked"), 0o600); err != nil {
t.Fatal(err)
}
}
+11 -4
View File
@@ -75,7 +75,7 @@ func NewEditTool(cwd string, mq *MutationQueue, rt *ReadTracker) Tool {
Schema: editSchema,
Source: "builtin",
Emoji: "✏️",
Execute: makeEditExecutor(cwd, mq, rt),
Execute: makeEditExecutor(cwd, mq, rt, NewCheckpointStore(cwd)),
}
}
@@ -121,7 +121,7 @@ func parseEditParams(params json.RawMessage) (EditParams, error) {
return p, nil
}
func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker, cp *CheckpointStore) Executor {
return func(ctx context.Context, params json.RawMessage, _ UIBridge) (Result, error) {
p, err := parseEditParams(params)
if err != nil {
@@ -150,7 +150,7 @@ func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
var result Result
err = runWithContext(editCtx, func() error {
result = performEdit(path, p, mq)
result = performEdit(path, p, mq, cp)
return nil
})
if err != nil {
@@ -167,7 +167,7 @@ func makeEditExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
// performEdit loads, mutates, and writes path according to the edits in p.
// Every failure is returned as a Result with IsError set, never a non-nil
// error, so the executor keeps a single error envelope.
func performEdit(path string, p EditParams, mq *MutationQueue) Result {
func performEdit(path string, p EditParams, mq *MutationQueue, cp *CheckpointStore) Result {
// Check file size before reading to avoid OOM on large files.
info, err := os.Stat(path)
if err != nil {
@@ -217,6 +217,13 @@ func performEdit(path string, p EditParams, mq *MutationQueue) Result {
newContent = strings.ReplaceAll(newContent, "\n", "\r\n")
}
// Snapshot immediately before the write. applyEdits has already run, so
// a rejected edit leaves no checkpoint behind, and the mutation lock is
// held, so nothing can change the file between here and the write.
if _, err := cp.Snapshot(path); err != nil {
return Result{Content: fmt.Sprintf("refusing to edit %s: %v", path, err), IsError: true, ErrorKind: "checkpoint_failed"}
}
if err := writeFileAtomic(path, []byte(bom+newContent), 0o644); err != nil {
return Result{Content: fmt.Sprintf("error writing file: %v", err), IsError: true}
}
+10 -2
View File
@@ -54,11 +54,11 @@ func NewWriteTool(cwd string, mq *MutationQueue, rt *ReadTracker) Tool {
Schema: writeSchema,
Source: "builtin",
Emoji: "📝",
Execute: makeWriteExecutor(cwd, mq, rt),
Execute: makeWriteExecutor(cwd, mq, rt, NewCheckpointStore(cwd)),
}
}
func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor {
func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker, cp *CheckpointStore) Executor {
return func(ctx context.Context, params json.RawMessage, _ UIBridge) (Result, error) {
var p WriteParams
if err := json.Unmarshal(params, &p); err != nil {
@@ -92,6 +92,14 @@ func makeWriteExecutor(cwd string, mq *MutationQueue, rt *ReadTracker) Executor
release := mq.Acquire(path)
defer release()
// Snapshot before the first byte changes. If the checkpoint cannot
// be taken the write is refused: proceeding would produce a
// mutation with nothing to restore from.
if _, err := cp.Snapshot(path); err != nil {
result = Result{Content: fmt.Sprintf("refusing to write %s: %v", path, err), IsError: true, ErrorKind: "checkpoint_failed"}
return nil
}
dir := filepath.Dir(path)
if err := os.MkdirAll(dir, 0o755); err != nil {
result = Result{Content: fmt.Sprintf("error creating directory: %v", err), IsError: true}