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.

[harshitsinghbhandari]

Proposed resolution for the root-file model: version the parent (root-as-repo)

Picking up risk #1 (root symlinks are not a write barrier). I think the cleanest answer is to stop treating root files as a special case and make the parent folder a git repo (gitignoring the child-repo paths). A workspace session then becomes uniformly worktrees: a parent worktree holding the root files plus one child worktree per registered repo, all on ao/<session-id>. This is the "root-as-repo" option the deep-dive doc currently lists only as a footnote escape hatch — I think it should be the default.

The reframe that drives this

The current doc frames root files as "shared read context." For the files this feature actually names — package.json, pnpm-workspace.yaml, Makefile, scripts/ — that's empirically false. The defining operations write root paths as a side effect:

• pnpm/npm/yarn install rewrites the root lockfile next to package.json
• build tools write root dist/, .cache/, .turbo/, generated config
• the root manifest + workspace file are active participants in resolution, not inert docs

So this isn't a "how do we expose read-only context" problem. It's a "what happens when the normal toolchain writes a root path" problem. The symlink model turns the common, benign event (a lockfile write) into silent cross-session corruption of canonical, then patches it with detection the doc itself admits isn't a real barrier.

Why root-as-repo beats the alternatives

• vs symlink + enforcement (current doc): under root-as-repo, a tool writing the lockfile is just an uncommitted change in an isolated worktree. Git already provides the isolation the symlink model tries to fake with policy. No enforcement layer, no root-write lock, no root_access mode.
• vs copy-per-session + promotion: copy fixes the corruption but adds drift (stale snapshot) and a promotion path for shared edits, and it's a second isolation model bolted on next to the worktree model used for children. Root-as-repo needs neither — root edits are commits, shared via the same per-repo PR flow as child code, with real history and rollback. One mechanism, not two.
• vs submodules (already rejected): no .gitmodules, no gitlink bookkeeping, no detached-HEAD/file-protocol UX. The parent and children stay fully independent repos that merely share a directory.

Nesting behavior — verified, not theoretical

The obvious worry is "a child git repo living inside a parent git repo's worktree." I ran this end to end with live git. It's clean on one condition: the parent must gitignore each child path before its first commit.

• With children ignored from the start, the parent tracks only root files; git status reports !! cli/ (ignored). Git discovery stops at the nearest .git, so a command run inside session/cli resolves to the cli repo and a command at the session root resolves to the parent — no confusion.
• A parent worktree with a child worktree nested inside it works: each .git is an independent pointer; git add -A in the parent never touches the child.
• git clean -fdx in the parent leaves the nested child untouched.
• git worktree list is per-repo; teardown is just "remove child worktrees, then the parent worktree, then prune."

The one hard requirement / trap: if a child dir is git add-ed while not ignored, git records it as an embedded gitlink (160000 <sha> cli) — a broken submodule — and once embedded, adding it to .gitignore afterward does not untrack it. So "ignore-first" must be enforced in the registration code path, ideally with a guard that refuses to commit a parent index containing a 160000 entry for a known child path.

Implementation implications

Registration (--as-workspace):

• Parent already a git repo → use as-is; just ensure child paths are in .gitignore.
• Parent plain → git init, write .gitignore listing each detected child path plus a build/junk denylist (node_modules, dist, build, .cache, .turbo, target, …), then one initial commit of the root files. Ignore-children-before-first-add is mandatory.
• Record the parent as a workspace repo (a reserved root entry, or a projects.root_is_repo flag) so spawn/cleanup treat it as just another worktree.

Spawn: create the parent worktree at the session root, then each child worktree inside it. The parent worktree materializes only tracked root files; ignored child dirs are absent, leaving the paths free for the child worktree commands. One session_worktrees row per repo, including the root.

Edits / cleanup: root changes are ordinary commits on ao/<session-id>, isolated per session (git owns concurrency). Teardown reuses worktree-remove semantics for every repo including the root. No root-write-violation detection, no manifest reconciliation.

Schema impact — net simpler than the current plan:

• Drop: sessions.root_access (read|write), project_root_write_locks, and any session_root_files/root-context-manifest table — none are needed.
• Add: a single signal that the parent is a versioned repo. The root then reuses session_worktrees verbatim.
• Workspace support collapses to "N+1 worktrees per session." The root stops being a special case.

