Workspace projects: final design — root-as-repo, change propagation, full lifecycle

[harshitsinghbhandari]

Workspace projects: final design — root-as-repo, change propagation, full lifecycle

This supersedes the root-file sections of docs/workspace-projects.md and consolidates the resolution thread in #161 into one implementable spec. Follow-up to #155 and #161. Every git-mechanical claim below was verified with live git; the lifecycle rules also fix two bugs found while auditing the #161 thread (a stash-on-conflict failure and a two-dot/three-dot diff error — see §10).

What stays settled from #155/#161: composed child git worktrees, no submodules, no --targets, every session gets all registered child repos, PR ownership stays session-centric.

What changes: root files are no longer "read-only symlink context with enforcement." The parent folder becomes a git repo. Everything is a worktree.

---

1. The model in one paragraph

A workspace project's parent folder is a git repo (root-as-repo) whose .gitignore excludes every child-repo path. A session is then uniformly N+1 worktrees: one parent worktree at the session root holding the root files (package.json, Makefile, scripts/, …) plus one child worktree per registered repo nested inside it — all on the same branch name. Root files get full git semantics — isolation per session, history, diff/review, rollback, and merge-based concurrency — from the same mechanism as everything else. The symlink layer, the root-write lock, and the root_access mode are deleted.

canonical/abc/                  # git repo (root-as-repo), tracks root files only
  .gitignore                    # ignores /cli/, /api/ + build junk
  package.json
  cli/                          # independent git repo, remote github.com/org/abc-cli
  api/                          # independent git repo, remote github.com/org/abc-api

managed/abc/abc-7/              # parent worktree, branch ao/abc-7
  package.json                  # tracked by parent repo
  cli/                          # worktree of cli, branch ao/abc-7
  api/                          # worktree of api, branch ao/abc-7

