From b262184406d146d29349acb10afe4c6985b736c6 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 12:06:25 +0300 Subject: [PATCH 1/2] feat(repo): agent sessions on a partial clone (P37d, ADR-0050) sc ws fork/run/harvest/abandon and sc work work on a partial clone. A workspace or agent sees the host's sparse view only (sc work no longer gets a complete tree there); the view closure is filled (lazy, online) or refused with the gap error before anything is written; a workspace commit grafts the out-of-view subtrees from the base without reading them; and harvest lands through the ADR-0049 merge, with any conflict falling back to a work- branch as on a full clone. Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 10 +- ROADMAP.md | 8 +- crates/repo/src/lib.rs | 2 + crates/repo/src/partial_sessions.rs | 170 ++++++++++++++++++++ crates/repo/src/workspace.rs | 86 +++------- crates/repo/src/ws.rs | 122 +++++++------- docs/adr/0049-merge-on-partial-clones.md | 6 +- docs/adr/0050-sessions-on-partial-clones.md | 42 +++++ docs/adr/README.md | 1 + 9 files changed, 308 insertions(+), 139 deletions(-) create mode 100644 crates/repo/src/partial_sessions.rs create mode 100644 docs/adr/0050-sessions-on-partial-clones.md diff --git a/CLAUDE.md b/CLAUDE.md index b5d7d3e6..da7a9031 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -106,7 +106,7 @@ the project tree if desired. ## Capability map (what's built, by phase) -All 36 phases, P37a, P37b-i, P37b-ii and P37c are built and tested. One line of current fact per phase; the +All 36 phases, P37a, P37b-i, P37b-ii, P37c and P37d are built and tested. One line of current fact per phase; the authoritative rationale and full semantics live in the linked ADR, the design in `ARCHITECTURE.md`. The old per-phase narrative log this table replaced is archived verbatim at `docs/archive/claude-md-phase-log-2026-07.md` — do not @@ -153,7 +153,8 @@ the code, those win. | P36 | Bucket WAL remotes (sc+wal://, sc+s3://): immutable packs + CAS'd manifest, checkpoints + log-tail cold start, bucket-backed `sc serve --store` with disposable instances | [0046](docs/adr/0046-wal-bucket-remotes.md) | | P37a | Want-by-id fetch: batched `GetObjects` verb (wire v5), opt-in `.sc/promisor-lazy`, `sc cat :` fills only the absent trees and blob on its path; `Store::get` stays network-free; sealed objects refused by kind; sparse widen and the lifted P27 refusals are P37b | [0047](docs/adr/0047-want-by-id-fetch-and-gap-fill.md) | | P37b-i | Presence-based partial clones: push, verify and gc walk what the store holds (`reachable_objects_partial`), not the fetch filter; push checks every gap id against the destination before sending; a view gap fails with `GapInView` before any write (preflight at the top of `materialize`, plus `undo` and `sparse set`); a partial clone fetches from its origin only. 37b-ii: on a lazy, online clone `ensure_view` fills the view closure by id before switch, fast-forward, undo and `sparse set`, `sparse set` may widen past the filter, a by-id reply is capped at `min(--max-pack-size, 512 MiB)` and a refused batch is split. | [0048](docs/adr/0048-presence-based-partial-clones.md) | -| P37c | Merge, cherry-pick and rebase on a partial clone: a tree-recursive engine (`merge_trees`) carries a subtree by id when the sides agree and no protection rule applies, reads only where they differ or a rule intersects, and on a lazy, online clone fills what it asks for by id outside the store lock (a non-lazy clone gets the gap error with `sc backfill `); a carried protected subtree keeps the complete input wrap union; a conflict inside the view is marked and resolved like on a full clone (`sc conflicts`/`sc resolve`/`merge --abort`/`sc commit`; the out-of-view part is grafted from the decided root), while a conflict outside the view, or a result that must be sealed outside it, is refused before any ref, merge-state or working-tree change (fetched objects stay). A subtree identical on all three sides is carried even under a protection rule. Cherry-pick and rebase use the same engine (`replay_commit`): the fold's accumulator may hold absent subtrees, the view is filled before the final write, and a stopped pick or rebase keeps its carried subtrees in the decided root. Mode-only edits now merge and a file/directory collision fails before any write, on full clones too. Sessions are undecided | [0049](docs/adr/0049-merge-on-partial-clones.md) | +| P37c | Merge, cherry-pick and rebase on a partial clone: a tree-recursive engine (`merge_trees`) carries a subtree by id when the sides agree and no protection rule applies, reads only where they differ or a rule intersects, and on a lazy, online clone fills what it asks for by id outside the store lock (a non-lazy clone gets the gap error with `sc backfill `); a carried protected subtree keeps the complete input wrap union; a conflict inside the view is marked and resolved like on a full clone (`sc conflicts`/`sc resolve`/`merge --abort`/`sc commit`; the out-of-view part is grafted from the decided root), while a conflict outside the view, or a result that must be sealed outside it, is refused before any ref, merge-state or working-tree change (fetched objects stay). A subtree identical on all three sides is carried even under a protection rule. Cherry-pick and rebase use the same engine (`replay_commit`): the fold's accumulator may hold absent subtrees, the view is filled before the final write, and a stopped pick or rebase keeps its carried subtrees in the decided root. Mode-only edits now merge and a file/directory collision fails before any write, on full clones too. | [0049](docs/adr/0049-merge-on-partial-clones.md) | +| P37d | Agent sessions on a partial clone: `sc ws fork`/`run`/`harvest`/`abandon` and `sc work` work; a workspace or agent sees the host's sparse view only (`sc work` no longer gets a complete tree there), the view closure is filled (lazy, online) or refused with the gap error before anything is written, a workspace commit grafts the out-of-view subtrees from the base without reading them, and harvest lands through the ADR-0049 merge (any conflict falls back to a `work-` branch as on a full clone) | [0050](docs/adr/0050-sessions-on-partial-clones.md) | ## Standing boundaries & gotchas @@ -169,10 +170,9 @@ transport-adjacent. The rest, imperatively: renderer has five typed repository commands, no general filesystem/shell capability, and no DTO field capable of carrying protected ciphertext or identity material. -- **Partial clones refuse `sc ws fork`/`harvest`, - `sc work`, `sc export`, `sparse disable`, an empty `sparse set` (and, on a non-lazy clone, one outside the filter), `sc rewrap`, +- **Partial clones refuse `sc export`, `sparse disable`, an empty `sparse set` (and, on a non-lazy clone, one outside the filter), `sc rewrap`, `sc grant`/`revoke`, creating, switching to or leaving a private branch, a merge, cherry-pick or rebase whose conflict lies outside the view or needs sealing outside it (no ref, state or working-tree change), `sc push` to a git remote, and - `sc fetch` from any native remote but the promisor origin.** `sc merge`, `sc cherry-pick` and `sc rebase` work, including conflicts inside the view (P37c). `sc backfill --all` + `sc fetch` from any native remote but the promisor origin.** `sc merge`, `sc cherry-pick` and `sc rebase` work, including conflicts inside the view (P37c). `sc ws` and `sc work` work too (ADR-0050): workspaces and agents see the clone's view only, and harvest lands through the same merge. `sc backfill --all` converts to a genuine full clone and re-enables them. The filter records what a clone *asked for*, not what is present: after a fetch an in-filter object can be absent. On a lazy, online clone a switch, fast-forward, rebase, undo diff --git a/ROADMAP.md b/ROADMAP.md index 479df47f..48c1b488 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -558,12 +558,12 @@ clone: the view closure is filled by id before switch, fast-forward, undo and `sparse disable` stay refused. Design and open questions in [ADR-0048](docs/adr/0048-presence-based-partial-clones.md). -**P37c — merge on partial clones (proposed; 37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay built).** A tree-recursive three-way merge +**P37c — merge on partial clones (built; 37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay).** A tree-recursive three-way merge that carries a subtree by id where the three sides agree, checks protection rules before carrying, never drops wraps for subtrees it does not enumerate, and fills (lazy) or refuses (otherwise) the region where the sides differ, -the region that intersects a protection rule, and the sparse view's closure. Merges are built (`sc merge` on a partial clone): a conflict inside the view is marked, resolved with `sc conflicts`/`sc resolve`, aborted or committed like on a full clone; a conflict outside the view, or one that needs sealing outside it, is refused before any write. Cherry-pick and rebase use the same engine and conflict contract (`sc cherry-pick`, `sc rebase` and their `--continue`/`--abort` work on a partial clone); sessions -are undecided. Design in +the region that intersects a protection rule, and the sparse view's closure. Merges are built (`sc merge` on a partial clone): a conflict inside the view is marked, resolved with `sc conflicts`/`sc resolve`, aborted or committed like on a full clone; a conflict outside the view, or one that needs sealing outside it, is refused before any write. Cherry-pick and rebase use the same engine and conflict contract (`sc cherry-pick`, `sc rebase` and their `--continue`/`--abort` work on a partial clone); sessions are built (P37d, [ADR-0050](docs/adr/0050-sessions-on-partial-clones.md)): workspaces and +agents see the clone's view, and harvest lands through this merge. Design in [ADR-0049](docs/adr/0049-merge-on-partial-clones.md). ## Completed phases (usability-first ordering) @@ -774,7 +774,7 @@ scale-&-reach horizon): workaround proves too coarse in practice. **Now scoped as P37b (ADR-0048) and P37c (ADR-0049, Proposed):** push, verify and gc are presence-based (built); merge is designed in ADR-0049, - with replay following it and sessions undecided. + with replay and sessions (ADR-0050) following it. - **Blob-size/object-count clone filters (P27).** `sc clone --filter` is prefix-only, matching the sparse path-boundary machinery already built; git's `--filter=blob:limit` size-based filtering is a separate axis, diff --git a/crates/repo/src/lib.rs b/crates/repo/src/lib.rs index b400514d..59e7f424 100644 --- a/crates/repo/src/lib.rs +++ b/crates/repo/src/lib.rs @@ -23,6 +23,8 @@ mod partial_merge; #[cfg(test)] mod partial_replay; #[cfg(test)] +mod partial_sessions; +#[cfg(test)] mod partial_walks; pub mod pick_state; pub mod private; diff --git a/crates/repo/src/partial_sessions.rs b/crates/repo/src/partial_sessions.rs new file mode 100644 index 00000000..930cfe2c --- /dev/null +++ b/crates/repo/src/partial_sessions.rs @@ -0,0 +1,170 @@ +//! Tests for agent sessions on a partial clone (ADR-0050): `sc ws` and +//! `sc work` workspaces see the host's view, and harvest lands through the +//! same tree-recursive merge as `sc merge` (ADR-0049). +//! +//! They reuse the merge fixture: an origin with `src/`, `docs/`, `docs/api/` +//! and `lib/`, and a `--filter src/` clone. + +use crate::partial_merge::{dir_id, has, Fx, SRC_A}; +use crate::refs; +use crate::workspace::WorkOptions; +use crate::ws::WsHarvestOutcome; + +const SRC_FIRST: &[u8] = b"ONE\ntwo\nthree\n"; +const SRC_LAST: &[u8] = b"one\ntwo\nTHREE\n"; + +/// `sc ws fork` lays out the view and nothing else. +#[test] +fn fork_materializes_only_the_view() { + let fx = Fx::origin("ws-view", |_| {}); + let clone = fx.clone(false); + let session = clone.ws_fork(2, "t", None).unwrap(); + assert_eq!(session.workspaces.len(), 2); + for ws in &session.workspaces { + assert_eq!(std::fs::read(ws.dir.join("src/a.txt")).unwrap(), SRC_A); + assert!(!ws.dir.join("docs").exists(), "docs is outside the view"); + assert!(!ws.dir.join("lib").exists()); + } + clone.ws_abandon(None).unwrap(); + assert!(clone.ws_session().unwrap().is_none()); + drop(clone); + fx.cleanup(); +} + +/// A workspace edit and a host edit to different lines of the same file merge +/// cleanly, and the out-of-view subtrees are carried by id, never read. +#[test] +fn harvest_lands_a_clean_merge_and_carries_the_out_of_view_subtrees() { + let fx = Fx::origin("ws-land", |_| {}); + let clone = fx.clone(false); + let base = refs::read_branch_tip(clone.layout(), "main") + .unwrap() + .unwrap(); + let docs = dir_id(&clone, &base, "docs"); + let session = clone.ws_fork(1, "t", None).unwrap(); + std::fs::write(session.workspaces[0].dir.join("src/a.txt"), SRC_FIRST).unwrap(); + + // The host moves on in the same file, on another line. + std::fs::write(fx.clone_root.join("src/a.txt"), SRC_LAST).unwrap(); + let host_tip = clone.commit("t", "host edit").unwrap(); + + let outcomes = clone.ws_harvest(None, "t", None).unwrap(); + let merged = match outcomes.as_slice() { + [WsHarvestOutcome::Landed { merged_tip, .. }] => *merged_tip, + other => panic!("expected a clean landing, got {other:?}"), + }; + let snap = clone.snapshot(&merged).unwrap(); + assert_eq!(snap.parents.len(), 2); + assert_eq!(snap.parents[0], host_tip); + assert_eq!( + std::fs::read(fx.clone_root.join("src/a.txt")).unwrap(), + b"ONE\ntwo\nTHREE\n" + ); + assert_eq!(dir_id(&clone, &merged, "docs"), docs, "docs is unchanged"); + assert!(!has(&clone, &docs), "and was never read or fetched"); + assert!(!fx.clone_root.join("docs").exists()); + assert!(clone.ws_session().unwrap().is_none(), "the session ended"); + drop(clone); + fx.cleanup(); +} + +/// Both sides edit the same line: the workspace falls back to a branch and +/// the landing branch is untouched. +#[test] +fn harvest_conflict_falls_back_to_a_branch() { + let fx = Fx::origin("ws-conflict", |_| {}); + let clone = fx.clone(false); + let session = clone.ws_fork(1, "t", None).unwrap(); + std::fs::write(session.workspaces[0].dir.join("src/a.txt"), SRC_FIRST).unwrap(); + std::fs::write(fx.clone_root.join("src/a.txt"), b"uno\ntwo\nthree\n").unwrap(); + let host_tip = clone.commit("t", "host edit").unwrap(); + + let outcomes = clone.ws_harvest(None, "t", None).unwrap(); + match outcomes.as_slice() { + [WsHarvestOutcome::FallbackBranch { branch, .. }] => { + assert_eq!(branch, "work-1"); + } + other => panic!("expected a fallback branch, got {other:?}"), + } + assert!(refs::read_branch_tip(clone.layout(), "work-1") + .unwrap() + .is_some()); + assert_eq!( + refs::read_branch_tip(clone.layout(), "main").unwrap(), + Some(host_tip), + "main did not move" + ); + assert!(!clone.merge_in_progress()); + drop(clone); + fx.cleanup(); +} + +/// An untouched workspace harvests as unchanged, with no branch minted. +#[test] +fn harvest_of_an_untouched_workspace_is_unchanged() { + let fx = Fx::origin("ws-unchanged", |_| {}); + let clone = fx.clone(false); + clone.ws_fork(1, "t", None).unwrap(); + let outcomes = clone.ws_harvest(None, "t", None).unwrap(); + assert!(matches!( + outcomes.as_slice(), + [WsHarvestOutcome::Unchanged { .. }] + )); + assert!(refs::read_branch_tip(clone.layout(), "work-1") + .unwrap() + .is_none()); + drop(clone); + fx.cleanup(); +} + +fn work_opts(cmd: &[&str], scratch: &std::path::Path) -> WorkOptions { + WorkOptions { + agents: 1, + base_name: "agent".into(), + cmd: cmd.iter().map(|s| s.to_string()).collect(), + author: "t".into(), + message: None, + identity: None, + with_secrets: false, + session_root: Some(scratch.join("session")), + } +} + +/// `sc work` agents see the view only, and what they commit is grafted onto +/// the base's out-of-view subtrees without reading them. +#[test] +fn work_agents_see_the_view_and_harvest_without_reading_the_rest() { + let fx = Fx::origin("work-partial", |_| {}); + let clone = fx.clone(false); + let base = refs::read_branch_tip(clone.layout(), "main") + .unwrap() + .unwrap(); + let docs = dir_id(&clone, &base, "docs"); + let scratch = std::env::temp_dir().join(format!("scl-work-partial-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&scratch); + std::fs::create_dir_all(&scratch).unwrap(); + + // The agent proves it cannot see docs/ and edits a file in the view. + let outcomes = clone + .work(work_opts( + &["sh", "-c", "test ! -e docs && echo agent >> src/a.txt"], + &scratch, + )) + .unwrap(); + assert_eq!(outcomes.len(), 1); + assert_eq!(outcomes[0].agent_exit, Some(0)); + let tip = match &outcomes[0].harvest { + Ok(crate::workspace::HarvestResult::Committed(id)) => *id, + other => panic!("expected a committed harvest, got {other:?}"), + }; + assert_eq!( + refs::read_branch_tip(clone.layout(), "agent-1").unwrap(), + Some(tip) + ); + assert_eq!(dir_id(&clone, &tip, "docs"), docs, "docs is carried"); + assert!(!has(&clone, &docs), "and was never read or fetched"); + assert!(!scratch.join("session").exists(), "no session residue"); + std::fs::remove_dir_all(&scratch).unwrap(); + drop(clone); + fx.cleanup(); +} diff --git a/crates/repo/src/workspace.rs b/crates/repo/src/workspace.rs index e06f55ca..c2eb697b 100644 --- a/crates/repo/src/workspace.rs +++ b/crates/repo/src/workspace.rs @@ -88,10 +88,17 @@ pub(crate) fn harvest_workspace( let (tracked, changed) = { let store_arc = repo.vfs().store(); let mut store = store_arc.lock().unwrap(); - let tracked: std::collections::BTreeSet = + // A partial clone's workspace holds the view only: bound the walk by + // it, so an out-of-view subtree this clone never fetched is not read. + let tracked: std::collections::BTreeSet = if repo.promisor()?.is_some() { + worktree::tree_file_entries_with_perms_sparse(&mut store, snap.root, sparse)? + .into_keys() + .collect() + } else { worktree::tree_file_ids(&mut store, snap.root)? .into_keys() - .collect(); + .collect() + }; // The workspace-local cache (P33 Task 7) proves an untouched randomized // protected path unchanged, so it isn't spuriously reported modified // here (which would send it into the fresh-seal path in `snapshot_files` @@ -238,19 +245,20 @@ impl Repo { if opts.cmd.is_empty() { return Err(Error::InvalidArgument("empty agent command".into())); } - // Partial-clone guard (P27 Task 5 review Important fix): `sc work` - // always materializes each workspace with `Sparse::default()` (full - // materialization) by design — an agent needs the complete tree, - // never silently narrowed to the host's sparse view (see - // `materialize_workspace`'s doc comment). On a partial clone "the - // complete tree" includes out-of-filter content this clone never - // fetched, so that materialize call would hit the raw - // corruption-shaped `NotFound` this guard family exists to - // eliminate. Refuse loudly up front instead. - if self.promisor()?.is_some() { - return Err(crate::promisor::partial_clone_unsupported("sc work")); - } let tip = self.head_tip()?.ok_or(Error::Unborn)?; + // A full clone gives each agent the complete tree. A partial clone has + // no complete tree to give: the agents see the host's view, as + // `sc ws` workspaces do (ADR-0050), and its closure is filled first + // (lazy, online clones) or fails with the gap error before anything + // is written. + let view = if self.promisor()?.is_some() { + let view = self.sparse_spec()?; + let tip_root = self.snapshot(&tip)?.root; + self.ensure_view(tip_root, &view)?; + view + } else { + crate::sparse::Sparse::default() + }; let labels: Vec = (1..=opts.agents) .map(|i| format!("{}-{i}", opts.base_name)) .collect(); @@ -309,7 +317,7 @@ impl Repo { tip, &dir, opts.identity.as_ref(), - &crate::sparse::Sparse::default(), + &view, Some(&mut cache), )?; for path in &skipped { @@ -350,7 +358,7 @@ impl Repo { &label, &opts.author, &message, - &crate::sparse::Sparse::default(), + &view, Some(&mut cache), ); outcomes.push(WorkspaceOutcome { @@ -868,50 +876,4 @@ mod tests { let _ = &scratch; // scratch unused here teardown(&root); } - - /// P27 Task 5 review Important fix: `sc work` always materializes each - /// workspace with `Sparse::default()` (full materialization) by design - /// — an agent needs the complete tree. On a partial clone "the complete - /// tree" includes out-of-filter content this clone never fetched, so - /// that materialize call used to hit the raw corruption-shaped - /// `NotFound` this guard family exists to eliminate. Must refuse loudly - /// up front instead. - #[test] - fn work_refuses_on_partial_clone_instead_of_raw_notfound() { - let base = - std::env::temp_dir().join(format!("sc-work-partial-test-{}", std::process::id())); - let _ = std::fs::remove_dir_all(&base); - let src_root = base.join("src"); - let dst_root = base.join("dst"); - let scratch = base.join("scratch"); - std::fs::create_dir_all(src_root.join("src")).unwrap(); - std::fs::create_dir_all(src_root.join("docs")).unwrap(); - std::fs::create_dir_all(&scratch).unwrap(); - let src = Repo::init(&src_root).unwrap(); - std::fs::write(src_root.join("src/a.txt"), b"src-one").unwrap(); - std::fs::write(src_root.join("docs/b.txt"), b"docs-one").unwrap(); - src.commit("t", "c1").unwrap(); - - let dst = Repo::clone_url_filtered( - src_root.to_str().unwrap(), - &dst_root, - Some(&["src/".to_string()]), - ) - .unwrap(); - - let opts = work_opts(1, &["true"], &scratch); - let err = dst.work(opts).unwrap_err(); - assert!( - matches!(err, Error::PartialCloneUnsupported(_)), - "expected the explicit partial-clone-unsupported refusal, got {err:?}" - ); - assert!(err.to_string().contains("not supported on a partial clone")); - // Refused before anything was spawned or materialized: no session - // residue. - assert!(!scratch.join("session").exists()); - - drop(src); - drop(dst); - std::fs::remove_dir_all(&base).unwrap(); - } } diff --git a/crates/repo/src/ws.rs b/crates/repo/src/ws.rs index 7f708dbc..2ef5ae47 100644 --- a/crates/repo/src/ws.rs +++ b/crates/repo/src/ws.rs @@ -204,14 +204,6 @@ impl Repo { if agents == 0 { return Err(Error::InvalidArgument("agents must be >= 1".into())); } - // Partial-clone guard (P27 final review I2): `sc ws harvest` already - // refuses on a partial clone (a real merge needs the full tree - // closure), so an unguarded `ws fork` would create a session that - // can never be harvested — a guaranteed dead end. Refuse at the - // source instead of letting the session get created first. - if self.promisor()?.is_some() { - return Err(crate::promisor::partial_clone_unsupported("ws fork")); - } if let Some(existing) = read_manifest(self.layout())? { return Err(Error::InvalidArgument(format!( "a workspace session is already open ({} workspace(s) forked from branch {} @ {}); \ @@ -228,6 +220,11 @@ impl Repo { // durable session is closer to a second working tree for the same // repo, so it should see the same narrowed checkout the user does. let sparse = self.sparse_spec()?; + // On a partial clone the workspaces see the host's view and nothing + // more (ADR-0050): fill its closure first (lazy, online clones), or + // fail with the gap error before any checkout is written. + let tip_root = self.snapshot(&tip)?.root; + self.ensure_view(tip_root, &sparse)?; let root = ws_dir(self.layout()); // No manifest proves any .sc/ws content is crash residue from a @@ -514,7 +511,7 @@ impl Repo { // this is a hard `Err`, never silently folded into the "not clean" // fallback path. if self.promisor()?.is_some() { - return Err(crate::promisor::partial_clone_unsupported("ws harvest")); + return self.would_merge_cleanly_partial(ours, theirs, identity); } let store_arc = self.vfs().store(); let mut store = store_arc.lock().unwrap(); @@ -557,6 +554,57 @@ impl Repo { } } + /// [`Self::would_merge_cleanly`] on a partial clone: the same question, + /// answered with the tree-recursive engine (ADR-0049), which reads only + /// where the sides differ and fills what it needs by id on a lazy, online + /// clone. Any conflict, in the view or not, is "not clean": the workspace + /// then falls back to a `work-` branch like on a full clone. + fn would_merge_cleanly_partial( + &self, + ours: ObjectId, + theirs: ObjectId, + identity: Option<&scl_crypto::SecretKey>, + ) -> Result { + let (base_snap, ours_snap, theirs_snap) = { + let store_arc = self.vfs().store(); + let mut store = store_arc.lock().unwrap(); + if crate::merge::is_ancestor(&mut store, theirs, ours)? + || crate::merge::is_ancestor(&mut store, ours, theirs)? + { + return Ok(true); // a no-op or a pure fast-forward + } + let Some(base) = crate::merge::merge_base(&mut store, ours, theirs)? else { + return Ok(false); + }; + ( + store.get_snapshot(&base)?, + store.get_snapshot(&ours)?, + store.get_snapshot(&theirs)?, + ) + }; + match crate::merge::merge_secrets( + &base_snap.secrets, + &ours_snap.secrets, + &theirs_snap.secrets, + ) { + Ok(_) => {} + Err(Error::SecretMergeConflict(_)) => return Ok(false), + Err(e) => return Err(e), + } + match self.tree_merge_filled( + Some((base_snap.root, &base_snap.protection)), + (ours_snap.root, &ours_snap.protection), + (theirs_snap.root, &theirs_snap.protection), + identity, + ) { + Ok((done, _)) => Ok(done.merge.conflicts.is_empty()), + Err(Error::ProtectedMergeNeedsIdentity(_)) + | Err(Error::NotAuthorized(_)) + | Err(Error::PathCollision(_)) => Ok(false), + Err(e) => Err(e), + } + } + /// Harvest every live workspace in the open session, landing clean /// results cumulatively onto the checked-out landing branch and falling /// back to a `work-` branch on conflict, scanner rejection, or an @@ -602,20 +650,6 @@ impl Repo { if crate::rebase_state::in_progress(&self.layout) { return Err(Error::RebaseInProgress); } - // Partial-clone guard (P27 Task 5 review Important fix), at the top - // of the whole operation — mirroring `merge_with_identity`'s and - // `sc work`'s own top-level refusals rather than relying solely on - // `would_merge_cleanly`'s inner guard: `harvest_workspace` itself - // (`workspace.rs`) computes its tracked-path set via the UNFILTERED - // `tree_file_ids`, which `NotFound`s on an out-of-filter gap before - // a landing ever reaches the merge probe. Refusing here, before any - // `harvest_workspace` call, turns that into the same loud typed - // error every other partial-clone-unsupported operation gives, - // instead of a raw corruption-shaped `NotFound`. - if self.promisor()?.is_some() { - return Err(crate::promisor::partial_clone_unsupported("ws harvest")); - } - let mut session = read_manifest(self.layout())? .ok_or_else(|| Error::InvalidArgument("no workspace session open".into()))?; @@ -1977,46 +2011,4 @@ mod tests { drop(repo); std::fs::remove_dir_all(&root).unwrap(); } - - /// P27 final review I2: `sc ws fork` is now refused up front on a - /// partial clone (it used to succeed, creating a session that could - /// never be harvested — `ws harvest` already refused with - /// `PartialCloneUnsupported`, but only after the dead-end session was - /// created and an agent may have already done work in it). Refusing at - /// the source eliminates the whole dead-end class instead of just - /// naming it after the fact. - #[test] - fn fork_refuses_on_partial_clone() { - let src_root = tmp_root("fork-partial-src"); - let dst_root = tmp_root("fork-partial-dst"); - std::fs::create_dir_all(src_root.join("src")).unwrap(); - std::fs::create_dir_all(src_root.join("docs")).unwrap(); - let src = Repo::init(&src_root).unwrap(); - std::fs::write(src_root.join("src/a.txt"), b"src-one").unwrap(); - std::fs::write(src_root.join("docs/b.txt"), b"docs-one").unwrap(); - src.commit("t", "c1").unwrap(); - - let dst = Repo::clone_url_filtered( - src_root.to_str().unwrap(), - &dst_root, - Some(&["src/".to_string()]), - ) - .unwrap(); - - let err = dst.ws_fork(1, "t", None).unwrap_err(); - assert!( - matches!(err, Error::PartialCloneUnsupported(_)), - "expected the explicit partial-clone-unsupported refusal, got {err:?}" - ); - assert!(err.to_string().contains("not supported on a partial clone")); - assert!( - read_manifest(dst.layout()).unwrap().is_none(), - "no dead-end session must be created" - ); - - drop(src); - drop(dst); - std::fs::remove_dir_all(&src_root).unwrap(); - std::fs::remove_dir_all(&dst_root).unwrap(); - } } diff --git a/docs/adr/0049-merge-on-partial-clones.md b/docs/adr/0049-merge-on-partial-clones.md index 8c2ab169..e19a31de 100644 --- a/docs/adr/0049-merge-on-partial-clones.md +++ b/docs/adr/0049-merge-on-partial-clones.md @@ -1,6 +1,6 @@ # ADR-0049: Merge on partial clones (P37c) -- **Status:** Proposed (37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay built; sessions open) +- **Status:** Proposed (37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay built; sessions are ADR-0050) - **Date:** 2026-10-17 - **Phase:** 37c - **Builds on:** ADR-0048 (presence-based partial clones), ADR-0047 (want-by-id fetch), ADR-0012 (three-way merge), ADR-0025 (protected merge and replay), ADR-0043 (randomized sealing) @@ -142,7 +142,7 @@ Replay is a three-way merge with a different base, and `replay_commit` is the on - **Conflict state** is decision 8 applied: `PICK_DECIDED_ROOT` and `REBASE_DECIDED_ROOT` hold the CAS-safe entries plus the carried subtrees, nothing is sealed while the op is open, and the same three refusals fire before any write (conflict outside the view, sidecar outside the view or over a tracked file, plaintext to seal outside the view). `ReplayOutcome::Conflicts` therefore carries the subtrees. - **Completion.** `snapshot_files` accepts a recorded decided root for a pick or a rebase step as it does for a merge, grafts the out-of-view part from it, and keeps the union of the tip's and the picked commit's wraps. `rebase --continue` reads its parent's view first, since the accumulator can hold an in-view subtree no earlier step filled. A pick or rebase completion with no decided root still refuses. - **Abort.** `cherry-pick --abort` and `rebase --abort` check the view before they delete anything and remove only sidecars the restored tree does not track, the same as `merge --abort`. `rebase --continue` removes only sidecars its completion parent does not track. A sidecar the user left behind and a commit swept up is the existing defect of q19's kind: completion reads untracked files. -- **Unchanged.** A rebase over a range that contains a merge commit still refuses before replaying anything. Sessions (`sc ws`, `sc work`) stay refused. +- **Unchanged.** A rebase over a range that contains a merge commit still refuses before replaying anything. Sessions (`sc ws`, `sc work`) are ADR-0050. ## Phasing @@ -150,7 +150,7 @@ Replay is a three-way merge with a different base, and `replay_commit` is the on - **37c-ii, clean merge on a partial clone (built).** `merge_with_identity` uses the engine when the clone is partial: `Repo::tree_merge_filled` runs a pass under the store lock, fills what it asked for outside it (`Repo::fill_needs`, batched and split like every by-id fetch) and repeats; a conflict is refused with `PartialCloneUnsupported` before any write; the merged root is built by `Vfs::write_tree_with_carried` (enumerated files plus carried subtrees verbatim, or the carried root as is); `merged_wraps` is the wrap map, unpruned when anything was carried; `ensure_view(merged_root)` runs before the first ref, spec or working-tree write. The differing region's blobs are fetched too: the leaf merge returns file bytes even when one side wins by id, so a region both sides touched is read in full while an untouched subtree (identical on all three sides) is not. Cases from decision 9 that need real repo operations are covered by `partial_merge.rs`: disjoint carry without a fetch, the differing region (fill when lazy, gap error otherwise), a conflict refused, a carried protected subtree keeping its wraps, a keyless protected merge refusing before fetching (the merged result decrypts for the recipient and its plaintext never reaches the CAS), a carried subtree inside the view, and an interrupted fill followed by a retry. The carried wraps are checked byte for byte and by decrypting the carried ciphertext under the merged policy. Merge then gc is covered by the disjoint-carry test. Still open from decision 9: equal plaintext sealed independently, crossed revokes and regrants, an empty-directory entry on a carried side, and a randomized partial-versus-full differential. Demo: `demo/run_lazy_fetch_demo.sh` section 9. - **37c-iii, conflicts (built).** The amendment to decision 8, then markers for in-view conflicts, completion from the decided root, abort, `sc conflicts` and `sc resolve`. A conflict outside the view, or a result that needs sealing outside it, is refused before any write. Tests in `partial_merge.rs` (conflict in view completes with the same tree as a full merge, carried subtree never fetched, abort, out-of-view refusals, carried protected subtree keeps its wraps through completion) and the CLI test `conflicting_merge_on_a_partial_clone_resolves_and_commits`. Demo section 10. - **37c-iv, replay (built).** `cherry-pick` and `rebase` call the same engine through `replay_commit` (decision 10). Tests in `partial_replay.rs` compare each result with the same operation on a full repository by root tree id: a carried subtree never fetched, a differing region filled when lazy and refused otherwise, a conflict in the view completing like a full pick, abort and a view gap on abort, a carried protected subtree keeping its wraps, a rebase carrying the target's subtree through every step, a rebase stopping, aborting, resolving and continuing, and in-view carried subtrees filled on both paths. CLI test `cherry_pick_and_rebase_work_on_a_partial_clone`. Demo section 11. -- **Sessions** (`sc ws`, `sc work`): undecided. They materialize whole checkouts per agent and auto-merge on harvest. Whether they should work on a partial clone at all is a product question. +- **Sessions** (`sc ws`, `sc work`): decided in ADR-0050. Workspaces see the host's view, and harvest lands through this engine. ## Consequences diff --git a/docs/adr/0050-sessions-on-partial-clones.md b/docs/adr/0050-sessions-on-partial-clones.md new file mode 100644 index 00000000..37086d29 --- /dev/null +++ b/docs/adr/0050-sessions-on-partial-clones.md @@ -0,0 +1,42 @@ +# ADR-0050: Agent sessions on partial clones (P37d) + +- **Status:** Accepted (built) +- **Date:** 2026-10-19 +- **Phase:** 37d +- **Builds on:** ADR-0049 (merge on partial clones), ADR-0048 (presence-based partial clones), ADR-0034 (sparse checkouts), ADR-0030 (agent sessions), ADR-0023 (agent workspaces) + +## Context + +`sc ws fork`/`harvest` and `sc work` were refused on a partial clone (ADR-0037, kept by ADR-0048 and ADR-0049). Two reasons stood behind the refusal, and ADR-0049 removed the second: + +1. A workspace is a whole checkout and a partial clone does not hold the whole tree. +2. Harvest lands a workspace by merging, and merge was unsupported. + +ADR-0049 left sessions "undecided" as a product question. The question was whether an agent on a partial clone should be possible at all. This record answers it: yes, with the host's view as the agent's world. That is the point of a partial clone for a large repository, and parallel agents are the other half of the project's thesis. + +## Decisions + +1. **A workspace on a partial clone sees the host's sparse view and nothing else.** `sc ws fork` already inherits the host view (ADR-0034). `sc work` gave each agent the complete tree by design; on a partial clone there is no complete tree, so its agents get the host view too, the same as `sc ws`. This is the one behavioural difference between a full and a partial clone, and it is the documented contract: an agent cannot read or change what the clone does not hold. A user who wants agents to see more runs `sc sparse set` (a lazy clone fetches the widened view by id, ADR-0048) or `sc backfill --all`. + +2. **The view is filled before anything is written.** Fork and `sc work` call `ensure_view` on the base tree: a lazy, online clone fetches the view closure by id, any other clone fails with `GapInView` and the `sc backfill ` hint, before a checkout, a manifest or a branch exists. + +3. **Harvest bounds its tracked-path walk by the workspace's view on a partial clone.** The commit pipeline already grafts everything outside the view from the base snapshot (`snapshot_files`), so a workspace commit carries the out-of-view subtrees by id without reading them. Full clones keep their unbounded walk unchanged. + +4. **Landing uses the ADR-0049 engine.** `ws_harvest` lands a clean workspace with `merge_with_identity`, which on a partial clone is the tree-recursive merge. The probe that decides "lands cleanly or falls back to `work-`" is the same question answered by `tree_merge_filled` (`would_merge_cleanly_partial`): any conflict, inside the view or not, is "not clean", and the workspace becomes a `work-` branch exactly as on a full clone. A conflict outside the view cannot arise from a workspace edit, which holds only the view, but it can arise from the host moving on; it falls back like any other. + +5. **Nothing else changes.** The one-session-per-repo rule, the landing-branch rule, `ws run`/`list`/`abandon`, scanner gating, protected-path carry and the oplog are unchanged. A `sc work` session still leaves no residue. + +## Consequences + +- Fork, run, harvest and abandon, and `sc work`, work on a partial clone, including a lazy one. Their results equal a full clone's for everything inside the view; outside it the result is the base's subtree, carried by id. +- The partial-clone refusal list shrinks to `sc export`, `sparse disable`, an empty `sparse set`, `sc rewrap`, `grant`/`revoke`, private branches, `sc push` to a git remote, and fetching from a remote other than the promisor origin. +- A host that moves on outside the workspace's view between fork and harvest lands without reading that region (carried), but a region both sides changed that the clone does not hold needs a lazy fetch or refuses with the gap error before any write, as for `sc merge`. + +## Tests + +`partial_sessions.rs`: fork lays out the view only; a clean harvest lands a two-parent merge and carries `docs/` unread; a same-line conflict falls back to `work-1` and leaves `main` alone; an untouched workspace is `Unchanged`; `sc work` agents cannot see `docs/`, commit to `agent-1`, leave `docs/` carried and unread, and leave no session residue. + +## Open questions + +1. A workspace on a lazy clone does not fetch on demand while an agent runs: the agent sees the view as it was filled at fork. Reading outside it is not possible by design (decision 1). +2. Sessions on a clone whose `.sc/sparse` is empty (a full view) are only meaningful if the filter covers the whole tree; otherwise `ensure_view` reports the gap. diff --git a/docs/adr/README.md b/docs/adr/README.md index 9ee290aa..a4cbd65e 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -60,6 +60,7 @@ supersedes the old one and update the **Status** line of the superseded record. | [0047](0047-want-by-id-fetch-and-gap-fill.md) | Want-by-id fetch and explicit gap fill for partial clones | Accepted (37a built) | 37 | | [0048](0048-presence-based-partial-clones.md) | Presence-based walks for partial clones | Accepted (37b-i, 37b-ii built) | 37b | | [0049](0049-merge-on-partial-clones.md) | Merge on partial clones | Proposed (37c-i to 37c-iv built) | 37c | +| [0050](0050-sessions-on-partial-clones.md) | Agent sessions on partial clones | Accepted | 37d | See [`ROADMAP.md`](../../ROADMAP.md) for the phase sequence. ADR numbers are assigned in creation order, so 0017 — the secret scanner — sequences as phase P5, From daf143acdc79632e031365607718da4118d00bd1 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Mon, 19 Oct 2026 12:11:34 +0300 Subject: [PATCH 2/2] fix(repo): check the view against the host before a session writes, and drop a failed harvest's candidate Sol review: fork and sc work relied on materialize's preflight, which a workspace layout (not a partial clone) skips, so a view gap surfaced mid-write as a raw NotFound; they now run preflight_view against the host layout first. A harvest whose probe or landing fails before any write left its candidate work- branch behind, and a retry minted another; it is deleted on that path (a real conflict keeps it). Co-Authored-By: Claude Sonnet 5.5 --- crates/repo/src/partial_sessions.rs | 85 +++++++++++++++++++++++++++++ crates/repo/src/workspace.rs | 8 +++ crates/repo/src/ws.rs | 29 +++++++++- 3 files changed, 121 insertions(+), 1 deletion(-) diff --git a/crates/repo/src/partial_sessions.rs b/crates/repo/src/partial_sessions.rs index 930cfe2c..a14e6832 100644 --- a/crates/repo/src/partial_sessions.rs +++ b/crates/repo/src/partial_sessions.rs @@ -168,3 +168,88 @@ fn work_agents_see_the_view_and_harvest_without_reading_the_rest() { drop(clone); fx.cleanup(); } + +/// A non-lazy clone whose HEAD view holds a gap: fork and `sc work` fail with +/// the gap error before any session state or checkout exists. +#[test] +fn fork_and_work_refuse_a_view_gap_before_writing_anything() { + let fx = Fx::origin("ws-gap", |_| {}); + let clone = fx.clone(false); + // The origin adds src/copy.md with the bytes of docs/a.md. The clone never + // fetched that blob (docs/ is outside its filter), so after a fetch an + // in-filter object is absent. Its main is pointed at the new tip. + std::fs::write(fx.origin_root.join("src/copy.md"), b"a\n").unwrap(); + fx.origin + .commit("t", "adds a src file sharing a docs blob") + .unwrap(); + clone.fetch("origin").unwrap(); + let tip = refs::resolve_tip(clone.layout(), "origin/main") + .unwrap() + .unwrap(); + refs::write_branch_tip(clone.layout(), "main", &tip).unwrap(); + assert!( + !has(&clone, &crate::partial_merge::blob_id(b"a\n")), + "premise: a gap" + ); + + let err = clone.ws_fork(1, "t", None).unwrap_err(); + assert!( + matches!(err, crate::error::Error::GapInView { .. }), + "got {err:?}" + ); + assert!(clone.ws_session().unwrap().is_none()); + assert!(!clone.layout().dot_sc.join("ws").exists(), "no session dir"); + + let scratch = std::env::temp_dir().join(format!("scl-work-gap-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&scratch); + std::fs::create_dir_all(&scratch).unwrap(); + let err = clone.work(work_opts(&["true"], &scratch)).unwrap_err(); + assert!( + matches!(err, crate::error::Error::GapInView { .. }), + "got {err:?}" + ); + assert!(!scratch.join("session").exists(), "no session residue"); + std::fs::remove_dir_all(&scratch).unwrap(); + drop(clone); + fx.cleanup(); +} + +/// A probe that cannot be answered (the host moved a protected region the +/// clone does not hold) fails the harvest, and must not leave a candidate +/// `work-` branch behind: a retry would mint another one. +#[test] +fn a_failing_probe_leaves_no_candidate_branch() { + let (_sk, pk) = scl_crypto::generate_keypair(); + let fx = crate::partial_merge::protected_origin("ws-probe", &pk); + let b1 = fx.origin_branch("b1", &[("vault/s.txt", b"L1\nl2\nl3\n")]); + let clone = fx.clone(false); + let session = clone.ws_fork(1, "t", None).unwrap(); + std::fs::write(session.workspaces[0].dir.join("src/a.txt"), SRC_FIRST).unwrap(); + // The host fast-forwards to a commit that changed the protected vault/, + // which the clone does not hold and cannot fetch. + clone.merge("origin/b1", "t").unwrap(); + assert_eq!( + refs::read_branch_tip(clone.layout(), "main").unwrap(), + Some(b1) + ); + + let err = clone.ws_harvest(None, "t", None).unwrap_err(); + eprintln!("probe error: {err:?}"); + assert!( + refs::read_branch_tip(clone.layout(), "work-1") + .unwrap() + .is_none(), + "no candidate branch may survive a failed harvest ({err:?})" + ); + assert!( + clone.ws_session().unwrap().is_some(), + "the workspace stays live" + ); + assert_eq!( + refs::read_branch_tip(clone.layout(), "main").unwrap(), + Some(b1) + ); + clone.ws_abandon(None).unwrap(); + drop(clone); + fx.cleanup(); +} diff --git a/crates/repo/src/workspace.rs b/crates/repo/src/workspace.rs index c2eb697b..621c2c86 100644 --- a/crates/repo/src/workspace.rs +++ b/crates/repo/src/workspace.rs @@ -255,6 +255,14 @@ impl Repo { let view = self.sparse_spec()?; let tip_root = self.snapshot(&tip)?.root; self.ensure_view(tip_root, &view)?; + // Presence against the host's layout, before any checkout: a + // workspace's own layout is not a partial clone, so its + // materialize would not catch a gap (non-lazy or offline clone). + { + let store_arc = self.vfs().store(); + let mut store = store_arc.lock().unwrap(); + crate::worktree::preflight_view(self.layout(), &mut store, tip_root, &view)?; + } view } else { crate::sparse::Sparse::default() diff --git a/crates/repo/src/ws.rs b/crates/repo/src/ws.rs index 2ef5ae47..a6f471c8 100644 --- a/crates/repo/src/ws.rs +++ b/crates/repo/src/ws.rs @@ -225,6 +225,15 @@ impl Repo { // fail with the gap error before any checkout is written. let tip_root = self.snapshot(&tip)?.root; self.ensure_view(tip_root, &sparse)?; + // `ensure_view` fills only when it can; on a non-lazy or offline clone + // the view may still hold a gap. Check presence against the HOST's + // layout now: a workspace's own layout is not a partial clone, so its + // materialize would not, and the gap would surface mid-write. + { + let store_arc = self.vfs().store(); + let mut store = store_arc.lock().unwrap(); + crate::worktree::preflight_view(self.layout(), &mut store, tip_root, &sparse)?; + } let root = ws_dir(self.layout()); // No manifest proves any .sc/ws content is crash residue from a @@ -794,7 +803,17 @@ impl Repo { crate::workspace::HarvestResult::Committed(id) => { let current_tip = refs::read_branch_tip(self.layout(), &landing)?.ok_or(Error::Unborn)?; - let clean = self.would_merge_cleanly(current_tip, id, identity)?; + // The candidate branch exists only to be landed or kept for + // a conflict. A failing probe leaves the workspace live for + // a retry, which would mint another candidate: remove this + // one first. + let clean = match self.would_merge_cleanly(current_tip, id, identity) { + Ok(clean) => clean, + Err(e) => { + let _ = refs::delete_branch(self.layout(), &branch); + return Err(e); + } + }; if clean { // The second tuple element on `Ok` is skipped // protected paths (missing-identity skips), not @@ -856,6 +875,14 @@ impl Repo { // of three_way's parameters is wrong, not a // normal user-facing conflict. Bail loudly // before any teardown. + if !matches!(e, Error::MergeConflicts(_)) { + // Refused before any write (a gap, a policy + // error): the workspace stays live, so drop + // the candidate rather than leak one per + // retry. A real conflict keeps it: its + // markers are on disk. + let _ = refs::delete_branch(self.layout(), &branch); + } return Err(if matches!(e, Error::MergeConflicts(_)) { Error::BadRef(format!( "ws harvest: probe predicted a clean merge of {branch} \