Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,12 +200,13 @@ requiring a restart. A real switch to a different account still requires Codex
to be stopped.

Recent Codex desktop releases moved canonical thread-to-project membership into
the App Server state database while retaining a legacy desktop-side assignment
map. If that upstream migration is incomplete, `project status` reports it and
`project repair` reconciles the legacy IDs through the official App Server
protocol. A normal `use` automatically performs this repair when Codex is
closed. The operation is idempotent and creates a timestamped backup of
`.codex-global-state.json` before marking the migration complete.
the App Server state database while the desktop still consumes a local project
catalog during startup. `codex-switch` keeps a credential-free shared catalog
under `CODEX_SWITCH_HOME`. A normal `use` captures that catalog when it is
healthy and restores it when an account change removes the desktop projection;
it then reconciles any pending legacy IDs through the official App Server
protocol. No separate `project repair` is required in the normal closed-app
switch flow. Every desktop-state change is backed up before replacement.

## What a switch changes

Expand All @@ -214,10 +215,11 @@ Normal account switches modify only:
- `$CODEX_HOME/auth.json`
- `codex-switch`'s own state and encrypted vault

When Codex reports an incomplete local-project migration, a switch performed
while Codex is closed may additionally restore `threads.project_id` through the
official App Server and update the backed-up desktop migration checkpoint. It
does not copy projects or sessions into per-account homes.
When Codex reports an incomplete or missing local-project projection, a switch
performed while Codex is closed may additionally restore the credential-free
desktop project catalog, restore `threads.project_id` through the official App
Server, and update the backed-up desktop migration checkpoint. It does not copy
projects or sessions into per-account homes.

An account-usage query may persist an officially refreshed credential generation
back to the encrypted vault. If the queried profile is active, the same
Expand Down
9 changes: 5 additions & 4 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,11 @@
refresh generations, and coordinates with switching through the same lock.
- `usagecache` stores credential-free successful snapshots separately from the
encrypted vault.
- `projectstate` detects the desktop's legacy-to-App-Server project migration,
restores canonical thread assignments through the official experimental App
Server API, and advances the desktop checkpoint only after every assignment
is confirmed.
- `projectstate` maintains a credential-free shared local-project catalog,
restores a missing desktop projection after account changes, reconciles
canonical thread assignments through the official experimental App Server
API, and advances the desktop checkpoint only after every assignment is
confirmed.
- `atomicfile` publishes complete files and refuses symlink destinations.
- `doctor` reports only redacted, non-secret local facts.

Expand Down
6 changes: 4 additions & 2 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,10 @@ Usage querying initializes `codex app-server` and calls:
- `account/rateLimits/read`
- `account/usage/read`

Project migration repair was added for Codex CLI `0.167.0`. It negotiates the
App Server's `experimentalApi` capability and uses `project/list` plus
Project migration repair was added for Codex CLI `0.167.0`. It preserves the
desktop's credential-free project projection independently of the active
account. When canonical assignments also need repair, it negotiates the App
Server's `experimentalApi` capability and uses `project/list` plus
`thread/metadata/update` with `projectId`. Older clients are unaffected unless
their desktop state explicitly reports a pending App Server project migration;
in that case the command fails with an update hint instead of editing SQLite
Expand Down
24 changes: 14 additions & 10 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,27 +55,31 @@ ordinary switching.

## Projects are empty or change after switching accounts

Recent Codex releases store projects and thread-to-project membership
separately. A desktop migration can create the projects successfully while
leaving every canonical thread `projectId` empty. Inspect the redacted status:
Recent Codex releases store the desktop project catalog and canonical
thread-to-project membership separately. An account change can leave the
canonical projects intact while removing the desktop projection, or a migration
can leave every canonical thread `projectId` empty. Inspect the redacted status:

```bash
codex-switch project status
codex-switch doctor
```

If repair is needed, fully quit Codex/ChatGPT and run:
Normal `codex-switch account use <alias>` repairs both states automatically when
Codex is closed. If a prior manual login already caused drift, fully quit
Codex/ChatGPT and run once:

```bash
codex-switch project repair
```

The repair uses Codex App Server rather than editing its SQLite database. It
keeps the desktop's legacy project map, verifies the new project IDs, applies
each assignment idempotently, and backs up `.codex-global-state.json` before
advancing the migration checkpoint. Use `--force` to reapply all retained
assignments after a later Codex regression. Avoid `--allow-running` unless the
desktop cannot be stopped; its in-memory state may overwrite the repair.
The repair restores the desktop projection from the shared catalog (or the most
recent codex-switch backup), then uses Codex App Server rather than editing its
SQLite database. It verifies the new project IDs, applies each assignment
idempotently, and backs up `.codex-global-state.json` before every replacement.
Use `--force` to reapply all retained assignments after a later Codex regression.
Avoid `--allow-running` unless the desktop cannot be stopped; its in-memory
state may overwrite the repair.

## Active account is unmanaged

