Rescue reviewed retained commits from missing managed worktrees

Author: ShadowfetchStudio

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.20.0 — native development (unreleased)
 
+- Native development: reviewed CLI rescue for missing worktrees restores retained
+  commits into a new checkout while preserving the original branch, index and
+  registration; missing uncommitted files are not reconstructed.
+
 - Desktop Settings adds worktree creation, opening through project trust,
   inspection and reviewed removal. Actions bind to the displayed source project;
   dirty or stale reviews cannot authorize removal.

docs/NATIVE_MIGRATION.md

@@ -57,8 +57,9 @@ the existing React visual design. This document tracks engineering acceptance;
   separate managed branch, preserved source edits, private recovery records and
   CLI inventory, desktop Settings controls and reviewed clean removal that retains
   branches and commits.
-  Dirty-state transfer, missing-checkout recovery and reviewed return of changes
-  remain open.
+  CLI rescue restores a missing checkout’s retained commit into a separate
+  checkout while preserving original recovery metadata. Dirty-state transfer,
+  desktop recovery, damaged-path repair and reviewed return of changes remain open.
 
 The Rust workspace is being introduced alongside the Python release. Existing
 features remain acceptance requirements; an unimplemented native feature must

docs/NATIVE_VERIFICATION.md

@@ -278,6 +278,19 @@ 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.
 
+## Missing-worktree committed recovery
+
+Six worktree tests pass, including a real Git checkout with an unmerged commit
+and staged changes moved away from its managed path. Recovery refuses existing
+paths, locked registrations and stale hashes. Reviewed restoration creates a
+separate checkout at the retained commit; the original index and recovery record
+are byte-for-byte unchanged, and the original branch, registration and moved
+files remain. The native executable passes 18 CLI scenario groups / 32 scripted
+model requests, including recovery preview, stale-hash rejection and restoration.
+Clippy and the native build pass. This restores committed work only; automatic
+reconstruction of missing uncommitted files is not claimed. Desktop rescue and
+damaged-path repair remain open.
+
 ## Desktop worktree controls
 
 The native Settings panel creates and lists worktrees, opens the normal trust

docs/NATIVE_WORKTREES.md

@@ -60,8 +60,9 @@ checks; removal never uses `--force` or deletes branches. Unmerged commits remai
 on the preserved branch. Source files and selection remain unchanged.
 
 Files deliberately changed by external programs should be preserved before
-removal, just as with ordinary Git operations. Missing or damaged checkout
-registrations still require manual inspection; the recovery record remains.
+removal, just as with ordinary Git operations. Damaged checkout paths or missing Git registrations still require manual
+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
@@ -70,3 +71,25 @@ operations and recovery controls for missing/damaged checkouts remain part of th
 Inventory and individual actions share the same bounded, non-following record
 reader. A record whose filename, managed path or branch identity has changed is
 rejected before it can be presented as a usable worktree.
+
+## Rescue a missing checkout's committed work
+
+```sh
+shadowcode --workspace /path/to/repository worktree --recovery FULL_WORKTREE_ID
+shadowcode --workspace /path/to/repository worktree --restore FULL_WORKTREE_ID --recovery-hash REVIEW_HASH
+```
+
+The review resolves the missing checkout's registered HEAD, including commits
+not merged into the source project. Restoration creates a **new** managed branch
+and checkout from that exact commit. It does not reconstruct missing uncommitted
+files. The original branch, registration, index and recovery record remain
+untouched so staged changes or a moved checkout can still be recovered manually.
+No global Git prune, forced removal or branch reset is performed.
+
+An existing path (including a symlink), locked registration, changed repository,
+missing commit, unavailable registration or stale review blocks rescue. A locked
+worktree may be on an unavailable device; inspect its location before unlocking.
+Trust and writable/idle source requirements also apply. Open and trust the new
+checkout explicitly. The original record remains in the active inventory until
+its underlying checkout is repaired and reviewed for removal. Dedicated desktop
+rescue controls and automatic repair of damaged paths remain open.

native/core/src/cli/args.rs

