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.

[harshitsinghbhandari]

Workspace Worktree Provisioning — Options

Context

AO assumes one project = one git repo. We want to support workspaces: a folder containing N sibling git repos, where the parent folder may or may not itself be a git repo. The hard question is how a session's worktree gets provisioned when the user runs ao spawn --targets cli,api.

This doc lists every viable option for the provisioning mechanism with full pros/cons. No recommendation — that's for the maintainer to call.

Constraints baked in:

• Git-only scope. Non-git sub-folders get git init-ed or refused at registration time.
• Existing single-repo flow (path is itself a git repo) is unchanged. Options below only apply when path is a plain folder containing N git sub-repos.
• Empirical findings from the worktree stress-test (research.md): git worktree add on a parent-with-nested-repos produces empty placeholder dirs for the children; populated parent worktrees require .gitmodules + submodule update --init --recursive.

Summary table

Option	Provisioning mechanism	Disk cost	Reuses git internals	New surface area in AO
1	Plain parent + per-child git worktree add	O(1) per child (shared object DB)	Yes — native worktrees	Composition layer + root-file handling
2	git init parent + submodules + parent-level git worktree	O(1) per child + parent metadata cost	Yes — worktrees + submodules	.gitmodules lifecycle, submodule UX
3	Plain parent + per-child cp -r	O(N) full copy per session	No	Push-back plumbing, cleanup safety
4	Plain parent + per-child CoW (clonefile/reflink/overlayfs)	O(1) on supported FS	No	FS detection, fallback, push-back plumbing
5	Session group: one session per sub-repo, no composite worktree	O(1) per child (native worktrees)	Yes	Session-group abstraction; no composite needed
6	Plain parent + git clone --local per child	O(1) per child (hardlinked objects)	Partial — clone, not worktree	Branch-flow plumbing, remote-add per session

Options

Option 1: Plain parent + per-child git worktree add (compose in AO)

Shape. Parent folder is never git init-ed. For each targeted sub-repo, AO calls git -C <canonical>/<sub-repo> worktree add <session-dir>/<sub-repo> <branch>. AO tracks the composite session worktree in its DB as N native git worktrees + (optionally) root files copied or symlinked into <session-dir>/.

Pros.

• Native git worktree machinery: shared object DB, cheap provisioning, no clone cost.
• No submodule UX, no .gitmodules to maintain.
• Branch/push/PR flow is unchanged per sub-repo. Each PR is one sub-repo, one branch.
• Parent folder structure on disk is untouched — user-friendly, non-invasive.
• Cleanup = git worktree remove per child. Failure recovery uses existing AO worktree retry logic.
• Each child's .git/worktrees/ ledger tracks AO session worktrees → discoverable from the git side.

Cons.

• AO has to track the composition externally (one DB row binds session → N child worktrees). Listing "all worktrees for a session" requires AO DB, not just git worktree list.
• Root file handling is a separate problem (copy / symlink / read-only / none) and not solved by git.
• Multi-repo atomic operations (cross-repo commit/push) require AO orchestration — git won't do it for us.
• If a user manually git worktree removes one of the per-child worktrees, the composite is partially broken. AO needs detection + repair.
• The agent's working directory inside the session is a non-git folder containing N git sub-folders — same shape as the parent. Tools that assume cwd is a git repo need to be sub-repo-aware.

Open questions.

• Root files: copy, symlink, or skip?
• Agent cwd: parent of the session worktree, or cd into a specific sub-repo first?

Option 2: git init parent + submodules + parent-level git worktree

Shape. AO runs git init on the parent folder, writes .gitmodules, commits gitlinks for each sub-repo. Per-session: git -C <parent> worktree add <session-dir> + git -C <session-dir> submodule update --init --recursive.

Pros.

• One git repo to reason about at the top level: parent worktree, recursive children come for free.
• Composite worktree is a single git artifact — atomic in git's eyes.
• Sub-repo pinning is explicit (gitlink SHA). Workspace state is reproducible from a single parent commit.
• If the user pushes the parent, the submodule SHAs travel together.

Cons.