Expand Down
40 changes: 31 additions & 9 deletions internal/app/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -637,13 +637,17 @@ func newUseCommand(options *Options) *cobra.Command {
inspection, inspectErr := runtime.projectService(options.Version).Inspect()
if inspectErr != nil {
projectWarning = "Project migration status could not be inspected: " + inspectErr.Error()
} else if inspection.NeedsRepair {
} else {
running, detectErr := process.DetectCodex()
switch {
case detectErr != nil:
projectWarning = "Project assignment migration is pending; run 'codex-switch project repair' after closing Codex."
if inspection.NeedsRepair {
projectWarning = "Shared project state needs repair; run 'codex-switch project repair' after closing Codex."
}
case allowRunning || len(running) > 0:
projectWarning = "Project assignment migration is pending; run 'codex-switch project repair' after closing Codex."
if inspection.NeedsRepair {
projectWarning = "Shared project state needs repair; run 'codex-switch project repair' after closing Codex."
}
default:
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
repaired, repairErr := runtime.projectService(options.Version).Repair(ctx, false, false)
Expand All @@ -667,7 +671,12 @@ func newUseCommand(options *Options) *cobra.Command {
}
}
if projectRepair != nil && projectRepair.Repaired {
message += fmt.Sprintf(" Repaired %d local project assignment(s).", projectRepair.AssignmentsRepaired)
if projectRepair.ProjectionRestored {
message += fmt.Sprintf(" Restored %d shared local project(s).", projectRepair.Projects)
}
if projectRepair.AssignmentsRepaired > 0 {
message += fmt.Sprintf(" Repaired %d local project assignment(s).", projectRepair.AssignmentsRepaired)
}
}
if projectWarning != "" {
message += "\nWarning: " + projectWarning
Expand Down Expand Up @@ -727,9 +736,11 @@ func newProjectRepairCommand(options *Options) *cobra.Command {
if err != nil {
return err
}
message := "Project assignments are already consistent."
message := "Shared project state is already consistent."
if result.Repaired {
message = fmt.Sprintf("Repaired %d local project assignment(s). Backup: %s", result.AssignmentsRepaired, result.Backup)
message = fmt.Sprintf("Restored %d shared local project(s) and repaired %d assignment(s). Backup: %s", result.Projects, result.AssignmentsRepaired, result.Backup)
} else if result.CatalogUpdated {
message = fmt.Sprintf("Saved %d shared local project(s) for future account switches.", result.Projects)
}
return options.render(result, message)
},
Expand All @@ -749,8 +760,14 @@ func formatProjectInspection(inspection projectstate.Inspection) string {
} else if !inspection.ThreadAssignmentsMigrated {
status = "not applicable"
}
return fmt.Sprintf("Projects: %d\nAssignments: %d (%d resolvable, %d pending)\nMigration: %s",
inspection.Projects, inspection.LegacyAssignments, inspection.ResolvableAssignments, inspection.PendingAssignments, status)
projection := "present"
if inspection.ProjectionMissing {
projection = "missing (recoverable)"
}
return fmt.Sprintf("Projects: %d shared (%d desktop, %d saved)\nAssignments: %d shared (%d desktop, %d saved; %d resolvable, %d pending)\nDesktop projection: %s\nMigration: %s",
inspection.Projects, inspection.DesktopProjects, inspection.CatalogProjects,
inspection.LegacyAssignments, inspection.DesktopAssignments, inspection.CatalogAssignments,
inspection.ResolvableAssignments, inspection.PendingAssignments, projection, status)
}

func newDeactivateCommand(options *Options) *cobra.Command {
Expand Down Expand Up @@ -1138,8 +1155,12 @@ func (options *Options) loadProjectRuntime() (runtimeState, error) {
if err != nil {
return runtimeState{}, err
}
paths, err := appconfig.ResolvePaths(options.AppHome)
if err != nil {
return runtimeState{}, err
}
bin, binErr := codexlogin.FindBinary(options.CodexBin)
return runtimeState{home: home, bin: bin, binErr: binErr}, nil
return runtimeState{home: home, paths: paths, bin: bin, binErr: binErr}, nil
}

func (runtime runtimeState) switcher() switcher.Service {
Expand All @@ -1152,6 +1173,7 @@ func (runtime runtimeState) projectService(version string) projectstate.Service
Binary: runtime.bin,
BinaryError: runtime.binErr,
ClientVersion: version,
CatalogPath: runtime.paths.ProjectCatalog,
}
}

Expand Down
22 changes: 12 additions & 10 deletions internal/config/paths.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@ import (
)

type Paths struct {
Root string
Vault string
State string
Journal string
UsageCache string
Root string
Vault string
State string
Journal string
UsageCache string
ProjectCatalog string
}

func ResolvePaths(override string) (Paths, error) {
Expand All @@ -31,11 +32,12 @@ func ResolvePaths(override string) (Paths, error) {
return Paths{}, fmt.Errorf("resolve codex-switch home: %w", err)
}
return Paths{
Root: abs,
Vault: filepath.Join(abs, "vault.v1.enc"),
State: filepath.Join(abs, "state.json"),
Journal: filepath.Join(abs, "switch.journal.json"),
UsageCache: filepath.Join(abs, "usage-cache.v1.json"),
Root: abs,
Vault: filepath.Join(abs, "vault.v1.enc"),
State: filepath.Join(abs, "state.json"),
Journal: filepath.Join(abs, "switch.journal.json"),
UsageCache: filepath.Join(abs, "usage-cache.v1.json"),
ProjectCatalog: filepath.Join(abs, "project-catalog.v1.json"),
}, nil
}

Expand Down
Loading
Loading