@@ -53,14 +53,22 @@ pub enum Command {
     },
     /// List managed worktrees, or create an isolated branch at a local commit.
     Worktree {
-        #[arg(long,conflicts_with_all=["inspect","remove"])]
+        #[arg(long,conflicts_with_all=["inspect","remove","recovery","restore"])]
         create: bool,
-        #[arg(long, conflicts_with = "remove")]
+        #[arg(long, conflicts_with_all = ["remove","recovery","restore"])]
         inspect: Option<String>,
-        #[arg(long, requires = "hash")]
+        #[arg(long, requires = "hash", conflicts_with_all = ["recovery","restore"])]
         remove: Option<String>,
         #[arg(long, requires = "remove")]
         hash: Option<String>,
+        /// Review retained commits for a missing managed checkout.
+        #[arg(long, conflicts_with = "restore")]
+        recovery: Option<String>,
+        /// Restore a reviewed commit to a separate checkout, retaining original metadata.
+        #[arg(long, requires = "recovery_hash")]
+        restore: Option<String>,
+        #[arg(long, requires = "restore")]
+        recovery_hash: Option<String>,
         #[arg(long, default_value = "HEAD", requires = "create")]
         reference: String,
     },

native/core/src/cli/mod.rs

@@ -870,8 +870,10 @@ async fn execute(backend: &Backend, workspace: &Path, options: &Options) -> Resu
                 });
             }
         }
-        Command::Worktree {create,reference,inspect,remove,hash}=>{
-            if let Some(id)=remove {backend.call("POST","/api/worktrees/remove",json!({"id":id,"hash":hash})).await?}
+        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?}
+            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?}
             else {backend.call(if *create {"POST"}else{"GET"},"/api/worktrees",json!({"reference":reference})).await?}
         },

native/core/src/service.rs

@@ -213,6 +213,40 @@ impl Service {
                     .await?
                 ));
             }
+            ("POST", "/api/worktrees/recovery") => {
+                let workspace = self.workspace()?;
+                ensure!(
+                    Config::load(self.engine.paths(), Some(&workspace))?.is_trusted(&workspace),
+                    "Trust the source project before inspecting recovery"
+                );
+                return Ok(json!(
+                    crate::worktrees::recovery(
+                        self.engine.paths(),
+                        &workspace,
+                        text("id"),
+                        CancellationToken::new()
+                    )
+                    .await?
+                ));
+            }
+            ("POST", "/api/worktrees/restore") => {
+                let ws = self.mutable_workspace()?;
+                let record = crate::worktrees::restore(
+                    self.engine.paths(),
+                    &ws.path,
+                    text("id"),
+                    text("hash"),
+                    ws.reservation.cancellation(),
+                )
+                .await?;
+                store.add_event(
+                    "worktree.restored",
+                    &json!({"original_id":text("id"),"checkout":record}),
+                    None,
+                    None,
+                )?;
+                return Ok(json!(record));
+            }
             ("POST", "/api/worktrees") => {
                 let ws = self.mutable_workspace()?;
                 let reference = body["reference"].as_str().unwrap_or("HEAD");

native/core/src/worktrees.rs

@@ -405,3 +405,106 @@ pub async fn remove(
         }
     }
 }