• Forces submodule UX on the user. Most teams actively avoid submodules.
• Per the research: local-path submodule URLs require protocol.file.allow=always. Awkward for any local-only sub-repo.
• .gitmodules lifecycle is heavyweight: every sub-repo branch advance requires bumping the parent's gitlink SHA, otherwise worktrees still point at the old child SHA.
• Forcing git init on the parent is invasive — touches the user's folder. Reversing it (de-registering a workspace) leaves a .git/ behind.
• For sub-repos without remotes, submodule URLs can only be local paths → per-machine config or strict relative paths.
• New users will hit detached HEAD inside submodules, "submodules out of sync" warnings, the whole submodule UX cliff.
• "Session = branch" semantics get muddled: parent branch vs sub-repo branches — what counts?
• PR flow: do you open one parent PR with submodule bumps, or per-sub-repo PRs? Both have downsides.

Open questions.

• Who owns .gitmodules: AO or the user? Auto-bump on sub-repo branch advance?
• How are PRs structured?

Option 3: Plain parent + per-child plain copies (cp -r)

Shape. AO copies each targeted sub-repo into the session dir with cp -r. Git commands still work because each copy is a full self-contained repo (its own .git/).

Pros.

• Simplest mental model: a session dir is just a copy of selected sub-repos.
• Works on any filesystem — no platform special-casing.
• No git worktree linked-state edge cases at all.
• Sessions can checkout any branch independently without conflicting with a worktrees ledger.
• Root files are just copied alongside — no special handling needed.
• Independent .git/ per session means agent-side git operations have no cross-session interference.

Cons.

• Full disk copy per session, including the entire .git/. Linear in repo size.
• Slow provisioning on multi-GB repos (cold-cache cp -r can be minutes).
• Each session has its own object DB → diverged from canonical. Pushing back requires git remote add + push, or a manual diff/apply step.
• Cleanup is rm -rf — no safety net if a path is wrong. (Real risk with composite paths.)
• Two sessions touching the same sub-repo are fully independent copies — no object reuse, no shared cache.
• Branches created in a session aren't visible from canonical until pushed back.

Open questions.

• Push-back UX: configure a remote pointing at canonical and git push? Or diff-and-apply?
• How are branch reservations coordinated across sessions if each has its own ref namespace?

Option 4: Plain parent + per-child CoW (clonefile / reflink / overlayfs)

Shape. Same as Option 3, but use the OS's copy-on-write primitive. macOS APFS clonefile(), btrfs cp --reflink=auto, Linux overlayfs.

Pros.

• O(1) provisioning regardless of repo size on supported filesystems.
• Each session sees an independent copy in user-visible terms — no shared-state hazards.
• Same simple mental model as Option 3 with the disk cost erased.

Cons.

• Filesystem-dependent. macOS APFS = yes. Linux btrfs/ZFS = yes. ext4 = no. NTFS = no out of the box.
• Reproducibility hazard: behavior depends on the user's FS choice → CI and local diverge.
• Overlayfs on Linux requires root or rootless overlay setup → operational complexity.
• Same push-back problem as Option 3: each copy has its own object DB.
• Detecting FS support at runtime and falling back to plain copy adds code paths and confusing failure modes.
• External tools (du, backup, Dropbox, time machine) can break CoW semantics in surprising ways.

Open questions.

• Fallback strategy for non-CoW filesystems — Option 1 or Option 3?
• Do we accept "macOS-and-some-Linux-only" as a constraint?

Option 5: One AO session per sub-repo + session group

Shape. Drop the composite-worktree idea entirely. A "session group" is the multi-target abstraction. ao spawn --targets cli,api creates two sessions, each with its own native git worktree against one sub-repo, both belonging to one group. Cross-sub-repo coordination is via the group, not via a shared worktree.

Pros.

• Existing single-repo session machinery is reused unchanged: worktree provisioning, branches, PRs, reaper, SCM observer all stay as-is.
• session ↔ one repo invariant stays intact. Schema delta is small (one new session_group table).
• Per-sub-repo PRs fall out naturally; SCM observer's PR↔session 1:1 model is preserved without effort.
• Cleanup is per-session, identical to today.
• No root-file question to answer (no shared parent dir).

Cons.

• User model is confusing: one agent invocation produces N sessions.
• Cross-repo agent work is genuinely hard. Agent in cli session can't see api/ files. The "I want one agent that refactors across api+cli" use case is not delivered.
• "Atomic" cross-repo edits require coordinating two agents — typically via a higher-level orchestrator, not free.
• If multi-target is the primary use case, this is essentially a renaming of for repo in targets: ao spawn ....