Why this beats the alternatives (full analysis in #161): the root files named by this feature are written by the normal toolchain (pnpm install rewrites the root lockfile; builds write root caches). Symlinks turn that common benign event into silent cross-session corruption of canonical, patched by enforcement that is admittedly not a barrier. A per-session copy fixes corruption but adds drift plus a second isolation model and a promotion path. Root-as-repo needs neither: a tool write is an uncommitted change in an isolated worktree; an intentional root edit is a commit; sharing is a merge. The invasiveness (AO writes .git into the parent) is explicitly accepted.

---

2. Registration (ao project add --path <parent> --as-workspace)

Child detection is unchanged: direct child git repos are registered; non-git children skipped.

Child validity — strict, with auto-fix offer. Each child must have ≥1 commit and an identifiable default branch; bare repos and directories that are worktrees of an external repo are rejected. On failure AO offers the fix (git init -b main, initial commit) instead of hard-refusing.

Parent setup:

• Parent already a git repo → adopt as-is. Merge missing child paths into the existing .gitignore (never overwrite), commit that edit. Never re-init; never require further cleanliness beyond the gitignore commit being possible.
• Parent plain folder → git init -b main, write .gitignore containing every child path plus a junk denylist (node_modules/, dist/, build/, .cache/, .turbo/, target/, …), then a single initial commit of the root files.
• Ordering is mandatory: ignore the children before the first git add. An un-ignored child dir gets recorded as an embedded gitlink (160000) — a broken submodule — and .gitignore cannot untrack it afterwards (verified).
• Gitlink guard (registration): refuse to create any parent commit whose index contains a 160000 entry. This guard is code, not convention.
• Registration commits use the user's normal git config/hooks; if the parent identity is unset, surface the standard git error and stop — do not invent an identity.

---

3. Spawn

Provision order: parent worktree first (git -C <parent> worktree add <session-root> -b <branch> <base>), then each child worktree inside it. The parent worktree materializes only tracked root files; ignored child paths are absent, leaving them free for the child worktree add calls. One session_worktrees row per repo, parent included (reserved repo name __root__ or a projects.root_is_repo flag — implementer's choice, but the root must flow through the same row machinery).

Base ref: each repo (parent and children) branches off its local default branch tip. No fetch at spawn; deterministic and offline. Staleness vs the remote is accepted — users who want latest pull first. Store the resolved base SHA per row.

Branch name — one-shared-name invariant: default ao/<session-id> in every repo. If that name already exists in any repo (possible because branches are retained for restorability, §5), compute one suffixed name (ao/<session-id>-2, incrementing) that is free in all repos and use that same name everywhere. Name selection is done once, under the daemon's spawn serialization (no probe race). The name is stored per row; never derived.

Partial provision failure: if child N fails, remove the already-created worktrees (children first, then parent) and leave no registered half-session.

---

4. How changes travel (the N+1 fan-out)

A session that touches cli/ and package.json has changed two unrelated repos. The deliverables travel on different rails and do not move together:

4.1 Children — unchanged

Commit on the session branch → push to the child's origin → PR → review/CI/merge on the SCM. Exactly today's flow, times N.

4.2 Root — detection (local, three checks)

The parent usually has no remote, so there is no webhook to watch. Detection is local git, possible because all parent worktrees share one object store (a session commit is in the canonical parent the instant it's made — no push). At session completion (and on demand), the root is "pending" if any of:

1. Committed work ahead: git rev-list --count main..ao/<session> > 0;
2. Uncommitted work in the parent worktree: git status --porcelain non-empty — committed-only detection would silently miss edits the agent never committed, which is exactly the loss this design exists to prevent;
3. A preserved-state ref exists for the root row (§5).

The review diff is three-dot: git diff main...ao/<session> (merge-base diff). Two-dot compares tips and, once main has advanced from another session's land, misleadingly shows the reverse of unrelated landed work (verified — see §10).

Gitlink guard (land-time): if the root diff introduces any 160000 entry (e.g. the agent cloned a repo into the session root and committed), block the land/PR and surface it. The registration-time guard alone is insufficient because agents run git in the parent worktree for the session's whole life.

4.3 Root — delivery, remote-aware

• No remote (default): land = local merge of the session branch into the parent's main, surfaced at session completion and executed on explicit confirm — never automatic. Review happens on the three-dot diff in the session detail view.
• Remote present: treat the root like a child — push the branch, open a PR (real review + CI). Pull-back is part of the flow: when the root PR merges, AO must update the canonical parent's local main (pull --ff-only when canonical is on a clean main; otherwise fetch origin main:main). Without this, the local-default base policy (§3) hands the next session a stale root base. Falls back to local-land when no remote. Never forces the user to add one.

4.4 Land mechanics — never trample the user's checkout

The merge target is main, which may be checked out in the user's canonical working tree (possibly dirty), and git refuses the same branch in two worktrees. Exact rules:

• canonical on main, clean → merge directly in canonical (the result belongs there anyway);
• canonical on main, dirty → refuse with "commit/stash root changes in , then retry";
• canonical not on main → main is unattached: perform the merge in a temporary worktree of main, remove it after; canonical is untouched and sees the result on next switch/pull.
• Merge conflict → abort the merge, leave canonical pristine, surface "root land conflicts with current main" with the conflicting paths. Resolution happens via a deliberate re-run, not a half-merged user checkout.

4.5 Discard — the third exit

Lockfile-churn-only root diffs will be the common case. The session detail therefore has three root actions: land (or open PR), view diff, and discard — which marks the root row resolved without merging. Nothing is deleted (the branch survives for restorability, §5); discard only clears the pending status. Without this, worst-of-N status (§6) nags forever on trivial sessions.

4.6 Concurrency — merges replace the lock

Two sessions touching root = two branches, landed sequentially; conflicts are git conflicts, handled by §4.4. This replaces project_root_write_locks and sessions.root_access entirely. There is no exclusive root access anywhere in the design.

---

5. Lifecycle: preserve primitive + full matrix

5.1 Primitive: per-repo preserved-state ref

git stash writes a commit into the shared repository, not the worktree, so uncommitted state can outlive worktree removal:

# 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
# restore, per repo, if ref exists:
git -C <wt> stash apply --index refs/ao/preserved/<session-id>

Verified round-trip: staged, unstaged, and untracked all survive force-destroy → restore, including the staged/unstaged split (--index). Each repo has its own ref store, so the same ref name lives independently in the parent and every child — the row key (session_id, repo_name) records which rows hold one. .gitignored files are deliberately not captured (that's build junk). The ref is dropped only on a clean reapply or explicit session deletion.

Known limitation (fixes a #161 bug): git stash push fails on unmerged (conflict) entries and cannot capture in-progress merge/rebase state — verified. Since §5.2's own "reapply with conflicts" row produces that state, destroy must handle it explicitly; see the matrix. "Cleanup always succeeds" is therefore scoped: it always succeeds except for in-progress-operation worktrees (explicit rule below) and OS-level file locks (e.g. Windows open handles), which remain retry-later.

5.2 The matrix

State	Operation	Action
Provision fails at repo N	create	remove already-created worktrees (children first), no half-session
Worktree clean	destroy	worktree remove + prune
Worktree dirty	destroy	snapshot to preserved ref → remove --force
Worktree has unmerged entries / in-progress merge-rebase	destroy	refuse + surface by default ("resolve or abort, then retry"). Explicit force path: abort the in-progress op, snapshot what remains, remove — audited. If the conflict came from our own reapply, the original preserved ref still exists (only dropped on clean apply), so the forced abort loses nothing durable
One worktree's removal fails (lock/handle)	destroy	snapshot + force the rest; mark the stuck row retry-later; never block the whole teardown
Teardown order	destroy	children first, then parent. Removing the parent first deletes the child worktree dirs inside it and strands stale registrations in every child repo. Parent removal effectively always needs --force (ignored junk) — safe, since anything preservable was snapshotted
All rows present + valid	restore	verify, no-op
Dir missing, row exists (incl. manual deletion)	restore	recreate worktree on the stored branch; reapply preserved ref if present
Path exists but is not the registered worktree	restore	move aside to <name>.stray-<timestamp> (nothing deleted), recreate
Preserved-ref reapply conflicts	restore	keep conflict markers, keep the ref, surface "reapplied with conflicts" — never swallow
Canonical child repo moved/deleted mid-session	any	mark that repo unavailable, keep the rest of the session working. Accepted loss: that child's session work — committed and preserved — lived in its object store and is unrecoverable. Surfaced, not hidden

5.3 Retention — every session is restorable

There is no permanently-killed session; kill = suspend. Session branches (ao/…, in every repo) and preserved refs are retained for the session's entire life and removed only on explicit session deletion (delete the branch in every repo + every preserved ref). Accumulation across many sessions is accepted; it is also the only reason branch-name collisions exist, which the suffix rule (§3) absorbs.

---

6. Status aggregation

List view — worst-of-N, root included. One glanceable status; worst wins:

child unavailable / PR closed-unmerged / CI failing
  > changes requested
  > open / in review
  > root pending (unlanded local diff OR open root PR)
  > done (all child PRs merged ∧ root landed/PR-merged/discarded/none)

A session is "done" only when every child deliverable is merged and the root is resolved (landed, PR-merged, discarded, or never changed). Terminal-but-bad states (child unavailable, PR closed without merge) rank as needs-attention, not done.

Detail view: per-child PR rows (PR + CI/review state) plus a root row: the three-dot diff with land / open-PR / discard actions per §4.

Cross-repo bulk operations (merge-all / rebase-all / cancel-all): explicitly out of V1.

---

7. Schema

ALTER TABLE projects ADD COLUMN kind TEXT NOT NULL DEFAULT 'single_repo'
  CHECK (kind IN ('single_repo', 'workspace'));
-- plus a signal that the parent is the root repo (flag or reserved workspace_repos row)

CREATE TABLE workspace_repos (
  project_id      TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  name            TEXT NOT NULL,
  relative_path   TEXT NOT NULL,
  repo_origin_url TEXT NOT NULL DEFAULT '',
  registered_at   TIMESTAMP NOT NULL,
  PRIMARY KEY (project_id, name),
  UNIQUE (project_id, relative_path)
);

CREATE TABLE session_worktrees (
  session_id     TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
  repo_name      TEXT NOT NULL,          -- includes the root row
  branch         TEXT NOT NULL,          -- identical across rows, possibly suffixed
  base_sha       TEXT NOT NULL,
  worktree_path  TEXT NOT NULL,
  preserved_ref  TEXT NOT NULL DEFAULT '',  -- refs/ao/preserved/<session> when set
  state          TEXT NOT NULL DEFAULT 'active',
    -- active | removed | retry_remove | unavailable | stray_moved
  PRIMARY KEY (session_id, repo_name)
);

Deleted from the previous plan: sessions.root_access, project_root_write_locks, and the root-context manifest table. Workspace support collapses to "N+1 worktrees per session"; the root is not a special case in the schema.

---

8. Accepted tradeoffs (explicit, so nobody relitigates silently)

1. Invasive init — AO writes .git/.gitignore/a commit into a plain parent. Accepted: one uniform correct mechanism beats a non-invasive leaky one.
2. No CI/review for no-remote roots — local land is reviewed only as a diff in AO. Teams that want CI on root add a remote (then §4.3 PR flow applies).
3. Stale local base — sessions branch from local default tips without fetching. Users pull for freshness; root PR merges trigger pull-back (§4.3).
4. Canonical child deleted ⇒ that child's session work is gone — its object store was the canonical repo. Surfaced as unavailable; unrecoverable by design.
5. In-progress-operation worktrees block destroy (default refuse) — correctness over convenience; the force path exists and is audited.
6. OS-level file locks can still defer cleanup (notably Windows open handles) — retry-later, not failure.
7. Branch/ref accumulation under every-session-restorable retention — bounded by explicit session deletion only.
8. User hooks fire for AO-created commits/merges in the parent repo (user's config, user's hooks). AO does not bypass them.

---

9. Implementation slices (updated)

1. Project model + detection + registration — projects.kind, workspace_repos, --as-workspace, strict child validation + auto-fix offer, parent adopt-or-init with gitignore-first + registration gitlink guard.
2. Session worktree schema — session_worktrees incl. root row, base_sha, preserved_ref, state.
3. Composite adapter — N+1 provision (order: parent → children), one-shared-name selection with suffix probe, teardown (children → parent), preserve/reapply primitive, full §5.2 matrix. Integration tests: two siblings + root; dirty destroy/restore round-trip; in-progress-merge refusal; stray-path move-aside; manual child deletion.
4. Root propagation — three-check detection, three-dot diff, land state machine (§4.4), discard, land-time gitlink guard, remote-aware PR + pull-back.
5. SCM observer + status — child origins from workspace_repos, PR-to-session attribution unchanged, worst-of-N + root-pending aggregation.

Slices 1–2 are unblocked today. Slice 3 depends on nothing outside this document. Slices 4–5 depend on 3.

---

10. Verified git facts (receipts)

Everything load-bearing was tested with live git rather than assumed:

• Nesting: with children gitignored before the first add, a parent repo tracks only root files; discovery stops at the nearest .git, so commands at the session root resolve to the parent and commands inside cli/ resolve to cli; git add -A in the parent never touches ignored children; git clean -fdx in the parent leaves nested child repos alone; git worktree list is per-repo.
• The gitlink trap: an un-ignored child dir staged in the parent becomes 160000 <sha> cli, and adding it to .gitignore afterwards does not untrack it. Hence the ignore-first rule and the two guards.
• Shared object store: a commit made on the session branch in a parent worktree is immediately visible (log, diff) from the canonical parent with zero remotes configured, and a local merge lands it into the canonical working file.
• Preserve round-trip: staged + unstaged + untracked survive stash push -u → update-ref → worktree remove --force → worktree add → stash apply --index, with the staged/unstaged distinction intact.
• Stash-on-conflict failure: git stash push -u on a worktree with unmerged entries fails (error: could not write index). This is why the matrix has an explicit in-progress-operation row instead of claiming universal snapshot-ability.
• Two-dot vs three-dot: after main advances, git diff main..ao/x shows the reverse of unrelated landed work; git diff main...ao/x shows only the session's changes. The review surface must be three-dot.

---

Decision log (for the record)

Decision	Choice
Root-file model	root-as-repo (parent is a git repo; symlink + copy models rejected)
Base ref	local default branch tip, no fetch at spawn
Branch name	ao/<session-id>; on any collision, one suffixed name used in all repos
Registration validity	strict (≥1 commit, default branch, no bare/external-worktree) + auto-fix offer
Parent already a repo	adopt as-is, merge gitignore entries
Root land timing	surface at completion, execute on confirm; discard available
Root delivery w/ remote	push + PR like a child, with post-merge pull-back; local land otherwise
Dirty worktree on destroy	snapshot to per-repo preserved ref, then force-remove
In-progress op on destroy	refuse by default; audited force = abort + snapshot + remove
Partial removal failure	snapshot + force the rest; stuck row → retry-later
Stray path on restore	move aside (*.stray-<ts>), recreate
Canonical child gone	mark unavailable, continue; loss surfaced
Snapshot/branch retention	every session restorable; removal only on explicit session deletion
Status	worst-of-N incl. root-pending; bulk ops out of V1