This also dissolves most of risk #2's matrix for the root: the root is no longer an un-versioned blob that cleanup might silently delete — it's a worktree with the same dirty/refuse/prune semantics as every child.

Accepted tradeoffs

• Invasive init: AO writes .git/.gitignore/an initial commit into a plain parent. This contradicts the "no metadata in the parent folder" preference — accepting it deliberately, because one uniform correct mechanism beats a non-invasive but leaky/two-model alternative.
• No-remote parent: if the parent has no origin, root changes still commit locally on the session branch but can't open a PR until a remote exists. Degraded (root work isn't PR-reviewable), not broken. Worth surfacing at registration.
• Pre-existing parent .gitignore/history: merge AO's child-ignore entries into the existing file rather than overwriting; never re-init an existing repo.

Net

Versioning the parent deletes the symlink enforcement layer, the root-write lock, and the root_access mode entirely, and makes the root just one more worktree — same isolation, branch, PR, history, and cleanup semantics as the child repos. The only genuinely new constraints are the ignore-first discipline (enforceable) and PR fan-out requiring a parent remote.

[harshitsinghbhandari]

Follow-up: how root changes actually travel (the N+1 fan-out, no parent remote)

The root-as-repo proposal above answers "where do root edits live" (a parent worktree on ao/<session-id>), but it leaves the harder half unanswered: how does a root change get home? This is the part the symlink and copy models both fudged, so spelling it out.

A workspace session produces N+1 independent deliverables

A session that touches cli/ and the root package.json has changed two unrelated repos: the cli repo and the parent (root-as-repo). Those travel on different rails and do not move together:

• Child repos (have remotes): commit on ao/<session-id> → push → PR on the child's origin → review/merge on GitHub. Unchanged from today.
• Parent / root files (no remote, AO-created): there is no PR. The cli PR physically cannot carry package.json — it's not part of the cli repo.

So right after the cli PR merges, the package.json change is: saved as a commit on ao/<session-id> in the local parent repo, not in any PR, and not yet in the user's real abc/package.json. It sits on the branch, stranded, until something explicitly lands it. The danger is obvious: child PR merges, everyone moves on, and the root change is silently forgotten (or discarded at worktree cleanup). The model has to make that change visible and landable.

Detection is a local git check, not a remote webhook

This is the key difference from child repos. The SCM observer learns about child changes by watching the remote (PR/CI/merge events). The parent has no remote, so there's nothing to watch. Instead AO asks git directly — and it can, because all worktrees of the parent share one object store, so the session branch is already present in the canonical parent with no push:

git -C <canonical>/<parent> rev-list --count main..ao/<session-id>   # >0 ⇒ root changed
git -C <canonical>/<parent> diff             main..ao/<session-id>   # the root diff to review

