Workspace Rename

Rename a WorkBuddy workspace and keep its internal bookkeeping consistent. WorkBuddy keys two kinds of state to the workspace folder path: a per-workspace mirror directory under ~/.workbuddy/projects/ and a workDir field per session in ~/.workbuddy/app/sessions.json. Renaming only the folder leaves stale pointers that break the recent-workspaces list and orphan session history.

When to use

• A user wants to rename a workspace folder (e.g. 2026-08-02-19-41-13 → 坤坤工作台).
• A user wants to move/relocate a workspace to a different parent directory (e.g. C:\Users\ROG\WorkBuddy\foo → D:\Projects\foo). "Move" is just a rename with a new parent — the mirror name and workDir are derived from the full absolute path, so moving is supported out of the box.
• A rename/move produced Device or resource busy (the folder was open/locked).
• After a rename/move, old session entries point to a nonexistent folder.

Procedure

1. Release the lock. Switch to another workspace or close WorkBuddy entirely before touching the folder. A folder opened by WorkBuddy cannot be renamed/moved and reports Device or resource busy. This is mandatory for MOVES (cross-drive): a move ends with deleting the source, and that delete is blocked both by a held lock and by some sandboxed shells' safe-delete. A same-drive rename often works while the workspace is open; a move usually does not — always close it first.
2. Rename/move the folder. Use File Explorer, mv from a different workspace's terminal, or the script's --move flag (which relocates the folder for you). Do NOT use WorkBuddy's in-app file pane. When moving to a new parent, make sure that parent directory exists first (the --move flag creates it automatically).
3. Sync the projects mirror directory. Compute the mirror name with path.lower().replace(":", "").replace("\\", "-").replace("/", "-") and rename ~/.workbuddy/projects/<old-mirror> to <new-mirror>.
4. Sync sessions.json. For every session whose workDir equals the old path, set it to the new path. Edit through a JSON parser (json.load/json.dump) — never a naive string replace, because backslashes are escaped as \\ in the file and a literal search misses them.
5. Verify. Search sessions.json and ~/.workbuddy/projects/ for the old path; confirm zero matches and that the workspace reopens normally.

Helper script

Run scripts/rename_workspace.py to perform steps 3–4 deterministically. With --move it also relocates the actual folder (step 2), so the whole operation becomes one command:

# Rename only (you move the folder yourself first):
python scripts/rename_workspace.py "<OLD_PATH>" "<NEW_PATH>" [--dry-run]

# Rename AND move the folder in one shot (auto-creates the new parent dir):
python scripts/rename_workspace.py "<OLD_PATH>" "<NEW_PATH>" --move [--dry-run]

# Example — move a workspace to another drive:
python scripts/rename_workspace.py "C:\Users\ROG\WorkBuddy\foo" "D:\Projects\坤坤工作台" --move

The script renames the projects mirror directory and rewrites all matching workDir values in sessions.json using a JSON parser (backslashes stay correct). Pass --dry-run to preview changes without writing. With --move, the folder relocation runs FIRST; if it fails (e.g. the folder is open in WorkBuddy), the script aborts before touching any references, so you never end up with a half-synced state. Steps 1 (release the lock) must still be done by the user/agent when the folder is the currently open workspace.

Leftover mirror directories for deleted workspaces are cleaned up manually: review ~/.workbuddy/projects/ and delete any mirror whose workspace folder no longer exists, after preserving its session history. Auto-detection is unreliable because folder names containing hyphens cannot be reversed from the mirror name.

Pitfalls

• Renaming/moving while the workspace is open → Device or resource busy. Always release the lock first.
• Editing sessions.json with a plain string replace fails: backslashes are stored escaped (\\), so the search string never matches. Use a JSON parser (the bundled script does this).
• Renaming/moving to a name that was a previous rename target leaves an extra stale mirror directory; delete it after confirming its session history was preserved.
• workbuddy.db may still contain an old cwd pointer; it affects only old chat records and does not break functionality, so it can be left as-is.
• With --move to a new parent directory, the mirror name changes (it encodes the full path). That is expected and handled automatically — session history is preserved, only the mirror folder name differs.
• With --move, if the destination path already exists the script aborts rather than overwriting. Remove/rename the conflict and retry.
• Cross-drive moves require the workspace to be closed first. A same-drive rename often works while the workspace is open, but a move's delete step is blocked by both the file lock and (in sandboxed shells) the safe-delete recycle bin — skip step 1 and you'll get a duplicate.
• If a move produced a duplicate (source + destination both present), do NOT delete blindly. Verify with diff -r and re-run the command; the script recovers by dropping the source. Only bypass the sandbox for the final delete when the destination is a confirmed identical copy.

Cross-drive moves: lock, sandbox, and recovery

A move to a different drive/parent is copy + delete. Two environment facts make the delete step fail if you skip step 1:

• File lock: a workspace open in WorkBuddy holds the folder, so the delete reports Device or resource busy.
• Sandbox safe-delete: in some sandboxed shells, every delete is redirected to a recycle bin that is unavailable, so the delete fails closed. The copy still succeeds → you end up with a duplicate (source + destination both present) and no references changed.

The --move script is built to survive this:
- It copies, then verifies the copy (same file set + sizes) BEFORE deleting the source. A failed verification removes the partial copy instead of the source.
- If the destination already exists and is an identical copy of the source (a leftover from an interrupted move), it skips the copy and just drops the source duplicate.
- If the source delete fails, it aborts before editing any references and tells you a duplicate exists.

Recovering from a leftover duplicate

If a move left both copies behind:
1. Confirm they match: diff -r "<OLD_PATH>" "<NEW_PATH>" (expect no output).
2. Re-run the exact same command: python rename_workspace.py "<OLD_PATH>" "<NEW_PATH>" --move. The script detects the identical copy and deletes the source; then it syncs the mirror + sessions.
3. If the source delete still fails:
- Make sure the workspace is closed in WorkBuddy (releases the lock), then retry.
- If a sandboxed shell blocks the delete, re-run the command with the sandbox disabled — the destination is a verified identical copy, so deleting the source is safe (it is the backup).

This is exactly why --move changes the folder first and only then touches sessions.json/mirror: a failure mid-move never leaves a half-synced state.