RCA: orchestrator spawn workspace conflict on fresh install (#1922)

[Copilot]

Root-cause analysis only — no code changes. The reporter sees AO found an older orchestrator workspace for "<project>_<hash>" but could not safely reuse it automatically on a completely fresh ao start, even though no prior worktree, branch, or session metadata exists.

Root cause

First-run autoCreateConfig produces two divergent project identities for the same repo:

• Local yaml (packages/cli/src/commands/start.ts:574-592) is written in the legacy wrapped projects: format, keyed by basename(cwd) (e.g. feat-reviewer-agent-flow).
• Global registry (registerProjectInGlobalConfig → generateExternalId, packages/core/src/global-config.ts:773-790, 49-54) rebrands the same project to <basename>_<sha10> (e.g. feat-reviewer-agent-flow_24136efca8).

autoCreateConfig then returns loadConfig(outputPath) against the wrapped local yaml. applyWrappedLocalStorageKeys (packages/core/src/config.ts:84-121) does not rename the key, so the CLI's subsequent ensureOrchestrator runs with projectId = '<basename>' and creates the worktree at ~/.agent-orchestrator/projects/<basename>/worktrees/<sessionPrefix>-orchestrator on branch orchestrator/<sessionPrefix>-orchestrator.

The dashboard loads from the canonical global config and only ever sees <basename>_<sha10>. The wrapped local yaml also makes the project show up as degraded (loadLocalProjectConfigDetailed returns old-format). "Fix Config" calls repairWrappedLocalProjectConfig, which rewrites the yaml flat — but does not move the worktree or session metadata.

When the user then clicks "Spawn Orchestrator":

• findManagedWorkspace (packages/plugins/workspace-worktree/src/index.ts:414-451) builds allowedPaths rooted at …/projects/<basename>_<sha10>/worktrees/….
• git worktree list --porcelain finds the existing worktree on branch orchestrator/<sessionPrefix>-orchestrator, but at the basename path.
• That path isn't in allowedPaths → throws "outside AO-managed worktree directories".
• classifySpawnError (packages/web/src/app/api/orchestrators/route.ts:15-32) rewrites the message and interpolates the hashed id, producing the reported text.

The conflict is structural (both ids derive deterministically from the repo path/origin), not a race. findManagedWorkspace is behaving correctly — the bug is upstream, in the auto-create flow producing two ids.

Why the issue's hypotheses were close but not quite right

Hypothesis	Verdict
Repair creates state that the spawn sees as stale	No — repair only edits yaml. The diverged state was created in step 8 by the CLI's own ensureOrchestrator during ao start.
Spawn creates half-state and trips on its own retry	No — the conflicting worktree predates the spawn click.
Repair → spawn path creates workspace state mid-flight	Indirect — repair only unblocks the Spawn button, exposing the latent divergence.

Suggested fix directions (not implemented; awaiting direction)

1. autoCreateConfig writes a flat local yaml (matching the post-repair format). Eliminates the degraded state and the basename key from config.projects. Smallest surgical fix.
2. autoCreateConfig reloads via loadConfig(getGlobalConfigPath()) after registerProjectInGlobalConfig so the rest of ao start uses the hashed id.
3. Teach applyWrappedLocalStorageKeys to rename the local key to the registered hashed id when the global registry already knows the project.
4. Have repairWrappedLocalProjectConfig migrate any worktrees/sessions under the basename project dir to the hashed project dir (only needed to recover already-corrupted installs).

(1) addresses the root cause. (1)+(4) together also recover users already affected.

Note on delivery

The instructions asked me to post the RCA as a comment on #1922. Both gh issue comment and the GitHub REST API returned 403 from this sandbox, and the available MCP tools only expose reply_to_comment for PR review threads. The full analysis lives in commit c3f541e's PR body and can be pasted to the issue by a maintainer.