Cheap, offline, always available. AO runs it (at session completion, or while reconciling the session's child PRs); if non-empty, it raises a "session has unlanded root changes" signal — a new, local notification to the orchestrator that sits alongside the existing PR-based signals for children.

Landing is a gated local merge into the parent's main

"Travel home" = a local merge that updates the user's real parent checkout on disk:

git -C <canonical>/<parent> merge ao/<session-id>     # or rebase / --ff-only

No remote, no push, no GitHub. (If the user later adds a remote to the parent, root changes can additionally be pushed/PR'd like children — graceful upgrade, never forced.)

What this nails down

• Review surface / no orphaning: the session-detail view becomes the unifying place — per-child PR rows (cli: PR #123 open, api: PR #124 merged) plus a root row (root: 3 files changed · view diff · land into main). Children reviewed on GitHub; root reviewed inline and landed on confirm. No split-brain, nothing forgotten.
• Gated, not automatic: the orchestrator/human confirms before the merge, and AO must refuse/handle a dirty canonical checkout or a conflict (e.g. another session already advanced main).
• Concurrency is just merges — this replaces the root-write lock entirely. Two sessions that both touched root = two branches landed sequentially, conflicts resolved by git. There is no exclusive-access mechanism, no root_access mode, no project_root_write_locks — git branches + merge already provide the isolation and serialization the lock was trying to emulate.

The one genuinely open product decision

Everything above is forced by git mechanics. The only real choice left is when the land is triggered and by whom: at session completion, when the last child PR merges, or purely on-demand by the orchestrator. That's a product call, not a git constraint.

Net

Child changes travel by PR (unchanged). Root changes are detected by a local main..ao/<session> diff, surfaced to the orchestrator as an unlanded-root signal, and landed by a gated local merge into the parent's main — no remote required, ever. This is also what lets us delete the symlink enforcement layer, the root-write lock, and the root_access mode from the design: the root becomes one more worktree whose changes are reviewed and merged like everything else, just locally instead of via GitHub.

[harshitsinghbhandari]

Resolved: branch / base / collision / registration policy (risk #3)

Decisions for the branch and registration questions from this thread, so the adapter is unblocked.

Base ref per child

Each child worktree branches off its local default branch tip — no fetch at spawn.

• Deterministic and offline; spawn never blocks on the network or on a remote being reachable.
• Consistent with the worktree model (we branch from what's already in the local repo).
• Store the resolved base per child in session_worktrees so restore/audit is explicit.
• Trade-off accepted: a child can be behind its remote. That's a deliberate "branch from local state" choice; users who want latest upstream fetch first. (If the parent/child has a remote and the team wants freshness, that's a future opt-in, not V1 default.)

Branch name (the one-shared-name invariant)

Default name is ao/<session-id> in every repo, parent included. The invariant — one logical session ⇒ one branch name everywhere — is load-bearing for detect/land and restore, so we never mix names across repos.

Collision rule: if ao/<session-id> already exists in any repo (child or parent), derive a single unique suffixed name (e.g. ao/<session-id>-2, incrementing until free in all repos) and use that same name across all repos — not just the colliding ones.

exists ao/abc-7 in api only?  ->  use ao/abc-7-2 in api AND cli AND parent

Pseudocode: compute the name once at spawn by probing existence across the full repo set, bump the suffix until it's free everywhere, then create that one name in each repo. Still store the (identical) name per child in session_worktrees.branch so per-repo state stays explicit.

Registration validity — strict, with an auto-fix offer

Each child repo must:

• have ≥1 commit and an identifiable default branch, and
• not be a bare repo or a directory that is an external worktree of another repo.

If a child fails these (e.g. freshly git init-ed with no commit, or not a repo at all), AO offers to auto-fix — git init -b main for a plain folder, or make an initial commit — rather than hard-refusing. Non-git child folders are skipped by default (per the doc); auto-fix is the opt-in path to include them.

Parent (root-as-repo) specifics

• Parent already a git repo: adopt it as-is. Merge each child path into the existing .gitignore (don't overwrite), and don't re-init or require a clean tree.
• Plain parent: git init, write .gitignore listing every child path plus a build/junk denylist, then make the initial commit — ignore-children-before-first-add is mandatory.
• Embedded-gitlink guard: refuse to commit a parent index that contains a 160000 (gitlink) entry for a known child path. This is the one trap that's unrecoverable after the fact (.gitignore can't untrack an already-embedded gitlink), so it's enforced in code, not left to convention.

[harshitsinghbhandari]

Resolved: composite lifecycle matrix (risk #2)

This is the second artifact this thread asked for. The key enabler is a primitive that turns the worst row — "dirty worktree refuses removal forever" — into a solved case.

Primitive: preserve uncommitted state to a ref, per repo

git stash doesn't store anything in the worktree — it writes a commit object into the shared repository and a ref pointing at it. The worktree is disposable; the repo underneath survives its removal. So we snapshot, force-remove freely, and rehydrate on restore. Verified round-trip (staged + unstaged + untracked all came back, with the staged/unstaged split intact):

# on destroy, per repo, if dirty:
git -C <wt> stash push -u -q -m "ao-preserve <session-id>"
git -C <wt> update-ref refs/ao/preserved/<session-id> "$(git -C <wt> rev-parse refs/stash)"
git -C <wt> stash drop -q
# worktree is now clean -> remove --force is safe

# on restore, per repo, if a preserved ref exists:
git -C <repo> worktree add <wt> ao/<session-id>
git -C <wt> stash apply --index refs/ao/preserved/<session-id>   # restores staged/unstaged/untracked

Each repo has its own ref store, so the ref lives in that repo (refs/ao/preserved/<session-id> in the parent and in cli and in api — identical names, no collision). It outlives the worktree because refs live in the common dir, not the worktree. The session_worktrees row — already keyed (session_id, repo_name) — records whether a preserved ref exists. .gitignored files are intentionally excluded (build junk shouldn't be preserved).

The matrix

Scenario	Operation	Action
Provision fails partway (child N can't be created)	Create	Remove already-created worktrees; leave no registered half-session.
Worktree clean	Destroy	git worktree remove + prune.
Worktree dirty (uncommitted)	Destroy	Snapshot to refs/ao/preserved/<session> (per repo), then force-remove.
One worktree locked / removal fails	Destroy	Snapshot + force-remove the rest; don't block the whole teardown on one repo.
All worktrees present & valid	Restore	Verify; no-op.
Dir missing, row exists	Restore	Recreate worktree on the branch; reapply preserved ref if present.
Path exists but isn't the registered worktree (stray)	Restore	Move aside (*.stray-<ts>, nothing deleted), then recreate.
Preserved-ref reapply conflicts	Restore	Leave conflict markers; surface "reapplied with conflicts." Never swallow.
Canonical child moved/deleted mid-session	any	Mark that repo unavailable; keep the rest of the session working.
Worktree removed manually outside AO	Restore	Detected as dir-missing → recreate (+ reapply preserved ref).

Snapshot lifetime

Every session is restorable — there is no "permanently killed" session. "Kill" = suspend. Preserved refs therefore persist for the session's whole lifetime and are removed only on:

1. a successful reapply during restore, or
2. an explicit session deletion by the user.

Net effect: cleanup always succeeds (no zombie worktrees, no disk litter, no "retry forever" state), and uncommitted work is never lost — it's either reapplied on restore or recoverable from the ref until the session is explicitly deleted.

[harshitsinghbhandari]

Resolved: status aggregation + remote-aware root delivery (risk #4, and the tail of #1)

Session status aggregation (risk #4)

List view = worst-of-N. A workspace session's single glanceable status is the least-done state across all its child PRs, with unlanded root changes counted as a pending item. Rough ordering (worst wins):

CI-failing  >  changes-requested  >  open/in-review  >  root-unlanded(pending)  >  all-merged-and-root-landed

So a session shows "done" only when every child PR is merged and the root changes are landed (or there were none). One failing child, or an un-landed root diff, keeps the whole session visibly not-done — which is the safe bias.

Detail view shows the breakdown: a per-child PR list (each repo's PR + CI/review state) plus a root row — the main..ao/<session> diff with a land (or open PR, see below) action. Children are reviewed on their GitHub PRs; the root row is where the root change is reviewed/landed.

Cross-repo bulk operations (cancel-all / rebase-all / merge-all) are out of V1, explicitly deferred. V1 keeps existing per-PR actions plus the single root land/PR action.

Remote-aware root delivery (tail of #1)

Root-change detection is unchanged and remote-independent: a local main..ao/<session> diff (works because the parent's worktrees share one object store — no push needed to see the branch). What differs is delivery, based on whether the parent has a remote:

• No remote (default case): land locally — git -C <canonical-parent> merge ao/<session> into main, surfaced at session completion and merged on confirm. No PR, no CI; review happens inline on the detail-view root row.
• Remote present: treat root like a child repo — push the root branch and open a PR (real review + CI) instead of a local merge. Falls back to local-land automatically if no remote.

This makes the root symmetric with child repos when the infra allows it, and degrades to a local merge when it doesn't — without ever forcing the user to add a remote. The status model above already accounts for both: "root-unlanded" covers an un-merged local diff or an open root PR.

Net for the thread

With this + the branch policy and lifecycle matrix comments above, all five risks raised here have a decided answer:

1. Root-file model → root-as-repo + detect/land (remote-aware).
2. Composite lifecycle → full matrix, with uncommitted-state preservation per repo.
3. Branch/base/collision → local-default base, one-shared-(possibly-suffixed)-name, strict+auto-fix registration.
4. PR fan-out → worst-of-N list status, per-child + root detail, bulk ops deferred.
5. Platform edge cases → largely mooted (no symlinks anywhere in this model).

The remaining task is the doc PR to replace the symlink section of workspace-projects.md with this model.

[harshitsinghbhandari]

The proposals in this thread have been consolidated — and audited/corrected (a stash-on-conflict hole in the lifecycle matrix, a two-dot vs three-dot diff bug in the root-review surface, land mechanics that previously could trample the user's checkout, plus detection of uncommitted root changes) — into a single final design: #164. Treat #164 as the implementable spec; the comments above are its derivation history. Note the original post's "settled" list still mentions read-only root symlinks — that direction is superseded by root-as-repo in #164, and docs/workspace-projects.md needs a follow-up PR to match.