Open questions.

• If we go this route, is --targets even useful, or do users just spawn N sessions explicitly?
• What does a "session group" actually own beyond a list of session IDs?

Option 6: Plain parent + git clone --local per child

Shape. Instead of git worktree add, AO does git clone --local <canonical>/<child> <session-dir>/<child> per targeted sub-repo. --local hardlinks the source's object DB, so it's cheap.

Pros.

• Cheap on disk (hardlinked object DB).
• Each session dir is a self-contained clone — no git worktree linked-state hazards.
• Sessions can freely checkout / create branches without touching the source's worktrees ledger.
• Push-back via git push origin <branch> once a remote is configured against canonical.

Cons.

• Each session has its own .git/HEAD, .git/refs, etc. — branches created in the session are NOT visible in the source until pushed/fetched.
• For sub-repos without remotes, "push back" means git push <canonical-path> and a remote-add per session — extra bookkeeping.
• --local hardlinks objects → GC on the source can corrupt the clones. AO must coordinate or disable GC.
• Two sessions on same sub-repo have independent ref namespaces → no shared branch state via the source.
• More moving parts than Option 1 (clone + remote-add + fetch refspecs).

Open questions.

• How do branches flow back into canonical — auto-push on session completion, or explicit user action?
• How do we prevent source-side GC from breaking session clones?

Cross-cutting concerns

These cut across all options and have to be decided independently of the provisioning mechanism.

Root files in a non-git parent

The parent folder may have files at the root (outside any sub-repo): package.json, pnpm-workspace.yaml, .env, Makefile, etc. The parent isn't a git repo, so those files have no version control. What does the session worktree do with them?

• (i) Copy into each worktree, last-write-wins back to canonical. Simplest. Silent overwrites between concurrent sessions.
• (ii) Read-only at the session worktree. Sessions can read but not write root files. Edits go through a separate flow.
• (iii) Require git init on the parent if any session needs to write at root. Pushes the problem into git's hands.

Applies to: Options 1, 3, 4, 6. (Option 2 makes the parent a git repo so root files are versioned. Option 5 doesn't share a parent dir at all.)

Schema for "session targets multiple sub-repos"

• A. session_target join table (session × sub-repo, N:N). Clean N:N. Extra table + joins.
• B. JSON column on sessions (target_subrepos JSON). Smallest schema delta. Lookups by sub-repo require scan or virtual column.
• C. One session per sub-repo + session_group parent. Keeps session ↔ one repo intact. Multi-target UX gets weirder.
• D. Single repo with branch-name convention. Zero schema change. Effectively means no workspace feature.

Option 5 implies schema C. Options 1, 3, 4, 6 work with A or B. Option 2 works with A, B, or D depending on whether sessions still target individual sub-repos or a single parent commit.

SCM observer attribution

Decided already: PR ↔ session is 1:1, observations flow to the linked session. No special workspace handling for the observer regardless of provisioning option.

Note: if Option 2 (parent submodules) is chosen and PRs are opened against the parent repo instead of sub-repos, the PR ↔ session model still works, but per-sub-repo activity gets harder to attribute. Per-sub-repo PRs in Option 2 are safer for observer fidelity.

Activity attribution

Decided already: the workspace project owns activity, not individual sub-repos. All options are compatible.

Cleanup / reaper

• Option 1: git worktree remove per child + AO retry. Existing model.
• Option 2: git worktree remove on the parent, submodule removal cascades.
• Option 3: rm -rf per child + safety guard rails needed.
• Option 4: same as Option 3.
• Option 5: existing per-session reaper, no change.
• Option 6: rm -rf per clone + GC coordination considerations.

Registration UX

Same across all options:

• Parent is a git repo → existing single-repo flow.
• Parent is a folder with N git sub-folders → prompt "register whole folder as one workspace, or pick one sub-repo?"
• Non-git sub-folders → offer git init or skip.
• No git sub-folders at all → refuse.
• CLI flag --as-workspace bypasses the prompt.

[harshitsinghbhandari]

Closing this scoping thread: the provisioning direction is settled as composed child git worktrees for every registered child repo. Follow-up implementation risks are tracked in #161: #161