Review and return worktree commits without automatic commits or discarded conflicts

Author: ShadowfetchStudio

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.20.0 — native development (unreleased)
 
+- Reviewed CLI worktree return prepares incoming commits in the source index
+  without committing. Stale reviews and active work are rejected; conflicts and
+  ignored local files are preserved for explicit resolution.
+
 - CI now exercises 200 native tasks, stalled-provider cancellations and output
   floods while checking memory, descriptors, child cleanup and history integrity.
 

docs/NATIVE_CLI.md

@@ -94,8 +94,12 @@ forwards ordinary shutdown signals, waits for native cleanup, and preserves the
 payload's exit status. Force-killing the wrapper still reports its signal status;
 the native child observes wrapper loss and shuts down.
 
-See [native worktrees](NATIVE_WORKTREES.md) for `worktree --create` and running
-tasks in a separate branch while preserving source checkout edits.
+See [native worktrees](NATIVE_WORKTREES.md) for creation, reviewed removal,
+missing-checkout recovery and reviewed return of committed work.
+`worktree --review-return ID` inspects incoming changes;
+`worktree --return-changes ID --return-hash HASH` prepares them in the source
+index without committing. Conflicts return a nonzero exit status and preserve
+the Git merge state for explicit resolution or abort.
 
 ## Saved work and settings
 

docs/NATIVE_MIGRATION.md

@@ -59,7 +59,9 @@ the existing React visual design. This document tracks engineering acceptance;
   branches and commits.
   CLI and desktop rescue restore a missing checkout’s retained commit into a
   separate checkout while preserving original recovery metadata. Dirty-state
-  transfer, damaged-path repair and reviewed return of changes remain open.
+  transfer, damaged-path repair and desktop return controls remain open.
+  Reviewed CLI return prepares a merge without committing, preserving source
+  branch work and leaving conflicts for explicit resolution or Git merge abort.
 
 The Rust workspace is being introduced alongside the Python release. Existing
 features remain acceptance requirements; an unimplemented native feature must

docs/NATIVE_VERIFICATION.md

@@ -304,6 +304,20 @@ these transitions. Assertions inspect fresh complete frames because incremental
 ANSI updates can split words. This covers resize recovery; broader picker
 navigation, visual review and sustained terminal stress remain open.
 
+## Reviewed return of worktree commits
+
+Nine worktree tests pass. Return-specific scenarios exercise diverged branches,
+source HEAD preservation until a separate commit, stale hashes after source
+commits, dirty/untracked files, active worktree reservations, source background
+processes, already-integrated commits, conflicts retained for manual resolution
+or abort, ignored-file collisions and changed source repository roots. Testing
+found that Git's `--no-overwrite-ignore` alone did not prevent an ignored-file
+overwrite in this merge path; explicit incoming-path/ignored-path intersection
+checks now reject it before mutation. Original worktree commits remain intact.
+The native CLI passes 19 scenario groups / 32 scripted model requests, including
+review, stale-hash rejection, uncommitted return and a separate merge commit.
+Clippy and the native build pass. Desktop return controls remain open.
+
 ## Missing-worktree committed recovery
 
 Six worktree tests pass, including a real Git checkout with an unmerged commit

docs/NATIVE_WORKTREES.md

@@ -64,8 +64,8 @@ removal, just as with ordinary Git operations. Damaged checkout paths or missing
 inspection; the recovery record remains. For a missing path whose Git
 registration survives, use the reviewed rescue below.
 
-Carrying uncommitted changes into an isolated checkout, reviewed return/merge
-operations and recovery controls for missing/damaged checkouts remain part of the
+Carrying uncommitted changes into an isolated checkout, desktop return controls
+and repair of damaged checkouts remain part of the
 [native migration gates](NATIVE_MIGRATION.md).
 
 Inventory and individual actions share the same bounded, non-following record
@@ -99,3 +99,38 @@ commit, together with the uncommitted-file limitation. **Restore in new worktree
 creates the separate checkout; **Cancel recovery** closes the review without
 changes. Errors clear stale reviews. Use **Open worktree** on the newly listed
 checkout to enter the usual project trust flow.
+
+## Review and return committed changes
+
+```sh
+shadowcode --workspace /source/project worktree --review-return FULL_WORKTREE_ID
+shadowcode --workspace /source/project worktree --return-changes FULL_WORKTREE_ID --return-hash REVIEW_HASH
+```
+
+The review includes the exact source/worktree branches and commits, their merge
+base, and the worktree's incoming diff from that base. This is the incoming
+branch diff, not a promise of a conflict-free merge. Reviews larger than the
+64 KB Git-output limit must be handled through ordinary Git review tools.
+Both checkouts must be attached to branches, free of tracked/untracked changes
+and unfinished Git operations. Locked worktrees and already-integrated commits
+are rejected. The source must be trusted and writable. Active tasks/manual
+operations or background processes in either checkout block the return.
+
+The return rechecks the review hash, then prepares `git merge --no-commit --no-ff`
+in the source checkout. HEAD stays unchanged: review the staged result and commit
+separately using the source project's normal Git review tools. Git preserves
+nonconflicting source-branch work when histories have diverged. Conflicts remain
+in the source files/index for explicit resolution; the result is
+`needs_attention`, with a nonzero CLI exit status. Inspect `git status`, resolve
+and commit, or run `git merge --abort` in the source project to abandon the merge.
+Interrupted operations retain a `returning` recovery record explaining what was
+attempted. No reset, auto-stash, automatic commit, branch deletion or checkout
+removal is performed. Ignored source files cannot be overwritten by the merge.
+The worktree branch and committed contents remain available throughout.
+
+Git hooks and filesystem-monitor hooks are disabled for these operations; Git's
+configured merge drivers and checkout filters still apply. Keep external Git or
+filesystem writers idle during review and return, as with ordinary Git merges.
+After committing or aborting, the record's last-operation status is historical;
+future actions inspect the actual Git state again. Dedicated desktop return
+controls remain in development.