+
+/// A rescue creates a new checkout; it never prunes the missing checkout's
+/// registration or index, which may still contain recoverable staged changes.
+#[derive(Clone, Debug, Serialize)]
+pub struct Recovery {
+    pub record: Record,
+    pub commit: String,
+    pub branch: String,
+    pub warning: String,
+    pub hash: String,
+}
+pub async fn recovery(
+    paths: &AppPaths,
+    source: &Path,
+    id: &str,
+    cancel: CancellationToken,
+) -> Result<Recovery> {
+    use sha2::{Digest, Sha256};
+    let record = read_record(paths, source, id)?;
+    match fs::symlink_metadata(&record.path) {
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+        _ => anyhow::bail!(
+            "Checkout path still exists or cannot be inspected; preserve it before recovery"
+        ),
+    }
+    let common = PathBuf::from(
+        git(
+            source,
+            &["rev-parse", "--path-format=absolute", "--git-common-dir"],
+            cancel.clone(),
+        )
+        .await?,
+    )
+    .canonicalize()?;
+    ensure!(
+        common == record.common_directory,
+        "Source repository identity changed"
+    );
+    let registered = git(
+        source,
+        &["worktree", "list", "--porcelain", "-z"],
+        cancel.clone(),
+    )
+    .await?;
+    let expected = format!(
+        "worktree {}",
+        record
+            .path
+            .to_str()
+            .context("Worktree path must be UTF-8")?
+    );
+    let block = registered
+        .split("\0\0")
+        .find(|block| block.split('\0').any(|field| field == expected))
+        .context(
+            "Missing checkout registration is unavailable; inspect retained branches manually",
+        )?;
+    ensure!(!block.split('\0').any(|field| field == "locked" || field.starts_with("locked ")), "Worktree is locked; it may be on an unavailable device. Review its location before recovery");
+    let commit = block
+        .split('\0')
+        .find_map(|field| field.strip_prefix("HEAD "))
+        .context("Registered checkout has no retained commit")?
+        .to_string();
+    ensure!(
+        matches!(commit.len(), 40 | 64) && commit.bytes().all(|b| b.is_ascii_hexdigit()),
+        "Invalid retained commit"
+    );
+    let resolved = git(
+        source,
+        &["rev-parse", "--verify", &format!("{commit}^{{commit}}")],
+        cancel,
+    )
+    .await?;
+    ensure!(resolved == commit, "Retained commit is unavailable");
+    let branch = block
+        .split('\0')
+        .find_map(|field| field.strip_prefix("branch refs/heads/"))
+        .unwrap_or("")
+        .to_string();
+    let hash = format!(
+        "{:x}",
+        Sha256::digest(serde_json::to_vec(
+            &serde_json::json!({"record":record,"registration":block})
+        )?)
+    );
+    Ok(Recovery { record, commit, branch, hash, warning:"Creates a separate checkout from the retained commit. Missing uncommitted files are not reconstructed. The original branch, registration, index and recovery record remain intact for manual recovery.".into() })
+}
+pub async fn restore(
+    paths: &AppPaths,
+    source: &Path,
+    id: &str,
+    expected_hash: &str,
+    cancel: CancellationToken,
+) -> Result<Record> {
+    let review = recovery(paths, source, id, cancel.clone()).await?;
+    ensure!(
+        review.hash == expected_hash,
+        "Recovery state changed; inspect it again before restoring"
+    );
+    // Commit objects are immutable. Create from the reviewed commit, never a
+    // mutable branch name, and leave the original recovery evidence untouched.
+    create(paths, source, &review.commit, cancel).await
+}

native/core/tests/worktrees.rs

@@ -397,3 +397,102 @@ async fn worktree_inspection_rejects_detached_heads_symlinks_and_forged_paths()
     assert!(worktrees::list(&paths, &project).is_err());
     assert!(project.join("tracked.txt").exists());
 }
