refactor: make memory subagent self-contained, eliminate defrag skill (#1180)

src/agent/subagents/builtin/memory.md

@@ -1,7 +1,7 @@
 ---
 name: memory
 description: Decompose and reorganize memory files into focused, single-purpose files using `/` naming
-tools: Read, Edit, Write, Glob, Grep, Bash
+tools: Read, Edit, Write, Glob, Grep, Bash, TaskOutput
 model: sonnet
 memoryBlocks: none
 permissionMode: bypassPermissions
@@ -68,20 +68,48 @@ Do **not** edit:
 
 ## Operating Procedure
 
+### Phase 0: Setup
+
+The memory directory is at:
+`~/.letta/agents/$LETTA_AGENT_ID/memory/`
+
+```bash
+MEMORY_DIR=~/.letta/agents/$LETTA_AGENT_ID/memory
+WORKTREE_DIR=~/.letta/agents/$LETTA_AGENT_ID/memory-worktrees
+```
+
+The memory directory should already be a git repo
+(initialized when MemFS was enabled). If it's not, or
+if git is unavailable, report the issue and exit without
+making changes.
+
+**Create worktree:**
+
+```bash
+BRANCH="defrag-$(date +%s)"
+mkdir -p "$WORKTREE_DIR"
+cd "$MEMORY_DIR"
+git worktree add "$WORKTREE_DIR/$BRANCH" -b "$BRANCH"
+```
+
+All subsequent file operations target the worktree:
+`$WORKTREE_DIR/$BRANCH/system/` (not the main memory dir).
+
 ### Step 1: Inventory
 
 First, list what files are available:
 
 ```bash
-ls ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
+WORK=$WORKTREE_DIR/$BRANCH/system
+ls $WORK/
 ```
 
 Then read relevant memory files:
 
 ```
-Read({ file_path: "~/.letta/agents/$LETTA_AGENT_ID/memory/system/project.md" })
-Read({ file_path: "~/.letta/agents/$LETTA_AGENT_ID/memory/system/persona.md" })
-Read({ file_path: "~/.letta/agents/$LETTA_AGENT_ID/memory/system/human.md" })
+Read({ file_path: "$WORK/project.md" })
+Read({ file_path: "$WORK/persona.md" })
+Read({ file_path: "$WORK/human.md" })
 ```
 
 ### Step 2: Identify system-managed files (skip)
@@ -149,6 +177,139 @@ For each edited file: before/after chars, delta, what was fixed
 #### 4) Before/after examples
 2–4 examples showing redundancy removal, contradiction resolution, or structure improvements
 
+### Phase 5: Merge, Push, and Clean Up (MANDATORY)
+
+Your defrag has two completion states:
+- **Complete**: merged to main AND pushed to remote.
+- **Partially complete**: merged to main, push failed.
+  Clean up the worktree, but report that local main is
+  ahead of remote and needs a push.
+
+The commit in the worktree is neither — it's an intermediate
+step. Without at least a merge to main, your work is lost.
+
+**Step 5a: Commit in worktree**
+
+```bash
+MEMORY_DIR=~/.letta/agents/$LETTA_AGENT_ID/memory
+WORKTREE_DIR=~/.letta/agents/$LETTA_AGENT_ID/memory-worktrees
+cd $WORKTREE_DIR/$BRANCH
+git add -A
+```
+
+Check `git status` — if there are no changes to commit,
+skip straight to Step 5d (cleanup). Report "no updates
+needed" in your output.
+
+If there are changes, commit:
+
+```bash
+git commit -m "chore(defrag): <summary>"
+```
+
+**Step 5b: Pull + merge to main**
+
+```bash
+cd $MEMORY_DIR
+```
+
+First, check that main is in a clean state (`git status`).
+If a merge or rebase is in progress (lock file, dirty
+index), wait and retry up to 3 times with backoff (sleep 2,
+5, 10 seconds). Never delete `.git/index.lock` manually.
+If still busy after retries, go to Error Handling.
+
+Pull from remote:
+
+```bash
+git pull --ff-only
+```
+
+If `--ff-only` fails (remote has diverged), fall back:
+
+```bash
+git pull --rebase
+```
+
+If rebase has conflicts, resolve them autonomously to
+stabilize local `main` against remote `main` first. In this
+step, prefer **remote main** content for conflicting files,
+then run `git rebase --continue`.
+
+Now merge the defrag branch:
+
+```bash
+git merge $BRANCH --no-edit
+```
+
+If the merge has conflicts, resolve by preferring defrag
+branch/worktree content for memory files, stage the resolved
+files, and complete with `git commit --no-edit`.
+
+If you cannot resolve conflicts after 2 attempts, go to
+Error Handling.
+
+**Step 5c: Push to remote**
+
+```bash
+git push
+```
+
+If push fails, retry once. If it still fails, report that
+local main is ahead of remote and needs a push. Proceed to
+cleanup — the merge succeeded and data is safe on local
+main.
+
+**Step 5d: Clean up worktree and branch**
+
+Only clean up when merge to main completed (success or
+partially complete):
+
+```bash
+git worktree remove $WORKTREE_DIR/$BRANCH
+git branch -d $BRANCH
+```
+
+**Step 5e: Verify**
+
+```bash
+git status
+git log --oneline -3
+```
+
+Confirm main is clean and your defrag commit is visible
+in the log.
+
+## Error Handling
+
+If anything goes wrong at any phase:
+
+1. Stabilize main first (abort in-progress operations):
+   ```bash
+   cd $MEMORY_DIR
+   git merge --abort 2>/dev/null
+   git rebase --abort 2>/dev/null
+   ```
+
+2. Do NOT clean up the worktree or branch on failure —
+   preserve them for debugging and manual recovery.
+
+3. Report clearly in your output:
+   - What failed and the error message
+   - Worktree path: `$WORKTREE_DIR/$BRANCH`
+   - Branch name: `$BRANCH`
+   - Whether main has uncommitted/dirty state
+   - Concrete resume commands, e.g.:
+     ```bash
+     cd ~/.letta/agents/$LETTA_AGENT_ID/memory
+     git merge <branch-name> --no-edit
+     git push
+     git worktree remove ../memory-worktrees/<branch-name>
+     git branch -d <branch-name>
+     ```
+
+4. Do NOT leave uncommitted changes on main.
+
 ## Final Checklist
 
 Before submitting, confirm:
@@ -158,6 +319,7 @@ Before submitting, confirm:
 - [ ] **Hierarchy is 2–3 levels deep**
 - [ ] **No file exceeds ~40 lines**
 - [ ] **Each file has one concept**
+- [ ] **Changes committed, merged to main, and pushed**
 
 **If you have fewer than 15 files, you haven't split enough.**