native/core/src/cli/args.rs

@@ -53,22 +53,30 @@ pub enum Command {
     },
     /// List managed worktrees, or create an isolated branch at a local commit.
     Worktree {
-        #[arg(long,conflicts_with_all=["inspect","remove","recovery","restore"])]
+        #[arg(long,conflicts_with_all=["inspect","remove","recovery","restore","review_return","return_changes"])]
         create: bool,
-        #[arg(long, conflicts_with_all = ["remove","recovery","restore"])]
+        #[arg(long, conflicts_with_all = ["remove","recovery","restore","review_return","return_changes"])]
         inspect: Option<String>,
-        #[arg(long, requires = "hash", conflicts_with_all = ["recovery","restore"])]
+        #[arg(long, requires = "hash", conflicts_with_all = ["recovery","restore","review_return","return_changes"])]
         remove: Option<String>,
         #[arg(long, requires = "remove")]
         hash: Option<String>,
         /// Review retained commits for a missing managed checkout.
-        #[arg(long, conflicts_with = "restore")]
+        #[arg(long, conflicts_with_all = ["restore","review_return","return_changes"])]
         recovery: Option<String>,
         /// Restore a reviewed commit to a separate checkout, retaining original metadata.
-        #[arg(long, requires = "recovery_hash")]
+        #[arg(long, requires = "recovery_hash", conflicts_with_all = ["review_return","return_changes"])]
         restore: Option<String>,
         #[arg(long, requires = "restore")]
         recovery_hash: Option<String>,
+        /// Review committed changes before returning them to the source project.
+        #[arg(long, conflicts_with = "return_changes")]
+        review_return: Option<String>,
+        /// Prepare a reviewed merge in the source checkout without committing.
+        #[arg(long, requires = "return_hash")]
+        return_changes: Option<String>,
+        #[arg(long, requires = "return_changes")]
+        return_hash: Option<String>,
         #[arg(long, default_value = "HEAD", requires = "create")]
         reference: String,
     },

native/core/src/cli/mod.rs

@@ -870,8 +870,13 @@ async fn execute(backend: &Backend, workspace: &Path, options: &Options) -> Resu
                 });
             }
         }
-        Command::Worktree {create,reference,inspect,remove,hash,recovery,restore,recovery_hash}=>{
-            if let Some(id)=restore {backend.call("POST","/api/worktrees/restore",json!({"id":id,"hash":recovery_hash})).await?}
+        Command::Worktree {create,reference,inspect,remove,hash,recovery,restore,recovery_hash,review_return,return_changes,return_hash}=>{
+            if let Some(id)=return_changes {
+                let value=backend.call("POST","/api/worktrees/return",json!({"id":id,"hash":return_hash})).await?;
+                return Ok(Outcome{code:if value["state"]=="merge_pending" {0}else{1},value,raw:None});
+            }
+            else if let Some(id)=review_return {backend.call("POST","/api/worktrees/review-return",json!({"id":id})).await?}
+            else if let Some(id)=restore {backend.call("POST","/api/worktrees/restore",json!({"id":id,"hash":recovery_hash})).await?}
             else if let Some(id)=recovery {backend.call("POST","/api/worktrees/recovery",json!({"id":id})).await?}
             else if let Some(id)=remove {backend.call("POST","/api/worktrees/remove",json!({"id":id,"hash":hash})).await?}
             else if let Some(id)=inspect {backend.call("POST","/api/worktrees/inspect",json!({"id":id})).await?}

native/core/src/service.rs

@@ -213,6 +213,49 @@ impl Service {
                     .await?
                 ));
             }
+            ("POST", "/api/worktrees/review-return") => {
+                let workspace = self.workspace()?;
+                ensure!(
+                    Config::load(self.engine.paths(), Some(&workspace))?.is_trusted(&workspace),
+                    "Trust the source project before reviewing returned changes"
+                );
+                return Ok(json!(
+                    crate::worktrees::review_return(
+                        self.engine.paths(),
+                        &workspace,
+                        text("id"),
+                        CancellationToken::new()
+                    )
+                    .await?
+                ));
+            }
+            ("POST", "/api/worktrees/return") => {
+                let ws = self.mutable_workspace()?;
+                let reviewed = crate::worktrees::review_return(
+                    self.engine.paths(),
+                    &ws.path,
+                    text("id"),
+                    ws.reservation.cancellation(),
+                )
+                .await?;
+                let _target = self.engine.reserve_workspace(&reviewed.record.path)?;
+                let _source_background =
+                    self.engine.background().reserve_idle_workspace(&ws.path)?;
+                let _target_background = self
+                    .engine
+                    .background()
+                    .reserve_idle_workspace(&reviewed.record.path)?;
+                let record = crate::worktrees::return_changes(
+                    self.engine.paths(),
+                    &ws.path,
+                    text("id"),
+                    text("hash"),
+                    ws.reservation.cancellation(),
+                )
+                .await?;
+                store.add_event("worktree.returned", &json!(record), None, None)?;
+                return Ok(json!(record));
+            }
             ("POST", "/api/worktrees/recovery") => {
                 let workspace = self.workspace()?;
                 ensure!(