Clean reinstall of AgentKit

Binary and kit channels are separate. Use --channel stable explicitly when you want the stable path.

1. 1

   Stop active writers

   Close Codex, Claude Code, and any running AgentKit lifecycle command before touching temp files or uninstalling kits.

2. 2

   Confirm ak CLI + stable channel

   type -a ak, ak --version, ak self-update --check --channel stable. Upgrade the CLI if needed — but do not delete ~/.agentkit yet.

3. 3

   Work around ..* filename (2.7.0)

   If you hit the snapshot outside-scope error: close Codex, list then move (do not delete) matching temp files into quarantine.

4. 4

   Audit + uninstall owned kits

   Only the scopes/modes you actually installed: global native, user plugin, project native, project plugin. Preview (--dry-run), then --yes.

5. 5

   Verify uninstall evidence

   ak audit --json and ak backups list --json. Retained recovery snapshots are expected — keep them until reinstall verification passes.

6. 6

   Reset AgentKit state (optional)

   Only after ownership-aware kit uninstall: ak logout, then mv ~/.agentkit to a recovery name — do not delete it yet.

7. 7

   Install stable CLI

   Stable installer, hash -r, type -a ak, ak --version, ak doctor --json. Resolve duplicate binaries on PATH.

8. 8

   Login + reinstall kits

   ak login, ak licenses, ak kit init … --channel stable --yes, then audit/doctor before restarting Codex.

Close Codex, Claude Code, and any running AgentKit lifecycle command before touching temp files under ~/.codex or running uninstall. Do not overlap lifecycle commands or kill an active mutation mid-flight.

First list files matching the narrow pattern (maxdepth 1, regular files only):

find "$HOME/.codex" -maxdepth 1 -type f \
  -name '..codex-global-state.json.bak.tmp-*' -print

After Codex is closed, move matching files to a recoverable quarantine outside the ~/.codex tree (still under ~/.agentkit for easy discovery):

quarantine="$HOME/.agentkit/manual-quarantine/codex-temp-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$quarantine"

find "$HOME/.codex" -maxdepth 1 -type f \
  -name '..codex-global-state.json.bak.tmp-*' \
  -exec mv -n {} "$quarantine"/ \;

After quarantine, rerun dry-run then confirmed uninstall (correct scope — see Phase 4).

ak audit --json
ak backups list --json

Retained recovery snapshots are expected evidence — do not delete them until the lifecycle result and reinstall are verified. Only describe uninstall as completed when the confirmed (--yes) command succeeded.

# Only after ownership-aware kit uninstall has finished
ak logout

stamp=$(date +%Y%m%d-%H%M%S)
mv "$HOME/.agentkit" "$HOME/.agentkit.pre-stable-$stamp"

# Keep the renamed directory until stable install + audit/doctor pass
# Do not delete yet — it holds backups, quarantine, registry, and auth state

• Resets AgentKit state while retaining a recovery copy (mv, not rm).
• Also moves backups and the temporary-file quarantine from Phase 3 (under ~/.agentkit).
• Do not delete the renamed directory until the new stable installation and kit audit pass.

ak login
ak licenses

# Example: Engineer Kit on global Codex, stable channel
ak kit init engineer \
  --target codex \
  --global \
  --channel stable \
  --yes

ak audit engineer --strict --json
ak doctor --adapter codex --json

# Restart Codex only after the checks above complete

Keep the quarantine and ~/.agentkit.pre-stable-* until ak audit / ak doctor pass. Only then consider removing recovery copies.

# PowerShell — close Codex first. Only temp files matching the narrow pattern.
$codex = Join-Path $env:USERPROFILE '.codex'
$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$quarantine = Join-Path $env:USERPROFILE ".agentkit\manual-quarantine\codex-temp-$stamp"
New-Item -ItemType Directory -Force -Path $quarantine | Out-Null

Get-ChildItem -LiteralPath $codex -File -Force |
  Where-Object { $_.Name -like '..codex-global-state.json.bak.tmp-*' } |
  ForEach-Object {
    Move-Item -LiteralPath $_.FullName -Destination $quarantine -ErrorAction Stop
  }

Get-ChildItem -LiteralPath $quarantine -Force

# PowerShell — only after ownership-aware kit uninstall
ak logout
$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$homeAk = Join-Path $env:USERPROFILE '.agentkit'
$dest = Join-Path $env:USERPROFILE ".agentkit.pre-stable-$stamp"
Move-Item -LiteralPath $homeAk -Destination $dest

# PowerShell
irm https://agentkit.best/install.ps1 | iex
# Open a new terminal, then:
Get-Command ak -All
ak --version
ak doctor --json

ak kit uninstall / audit / kit init flags match Unix. Prefer absolute project paths for --project-dir. Use %USERPROFILE% when referring to home paths.