Workspace projects: design risks before implementation

[harshitsinghbhandari]

Workspace project Option 1: design risks to resolve before implementation

Follow-up to #155.

The provisioning direction from #155 is now settled:

• use composed child git worktrees;
• do not use parent-level submodules as the default workspace model;
• do not add --targets for V1;
• every workspace session gets worktrees for all registered child repos;
• root-level parent files are exposed to normal sessions as read-only context via symlinks;
• root edits require an explicit orchestrator-authorized root-write path.

This thread is for the problems that remain in that design before we start coding past the first schema/registration slice.

1. Root symlinks are not a write barrier

The current doc says normal workers see root files through read-only symlinks. That is useful for workspace shape, but it is not enforcement by itself.

Likely day-one failure modes:

• pnpm install, npm install, or yarn install writes a lockfile next to the root manifest and can mutate canonical root state through the symlinked path.
• build tools may write root-level .cache/, dist/, stamp files, generated config, or lockfiles;
• common editor/shell paths (sed -i, tee, shell redirection, Python open(..., "w"), etc.) follow symlinks;
• symlinked root directories such as scripts/ or tools/ are recursively write-through;
• while a root-write session is editing canonical root files, normal sessions reading through symlinks can observe changing or partially written files.

Questions to decide:

• Is V1 honest-policy-only, with root writes treated as undefined/unsupported behavior?
• Do we need active write detection or command blocking for obvious dangerous commands like package-manager installs?
• Should root context symlinks be files-only for V1, with root directories skipped or copied?
• What is the exact UX when AO detects a root write violation?

2. Composite cleanup and restore need a state matrix

Single-repo cleanup already has an important invariant: do not force-delete dirty registered worktrees. With all child repos provisioned for every workspace session, cleanup now has N opportunities to partially fail.

Scenarios to enumerate:

• one child worktree has untracked build artifacts and git worktree remove refuses forever;
• cleanup removes cli/ successfully, then api/ refuses, leaving a partially cleaned composite root;
• restore after partial cleanup must know whether to recreate missing child worktrees, preserve dirty ones, or refuse;
• canonical child repo is deleted or moved while a session is alive;
• user manually removes one child worktree outside AO;
• branch or git metadata becomes inconsistent after force-push / GC / manual git operations.

Questions to decide:

• For each create/restore/destroy/cleanup partial-failure row, is the response retry, refuse + user action, or force with an explicit audit trail?
• Does cleanup become all-or-nothing, or can AO remove some child worktrees and persist a partial-cleanup state?
• What user-visible state should a session show when only some child worktrees remain?

3. Branch/base/collision policy across all child repos

V1 likely uses one shared branch name, ao/<session-id>, in every child repo. That still leaves several policy choices.

Questions to decide:

• What base ref is used per child repo: remote default branch, local default branch, current HEAD, or user-supplied branch?
• What happens if ao/<session-id> already exists in one child repo but not the others?
• Do we suffix, refuse, or attach to the existing branch?
• At registration time, do we require every child repo to have at least one commit and an identifiable default branch?
• Do we reject bare repos or child folders that are themselves git worktrees of an external repo?

4. PR fan-out and session status aggregation

One workspace session can produce one PR per child repo. PR ownership can still point to the session, but the product read model needs an aggregation rule.

Questions to decide:

• Does the session list show worst-of-N PR/CI/review status?
• Does the session detail page show per-repo PR pills/list?
• What happens when one repo PR is merged and another is still failing CI?
• Are cross-repo bulk operations like cancel/rebase/merge-all in scope for V1, or explicitly deferred?

Likely V1 answer: worst-of-N status in list views, per-child PR list in detail views, and no cross-repo bulk operations beyond existing per-PR actions.

5. Platform and registration edge cases

These are probably lower priority than the first four, but should be named before implementation:

• Windows symlink privileges / Developer Mode / path length / case-insensitive collisions (cli vs CLI);
• same basename collisions for nested direct children such as frontend/ui and mobile/ui if we ever support more than direct children;
• symlinked child repos (api -> /opt/work/api) and whether registration follows, refuses, or warns;
• root .gitignore, .envrc, .npmrc, .tool-versions, etc. as read-through context with side effects;
• remote/origin drift after registration (workspace_repos.repo_origin_url becoming stale);
• SQLite CHECK enum future-proofing for projects.kind.

Proposed next step

Before coding past project detection + registration, write two small design artifacts:

1. Root-file enforcement model — what V1 actually guarantees, what it detects, and what it refuses.
2. Composite lifecycle matrix — create/restore/destroy/cleanup behavior for each partial-failure case.

Those two are operationally more important than revisiting the provisioning choice itself. Option 1 remains the right provisioning model; this discussion is about making it safe enough to ship.