feat: delete a node from the DAG (agentenv delete + ctl + MCP)

Adds node deletion (previously you could only create nodes):
- dag.Repo.Delete splices a node out, re-parenting its children to its parent
  so descendants survive; drops tags pointing at it.
- repo.Delete: refuses to delete the current HEAD (would orphan the live work
  tree — checkout elsewhere first) or the only node; persists metadata then
  removes the snapshot dir. Safe even when children hardlink-share the deleted
  node's files (shared inodes stay alive — same reason gc is safe).
- Surfaces as 'agentenv delete <node>', the daemon 'delete' op (ctl + bare
  command auto-routes), and the agentenv__delete MCP tool so Claude Code can
  prune dead-end explorations itself.

Verified: deleting a middle node re-parents children; checkout of a survivor
still reads its content (hardlinks intact); the deleted snapshot dir is gone;
deleting HEAD is refused.

Author: css521

internal/api/server.go

@@ -176,6 +176,12 @@ func dispatch(r *repo.Repo, c *repo.Capturer, req request) response {
 		}
 		return response{OK: true, Head: r.Head()}
 
+	case "delete":
+		if err := r.Delete(req.Node); err != nil {
+			return response{Error: err.Error()}
+		}
+		return response{OK: true, Head: r.Head()}
+
 	case "commit":
 		n, err := r.Commit(req.Message, "")
 		if err != nil {

internal/cli/cli.go

@@ -47,6 +47,7 @@ var commandList = []*command{
 	{"branches", "", "list branch tips (distinct explored end-states)", false, cmdBranches},
 	{"show", "<node>", "files this node changed vs its parent", false, cmdShow},
 	{"diff", "<a> <b>", "files that differ between two nodes", false, cmdDiff},
+	{"delete", "<node>", "remove a node from the DAG (children re-parent to its parent)", true, cmdDelete},
 	{"gc", "", "delete orphan snapshots (reclaims sparsified ones)", true, cmdGC},
 }
 

internal/cli/commands.go

@@ -310,6 +310,19 @@ func cmdTournament(r *repo.Repo, args []string) error {
 	return nil
 }
 
+// cmdDelete removes a node from the commit-DAG (and its snapshot). Children are
+// re-parented to the node's parent, so descendants survive.
+func cmdDelete(r *repo.Repo, args []string) error {
+	if len(args) < 1 {
+		return fmt.Errorf("usage: agentenv delete <node>")
+	}
+	if err := r.Delete(args[0]); err != nil {
+		return err
+	}
+	fmt.Printf("deleted %s\n", args[0])
+	return nil
+}
+
 func cmdGC(r *repo.Repo, _ []string) error {
 	removed, err := r.GC()
 	if err != nil {

internal/cli/ctl.go

@@ -27,7 +27,7 @@ func cmdCtl(args []string) error {
 	req := map[string]any{"op": op}
 	switch op {
 	case "log", "head", "branches", "gc", "ps":
-	case "checkout", "show":
+	case "checkout", "show", "delete":
 		if len(a) < 1 {
 			return fmt.Errorf("usage: agentenv ctl %s <node>", op)
 		}

internal/cli/run.go

@@ -21,7 +21,7 @@ import (
 // are excluded — they must own the lock themselves.
 func ctlRoutable(name string) bool {
 	switch name {
-	case "checkout", "commit", "exec", "tag", "gc", "tournament":
+	case "checkout", "commit", "exec", "tag", "gc", "tournament", "delete":
 		return true
 	}
 	return false

internal/dag/dag.go

@@ -139,6 +139,54 @@ func (r *Repo) Get(id string) (*Node, bool) {
 	return n, ok
 }
 
+// Delete removes node id from the graph, splicing it out: its children are
+// re-parented to id's parent (so the tree stays connected — deleting a middle
+// node keeps its descendants), and any tags pointing at id are dropped. The
+// caller is responsible for the policy checks (not HEAD, not the only node) and
+// for removing the on-disk snapshot. Returns id's former parent ("" if it was a
+// root) and whether the node existed.
+func (r *Repo) Delete(id string) (parent string, ok bool) {
+	n, ok := r.Nodes[id]
+	if !ok {
+		return "", false
+	}
+	parent = n.Parent
+	for _, cid := range n.Children {
+		c := r.Nodes[cid]
+		if c == nil {
+			continue
+		}
+		c.Parent = parent
+		if parent != "" {
+			if p := r.Nodes[parent]; p != nil {
+				p.Children = append(p.Children, cid)
+			}
+		}
+	}
+	if parent != "" {
+		if p := r.Nodes[parent]; p != nil {
+			p.Children = removeID(p.Children, id)
+		}
+	}
+	delete(r.Nodes, id)
+	for name, tid := range r.Tags {
+		if tid == id {
+			delete(r.Tags, name)
+		}
+	}
+	return parent, true
+}
+
+func removeID(ids []string, id string) []string {
+	out := ids[:0]
+	for _, x := range ids {
+		if x != id {
+			out = append(out, x)
+		}
+	}
+	return out
+}
+
 // Roots returns all nodes without a parent (normally just one).
 func (r *Repo) Roots() []*Node {
 	var out []*Node

internal/mcp/server.go

@@ -122,6 +122,17 @@ func register(s *mcp.Server, sock string) {
 	}, func(_ context.Context, _ *mcp.CallToolRequest, in nodeArgs) (*mcp.CallToolResult, any, error) {
 		return relay(sock, "checkout", map[string]any{"node": in.Node}, formatHead)
 	})
+
+	mcp.AddTool(s, &mcp.Tool{
+		Name:        "agentenv__delete",
+		Description: "Delete a node from the history (accepts node id, ID prefix, or tag). Its children re-parent to its parent, so descendants survive. Refuses to delete the current HEAD (check out another node first) or the only node. Use to prune dead-end explorations.",
+	}, func(_ context.Context, _ *mcp.CallToolRequest, in nodeArgs) (*mcp.CallToolResult, any, error) {
+		return relay(sock, "delete", map[string]any{"node": in.Node}, formatDeleted)
+	})
+}
+
+func formatDeleted(r *protocol.Response) string {
+	return "deleted; HEAD is " + r.Head
 }
 
 // relay issues a single daemon round-trip and packages the response. Errors

internal/repo/repo.go

@@ -686,6 +686,48 @@ func (r *Repo) Checkout(ref string) error {
 	return r.dag.Save()
 }
 
+// Delete removes a node from the DAG and deletes its on-disk snapshot. Its
+// children are re-parented to its parent so the tree stays connected (deleting
+// a middle node keeps its descendants). Refuses to delete the current HEAD (it
+// would orphan the live working tree — checkout elsewhere first) or the last
+// remaining node. Deleting a node's snapshot is safe even if children
+// hardlink-share its files: the shared inodes stay alive as long as a child
+// still references them (same reason GC is safe).
+func (r *Repo) Delete(ref string) error {
+	r.opMu.Lock()
+	defer r.opMu.Unlock()
+
+	id := r.resolveRefLocked(ref)
+	if id == "" {
+		return fmt.Errorf("unknown ref: %s", ref)
+	}
+	if id == r.dag.Head {
+		return fmt.Errorf("refusing to delete the current HEAD node %s — `agentenv checkout <other>` first", short(id))
+	}
+	if len(r.dag.Nodes) <= 1 {
+		return fmt.Errorf("refusing to delete the only node")
+	}
+	if _, ok := r.dag.Delete(id); !ok {
+		return fmt.Errorf("no such node: %s", id)
+	}
+	// Persist the metadata first (consistent DAG), then remove the snapshot dir.
+	// If the rm fails afterward it's a harmless orphan that `gc` reclaims.
+	if err := r.dag.Save(); err != nil {
+		return err
+	}
+	if err := r.be.Snapshotter.DeleteNode(id); err != nil {
+		fmt.Fprintf(os.Stderr, "agentenv: WARN deleted node %s from the DAG but could not remove its snapshot (gc will): %v\n", short(id), err)
+	}
+	return nil
+}
+
+func short(id string) string {
+	if len(id) > 12 {
+		return id[:12]
+	}
+	return id
+}
+
 // Head returns the current HEAD node ID.
 func (r *Repo) Head() string { return r.dag.Head }
 

verify/docker/mcp-smoke.sh

@@ -85,8 +85,8 @@ ok "initialize → protocol=$PROTOCOL serverInfo=$SRV_NAME"
 # --- id=2: tools/list -------------------------------------------------------
 TOOLS_LIST=$(byid 2)
 TOOL_COUNT=$(echo "$TOOLS_LIST" | jq '.result.tools | length')
-[ "$TOOL_COUNT" = "6" ] || die "tools/list: expected 6 tools, got $TOOL_COUNT"
-for want in agentenv__head agentenv__log agentenv__branches agentenv__show agentenv__diff agentenv__checkout; do
+[ "$TOOL_COUNT" = "7" ] || die "tools/list: expected 7 tools, got $TOOL_COUNT"
+for want in agentenv__head agentenv__log agentenv__branches agentenv__show agentenv__diff agentenv__checkout agentenv__delete; do
   echo "$TOOLS_LIST" | jq -e ".result.tools[] | select(.name == \"$want\")" >/dev/null \
     || die "tools/list: missing $want"
 done