Skip to content

fix(cli): runtime commands don't resolve externalized state paths #949

Closed

Description

@diberry

Problem

After running \squad externalize, several CLI commands still read from the local .squad/\ directory instead of resolving to the external state directory. This means externalized state (e.g., \ eam.md,
outing.md, \�gents/, \plugins/) becomes invisible to those commands.

Evidence

  • \detectSquadDir()\ only returns local .squad/\ or .ai-team/\ — it never follows \stateLocation: external\ + \projectKey\ to the external dir (\detect-squad-dir.ts:49-75)

  • esolveSquadPaths()\ ignores \stateLocation\ entirely (
    esolution.ts:258-292)
  • The 'external'\ backend in \state-backend.ts:262-268\ is still a stub that maps to \WorktreeBackend\
  • \loadDirConfig()\ parses \stateLocation/\projectKey\ from \config.json\ (
    esolution.ts:210-233), but nothing uses them to redirect to
    esolveExternalStateDir()\

Affected commands (non-exhaustive)

  • \squad start\ / shell — reads \ eam.md\ directly (\shell/index.ts:191-214, \shell/lifecycle.ts:67-85)
  • \squad start\ / coordinator — reads \ eam.md\ +
    outing.md\ (\shell/coordinator.ts:237-259)
  • \squad loop\ — requires local \ eam.md\ (\loop.ts:269-275)
  • \squad watch\ — requires local \ eam.md\ +
    outing.md\ (\watch/index.ts:651-657)
  • \squad plugin marketplace\ — reads/writes .squad/plugins/\ (\plugin.ts:39-60)
  • \squad doctor\ — reads \ eam.md,
    outing.md, \�gents/\ (\doctor.ts:158-190)
  • \squad schedule\ — reads/writes \schedule.json\ + .schedule-state.json\ (\schedule.ts:26-33)

Proposed fix

Add an \�ffectiveSquadDir()\ resolver that:

  1. Reads \config.json\ from the local .squad/\
  2. If \stateLocation === 'external', resolves the external path via
    esolveExternalStateDir(projectKey)\
  3. Returns the external path for state reads, local path for KEEP_LOCAL files

Then update all affected commands to use \�ffectiveSquadDir()\ instead of hardcoding local .squad/\ paths.

Additional issue: stale state resurrection


unExternalize\ copies into the external dir but never cleans pre-existing contents there.
unInternalize\ copies back but never removes stale external files afterward. Deleted/renamed files can persist in the external dir and come back on a later internalize. Consider mirror-sync or cleanup semantics.

Related

Activity

  1. diberry commented on Apr 10, 2026

    @diberry
    ContributorAuthor

    🔒 On hold — investigation revealed this requires an \�ffectiveSquadDir()\ abstraction threaded through 12+ CLI commands (loop, watch, doctor, plugin, build, import/export, migrate, upstream, copilot, shell/start), plus the external state backend stub. Too large for a minimal fix; reclassifying as high-touch architecture work.

  2. added a commit that references this issue on Apr 10, 2026
    b02f8e6
  3. added a commit that references this issue on Jun 5, 2026
    0d124b9
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions