---
title: Maintenance and Recovery
description: Label synchronization, canonical workflow state repair, repository detach and purge, cleanup, diagnostics, and safe recovery checks.
relatedCommands:
  - alpaca labels sync --help
  - alpaca state patch --help
  - alpaca state restore --help
  - alpaca detach --help
  - alpaca cleanup --help
  - alpaca doctor --help
relatedDocs:
  - workflow-state
  - setup
  - service-runtime
  - config
---

# Maintenance and Recovery

Use this guide when repairing AlpacaLoop-managed state, synchronizing labels, detaching a repository, cleaning local state, or collecting diagnostics before changing queue state.

## When to Use

- Use `alpaca doctor` before making manual repairs. It reports config, worker auth, cooldown, label, repo registration, and workflow template problems.
- Use `alpaca labels sync` when configured managed labels may be missing in the ticket tracker.
- Use `alpaca state patch` when canonical workflow state comments are missing required fields or need a supported patch.
- Use `alpaca state restore` only from a JSONL backup created by `state patch` or `state restore`.
- Use `alpaca detach` when a repo should be removed from service management.
- Use `alpaca cleanup` for machine-local AlpacaLoop state or eligible workspaces.

## Key Commands

```bash
alpaca doctor -h
alpaca labels sync -h
alpaca state patch -h
alpaca state restore -h
alpaca detach -h
alpaca cleanup -h
```

## Core Behavior

`alpaca labels sync` creates any missing configured managed labels in the tracker. It does not rename old labels on existing issues and does not migrate issue state.

`alpaca state patch --dry-run --state open` checks whether open issues' canonical workflow state comments can migrate to the current schema without updating tracker comments. `--state open` is the default; use `--issue <id[,id...]>` for targeted checks and `--state <open|closed|all>` for list-wide checks. Non-dry-run patch asks for confirmation in an interactive terminal and writes a JSONL backup before updating tracker comments. It only patches the latest canonical workflow state comment on each issue.

During service preflight, future workflow state versions still block the whole repository until AlpacaLoop is updated. Issue-local patch failures are isolated, moved to the Needs Human workflow state, and excluded from worker/config-scan scheduling so other ready issues can continue. Closed follow-up sources with invalid canonical workflow state are skipped during closed follow-up scanning so other sources can continue; repair them with a targeted `alpaca state patch --issue <id>` or a closed-state dry run before applying a broader repair.

`alpaca state restore --backup-file <path> --dry-run` previews restore operations from a backup. Non-dry-run restore asks for confirmation and writes a `.restore.jsonl` backup before changing comments. `--force` ignores current body hash mismatches but still skips when a newer canonical workflow state comment exists.

`alpaca detach` unregisters a repository from service management. With `--purge`, it can remove managed repository files, repo-local `.alpaca` files, and the project workspace root after confirmation. With `--force`, modified managed files can be deleted.

`alpaca cleanup --workspaces` cleans eligible worker workspaces. Without `--workspaces`, cleanup removes machine-local AlpacaLoop state after confirmation in an interactive terminal.

## Watch Outs

- Prefer dry-run modes before changing tracker comments or broad local state.
- Before publishing workflow state schema or patch changes, run the relevant state patch tests and `alpaca state patch --dry-run --state open` against affected repositories.
- Do not edit canonical workflow state comments manually unless the supported state commands cannot represent the recovery.
- If queue labels and canonical workflow state disagree, inspect the issue with `alpaca issue show` before adding or removing labels.

## Related Docs

- `alpaca docs show workflow-state`
- `alpaca docs show setup`
- `alpaca docs show service-runtime`
- `alpaca docs show config`