+
+#[tokio::test]
+async fn missing_checkout_rescue_retains_commits_index_and_original_registration() {
+    let root = tempfile::tempdir().unwrap();
+    let project = root.path().join("project");
+    repository(&project);
+    let paths = AppPaths::isolated(&root.path().join("profile")).unwrap();
+    Config::patch(&paths, json!({"trusted_workspaces":[project]})).unwrap();
+    let service = Service::open(paths.clone(), Some(project.clone())).unwrap();
+    let record = worktrees::create(&paths, &project, "HEAD", CancellationToken::new())
+        .await
+        .unwrap();
+    assert!(
+        worktrees::recovery(&paths, &project, &record.id, CancellationToken::new())
+            .await
+            .is_err()
+    );
+    fs::write(record.path.join("retained.txt"), "unmerged commit\n").unwrap();
+    git(&record.path, &["add", "."]);
+    git(&record.path, &["commit", "-qm", "Retained work"]);
+    let commit = git(&record.path, &["rev-parse", "HEAD"]);
+    fs::write(
+        record.path.join("tracked.txt"),
+        "staged recovery evidence\n",
+    )
+    .unwrap();
+    git(&record.path, &["add", "tracked.txt"]);
+    let index = git(
+        &record.path,
+        &["rev-parse", "--path-format=absolute", "--git-path", "index"],
+    );
+    let index_bytes = fs::read(&index).unwrap();
+    let record_file = paths
+        .data
+        .join("managed-worktrees/records")
+        .join(format!("{}.json", record.id));
+    let record_bytes = fs::read(&record_file).unwrap();
+    let saved = root.path().join("saved-checkout");
+    fs::rename(&record.path, &saved).unwrap();
+    git(
+        &project,
+        &["worktree", "lock", record.path.to_str().unwrap()],
+    );
+    assert!(
+        worktrees::recovery(&paths, &project, &record.id, CancellationToken::new())
+            .await
+            .unwrap_err()
+            .to_string()
+            .contains("locked")
+    );
+    git(
+        &project,
+        &["worktree", "unlock", record.path.to_str().unwrap()],
+    );
+    let review = operation(&service, "/api/worktrees/recovery", json!({"id":record.id}))
+        .await
+        .unwrap();
+    assert_eq!(review["commit"], commit);
+    assert_eq!(review["branch"], record.branch);
+    assert!(operation(
+        &service,
+        "/api/worktrees/restore",
+        json!({"id":record.id,"hash":"stale"})
+    )
+    .await
+    .unwrap_err()
+    .to_string()
+    .contains("changed"));
+    assert_eq!(worktrees::list(&paths, &project).unwrap().len(), 1);
+    let restored = operation(
+        &service,
+        "/api/worktrees/restore",
+        json!({"id":record.id,"hash":review["hash"]}),
+    )
+    .await
+    .unwrap();
+    let new_path = Path::new(restored["path"].as_str().unwrap());
+    assert_ne!(new_path, record.path);
+    assert_eq!(git(new_path, &["rev-parse", "HEAD"]), commit);
+    assert_eq!(
+        fs::read_to_string(new_path.join("retained.txt")).unwrap(),
+        "unmerged commit\n"
+    );
+    assert_eq!(
+        fs::read_to_string(new_path.join("tracked.txt")).unwrap(),
+        "committed\n"
+    );
+    assert_eq!(fs::read(index).unwrap(), index_bytes);
+    assert_eq!(fs::read(record_file).unwrap(), record_bytes);
+    assert_eq!(git(&project, &["rev-parse", &record.branch]), commit);
+    assert!(
+        git(&project, &["worktree", "list", "--porcelain"]).contains(record.path.to_str().unwrap())
+    );
+    assert_eq!(
+        fs::read_to_string(saved.join("tracked.txt")).unwrap(),
+        "staged recovery evidence\n"
+    );
+    service.engine.shutdown().await.unwrap();
+}

scripts/test-native-cli.mjs

@@ -2,7 +2,7 @@
 import assert from "node:assert/strict";
 import { spawn, execFileSync } from "node:child_process";
 import { createServer } from "node:http";
-import { mkdtemp, mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, writeFile, rm, rename } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -392,6 +392,18 @@ try {
   assert.equal(fixtureGit(["rev-parse",isolated.branch]).trim(),isolated.base_commit);
   checks.push("native worktree creation, inventory, trust, isolated model task, reviewed clean removal and preserved branch");
 
+  const missing=await cli(["worktree","--create"],0,{workspace:isolatedSource});
+  await rename(missing.path,path.join(scratch,"retained-missing-checkout"));
+  const recovery=await cli(["worktree","--recovery",missing.id],0,{workspace:isolatedSource});
+  assert.equal(recovery.commit,missing.base_commit);
+  assert.match((await cli(["worktree","--restore",missing.id,"--recovery-hash","stale"],1,{workspace:isolatedSource})).error,/changed/);
+  const rescued=await cli(["worktree","--restore",missing.id,"--recovery-hash",recovery.hash],0,{workspace:isolatedSource});
+  assert.notEqual(rescued.path,missing.path);
+  assert.equal(await readFile(path.join(rescued.path,"README.md"),"utf8"),"fixture-read-value committed\n");
+  assert.ok(fixtureGit(["worktree","list","--porcelain"]).includes(missing.path));
+  assert.equal(fixtureGit(["rev-parse",missing.branch]).trim(),missing.base_commit);
+  checks.push("missing worktree reviewed rescue with stale-hash rejection and original metadata retained");
+
   // Seed only this disposable, stopped profile. Recent-list limits must not hide
   // older IDs or force fetching multi-megabyte job results to resolve a prefix.
   const historyDb = new DatabaseSync(path.join(profile, "state/shadow-agent.db"));