---
name: update
description: "Update Clawdie from upstream or apply local changes safely with ZFS rollback. Takes a pre-update snapshot, pulls changes, validates build/tests, and supports instant rollback via ZFS. Triggers on \"update\", \"pull upstream\", \"sync with upstream\", \"get latest changes\"."
---

# Clawdie Update

Pull upstream changes and merge them with the current installation, using ZFS snapshots for rollback safety. The update skill always takes a snapshot before applying changes so rollback is instant via `zfs rollback`.

**Principle:** Handle everything automatically. Only pause for user confirmation before applying changes, or when merge conflicts need human judgment. Never leave the system in a broken state — if the update fails, roll back to the snapshot.

**UX Note:** Use `AskUserQuestion` for all user-facing questions.

**Attribution:** The upstream update mechanism and skills engine originate from [NanoClaw](https://github.com/openclaw/nanoclaw) by [Gavriel](https://github.com/openclaw), part of the [OpenClaw](https://github.com/openclaw/openclaw) ecosystem by [Peter Steinberger](https://github.com/steipete). Clawdie extends this with ZFS snapshot-based rollback on FreeBSD.

## 1. Pre-flight

### Check current version

```bash
node -e "console.log(require('./package.json').version)"
```

### Check for uncommitted changes

```bash
git status --porcelain
```

**If there are uncommitted changes:** AskUserQuestion: "You have uncommitted changes. Commit or stash before updating? Options: Continue anyway / Abort (I'll commit first)". If abort, stop.

### Check remote

```bash
git remote -v
```

Verify `origin` points to `codeberg.org:Clawdie/Clawdie-AI.git`. If not, warn the user.

### Check Sanoid status

```bash
sanoid --version 2>/dev/null && echo "SANOID_OK" || echo "NO_SANOID"
```

If Sanoid is running, note it — we'll rely on it for automated retention. The manual pre-update snapshot is separate and intentional.

## 2. ZFS Pre-Update Snapshot

**This is mandatory.** Always snapshot before applying changes.

### Snapshot the control-plane dataset

```bash
SNAP_NAME="pre-update-$(date +%d-%b-%Y-%H%M | tr '[:upper:]' '[:lower:]')"
sudo zfs snapshot zroot/clawdie-runtime/jails/controlplane@${SNAP_NAME}
```

### Verify snapshot was created

```bash
zfs list -t snapshot -r zroot/clawdie-runtime/jails/controlplane | tail -3
```

Record the snapshot name for potential rollback.

### Snapshot the database too (if db jail exists)

```bash
zfs list zroot/clawdie-runtime/jails/db 2>/dev/null && \
  sudo zfs snapshot zroot/clawdie-runtime/jails/db@${SNAP_NAME}
```

## 3. Fetch Changes

### Fetch from origin

```bash
git fetch origin main
```

### Check what's new

```bash
git log HEAD..origin/main --oneline
```

**If no new commits:** Tell the user they're already up to date. AskUserQuestion: "Already up to date. Force pull anyway? Options: Yes / No". If no, stop.

### Preview changes

```bash
git diff --stat HEAD..origin/main
```

Present to the user:
- Number of files changed
- Key files affected (src/, .agent/skills/, docs/)
- Any package.json version bump

## 4. Confirm

AskUserQuestion: "Apply this update? ZFS snapshot `{SNAP_NAME}` is ready for rollback if anything breaks. Options: Yes, apply / No, cancel"

If cancelled, stop. The snapshot remains (Sanoid will handle retention).

## 5. Apply

### Stop the service (if running)

```bash
service clawdie status 2>/dev/null && sudo service clawdie stop
```

### Pull changes

```bash
git pull origin main
```

**If merge conflicts:**

For each conflicting file:
1. Read the file — look for conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
2. Check if there's an intent file in `.agent/skills/<skill>/modify/<path>.intent.md`
3. Resolve using the intent file and codebase understanding
4. `git add <file>` after resolving

If you cannot confidently resolve a conflict, show the user the conflicting sections and ask for guidance.

### Install dependencies (if package.json changed)

```bash
git diff HEAD~1 --name-only | grep -q "package.json" && npm install
```

## 6. Build and Test

### Build

```bash
npm run build
```

**If build fails:**
- Type errors: read the error, fix the file, retry
- Missing dependencies: `npm install` first, retry
- Native module issues: `npm rebuild better-sqlite3`

### Run tests

```bash
npm test
```

**If tests fail:** Show which tests failed. Try to diagnose and fix. If unfixable, warn user and offer rollback.

### Type check

```bash
npm run typecheck
```

## 7. Post-Update Validation

### Run doctor

```bash
npm run doctor
```

### Restart service

```bash
sudo service clawdie start
service clawdie status
```

### Verify Telegram connectivity

Check logs for successful bot startup:

```bash
tail -20 logs/clawdie.log
```

## 8. Rollback (If Needed)

If the update broke something and you need to roll back:

### Stop service

```bash
sudo service clawdie stop
```

### Roll back ZFS

```bash
sudo zfs rollback zroot/clawdie-runtime/jails/controlplane@${SNAP_NAME}
```

If db was also snapshotted:

```bash
sudo zfs rollback zroot/clawdie-runtime/jails/db@${SNAP_NAME}
```

### Rebuild and restart

```bash
npm run build
sudo service clawdie start
```

### Verify rollback

```bash
node -e "console.log(require('./package.json').version)"
npm run doctor
```

The rollback is instant because ZFS snapshots are atomic.

## 9. Cleanup

After a successful update (service running, tests passing, Telegram working):

### Take a post-update milestone snapshot

```bash
NEW_VERSION=$(node -e "console.log(require('./package.json').version)")
sudo zfs snapshot zroot/clawdie-runtime/jails/controlplane@v${NEW_VERSION}-$(date +%d-%b-%Y | tr '[:upper:]' '[:lower:]')
```

### Report status

- "Updated from **{old_version}** to **{new_version}**"
- Files changed count
- Build and test status
- Pre-update snapshot name (for manual rollback reference)
- Sanoid will handle snapshot retention automatically

## Troubleshooting

**Merge conflicts in many files:** Consider whether extensive local modifications are conflicting with upstream. Use the skills system for customizations instead of direct edits — skills survive updates better.

**Build fails after update:** Check if dependencies changed. Run `npm install` to pick up new packages. Check for breaking TypeScript changes.

**Service won't start after update:** Check `logs/clawdie.error.log`. If unfixable, roll back with ZFS: `sudo zfs rollback zroot/clawdie-runtime/jails/controlplane@{SNAP_NAME}`.

**ZFS snapshot missing:** If the pre-update snapshot wasn't taken (manual setup without ZFS), fall back to `git reset --hard HEAD~1` but this is less safe. Always prefer ZFS rollback.

**Sanoid retention:** Pre-update snapshots follow the day-first naming convention. Sanoid's automated retention policy will eventually clean old pre-update snapshots according to the policy defined in `/sanoid` skill.
