Supporting multi-repo workspaces (folder of N sibling git repos)

[harshitsinghbhandari]

Right now AO assumes one project = one git repo. Sessions get isolated working copies via git worktree add, branches map 1:1 to sessions, and the SCM observer watches one remote per project.

That misses a common shape: a folder containing several sibling git repos.

project-abc/            ← plain folder, not itself a git repo
├── project-abc-cli/    ← git repo
├── project-abc-api/    ← git repo
└── project-abc-pf/     ← git repo (or we offer to init)

We want AO to support this: one logical project, N sibling git repos underneath, where the parent folder may or may not be a git repo.

Scope is git-only. If a sub-folder isn't a git repo, AO will offer to git init it or refuse to register it. No COW / overlay / non-git fallback.

Registration UX

When the user runs ao project add <path>:

• Path is itself a git repo → existing single-repo flow, unchanged.
• Path is not a git repo, has N git sub-folders → AO prompts: "There are N sub-folders that are git repos. Register the whole folder as one project, or pick one of these?"
• Path has some non-git sub-folders → offer git init for those, or skip them.
• Path has no git sub-folders at all → refuse, suggest git init first.

Open questions

This thread is for scoping. No proposed design — just the questions that need answers before anyone starts designing.

Workspace model

• Is a "workspace project" a new project kind, or just a project whose canonical path holds N sub-repos?
• Where does workspace metadata live? .ao/ inside the parent folder? AO's SQLite store only? Both?

Isolation unit

• Per session: isolate the whole workspace (worktree every sub-repo together) or per sub-repo (sessions target one sub-repo at a time)?
• If per-repo: how does a session that needs to touch multiple sub-repos coordinate — multiple sessions, or --targets cli,api?

Schema changes

• sessions.project_id today implies one branch on one repo. With workspaces, do we need session × sub-repo rows? A new session_target join?
• One branch per (session × sub-repo), or one shared branch name across all sub-repos a session touches?

SCM observer

• Today: one remote per project. With workspaces: N remotes. How does an observation (PR, review, run) get attributed back to the right (session, sub-repo) pair?

Activity attribution / hooks

• When a session edits both cli/ and api/, which sub-repo "owns" the resulting activity events? Both? The first one touched?

Cleanup / reaper

• Multi-repo cleanup = N worktree removes. If one fails partway, what's the recovery path?

Registration UX details

• For the "N git sub-folders detected" prompt, interactive only, or does ao project add --as-workspace / --pick-subrepo <name> bypass it for scripts?
• If AO git inits a sub-folder, does it mark anything in .git/config as AO-managed?

Scope for this iteration

• Smallest first cut that's still useful? E.g.: (1) detection + interactive registration, (2) per-sub-repo worktrees on spawn, (3) SCM observer adjustments, (4) session-spanning multi-repo edits.
• Which of those can be deferred?

[harshitsinghbhandari]

Closing several of the open questions, leaving two open.

Decisions

1. Workspace model: new backend project kind. Registration UX largely unchanged.
2. Metadata location: AO DB only. No .ao/ in the parent folder.
3. Isolation unit: sessions can target one or more sub-repos. The worktree contains the parent root files + the selected sub-repo folders only. Example: workspace has cli, app, pf, api; --targets api,pf creates a worktree with root files + api/ + pf/.
4. CLI flag: --targets cli,api.
5. SCM observer attribution: PR ↔ session is 1:1, so observations flow to the linked session — no special workspace handling needed.
6. Activity attribution: the project owns activity. Sub-repos are not activity sources.
7. Cleanup: retry on failure, same as current worktree handling.
8. Registration entry point: UI is primary. CLI gets ao project add --as-workspace.

Still open

Root files in a non-git parent

The worktree includes the parent's root-level files (outside any sub-repo). The parent isn't a git repo, so those files have no version control. When two concurrent sessions both edit package.json at the parent root — what happens?

• (i) Copy into each worktree, last-write-wins back to canonical — simplest, but silent overwrites between sessions.
• (ii) Read-only at the session worktree — sessions can read root files but not modify them; edits go through a separate flow.
• (iii) Require git init on the parent if any session needs to write at root — punts to git semantics.

Schema for "session targets multiple sub-repos"

A. session_target join table (session × sub-repo, N:N)

• Pros: clean N:N. Any (session, sub-repo) lookup is straightforward. Easy to scope "sessions touching sub-repo X".
• Cons: extra table + joins at most read sites. Touches many call sites that assume session.project_id is the whole story.

B. JSON column on sessions (target_subrepos JSON)

• Pros: smallest schema delta. No new table, no joins.
• Cons: "find sessions touching sub-repo X" requires a scan or a generated/virtual column. Schema-in-blob.

C. One session per sub-repo + a session_group parent

• Pros: keeps session ↔ one repo invariant. Zero changes to session manager, worktree manager, reaper.
• Cons: changes the user model — a multi-target spawn becomes N sessions under a group. Confusing UX.

D. Single repo with branch-name convention

• Pros: zero schema change.
• Cons: only works if we keep "session = one branch on one repo", which the rest of this design rejects. Effectively no workspace feature.