stacked_table: skip non-segment file names in heads/

Foreign files like AppleDouble `._*` (which appear when a macOS-created
archive is extracted on another system) or `.DS_Store` landing in
store/extra/heads made every metadata read fail until removed by hand;
a non-UTF8 name panicked outright. gc() already tolerates foreign
names in the table directory, and SimpleOpHeadsStore::get_op_heads
tolerates non-hex UTF-8 names in its own heads directory (though it
still errors on non-UTF8 ones). Apply the same idea to
get_head_tables(): ignore any entry whose name isn't exactly
SEGMENT_FILE_NAME_LENGTH ASCII hex characters, logging each skip at
warn level (visible under --debug/JJ_LOG), and never touch the
foreign file itself.

If every entry in heads/ turns out to be invalid, return the new
TableStoreError::NoValidHeads instead of silently manufacturing a
fresh empty table, which would otherwise mask lost head metadata. A
genuinely empty heads/ (no entries at all) keeps its existing
behavior.

Fixes #9775

Assisted-by: Claude:claude-fable-5

Author: Peter J McDade

CHANGELOG.md

@@ -62,6 +62,13 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   [#9711](https://github.com/jj-vcs/jj/issues/9711)
   [#8884](https://github.com/jj-vcs/jj/issues/8884)
 
+* A foreign file (e.g. `.DS_Store`, or an AppleDouble `._*` file that appears
+  when a macOS-created archive is extracted on another system) in
+  `store/extra/heads` is now ignored instead of breaking every command that
+  reads commit metadata, or panicking on a non-UTF8 file name. Skipped
+  entries are logged at `warn` level (visible with `--debug` or `JJ_LOG`).
+  [#9775](https://github.com/jj-vcs/jj/issues/9775)
+
 ## [0.44.0] - 2026-08-05
 
 ### Release highlights

lib/src/stacked_table.rs

@@ -413,6 +413,14 @@ pub enum TableStoreError {
         #[source]
         err: io::Error,
     },
+    #[error(
+        "Heads directory '{dir}' contains no valid head, {invalid_entries} invalid entries were \
+         skipped"
+    )]
+    NoValidHeads {
+        dir: PathBuf,
+        invalid_entries: usize,
+    },
     #[error("Failed to lock table store")]
     Lock(#[source] FileLockError),
 }
@@ -507,14 +515,28 @@ impl TableStore {
     }
 
     fn get_head_tables(&self) -> TableStoreResult<Vec<Arc<ReadonlyTable>>> {
+        let heads_dir = self.dir.join("heads");
         let mut tables = vec![];
-        for head_entry in
-            std::fs::read_dir(self.dir.join("heads")).map_err(TableStoreError::LoadHeads)?
-        {
-            let head_file_name = head_entry.map_err(TableStoreError::LoadHeads)?.file_name();
-            let table = self.load_table(head_file_name.to_str().unwrap().to_string())?;
+        let mut invalid_entries = 0;
+        for head_entry in std::fs::read_dir(&heads_dir).map_err(TableStoreError::LoadHeads)? {
+            let head_entry = head_entry.map_err(TableStoreError::LoadHeads)?;
+            let head_file_name = head_entry.file_name();
+            let Some(name) = head_file_name.to_str().filter(|name| {
+                name.len() == SEGMENT_FILE_NAME_LENGTH && hex_util::decode_hex(name).is_some()
+            }) else {
+                tracing::warn!(?head_file_name, "skipping invalid head file name");
+                invalid_entries += 1;
+                continue;
+            };
+            let table = self.load_table(name.to_string())?;
             tables.push(table);
         }
+        if tables.is_empty() && invalid_entries > 0 {
+            return Err(TableStoreError::NoValidHeads {
+                dir: heads_dir,
+                invalid_entries,
+            });
+        }
         Ok(tables)
     }
 
@@ -824,4 +846,95 @@ mod tests {
         assert_eq!(table.get_value(b"abc"), Some(b"value".as_slice()));
         Ok(())
     }
+
+    #[test]
+    fn stacked_table_store_ignores_foreign_head_files() -> TestResult {
+        let temp_dir = new_temp_dir();
+        let store = TableStore::init(temp_dir.path().to_path_buf(), 3);
+        let mut mut_table = store.get_head()?.start_mutation();
+        mut_table.add_entry(b"abc".to_vec(), b"value".to_vec());
+        store.save_table(mut_table)?;
+
+        let heads_dir = temp_dir.path().join("heads");
+        let ds_store = heads_dir.join(".DS_Store");
+        let apple_double = heads_dir.join(format!("._{}", "a".repeat(SEGMENT_FILE_NAME_LENGTH)));
+        // Right length, but not hex: exercises the hex-validity half of the
+        // predicate (the other junk names here are already rejected on
+        // length alone).
+        let right_length_non_hex = heads_dir.join("g".repeat(SEGMENT_FILE_NAME_LENGTH));
+        std::fs::write(&ds_store, "")?;
+        std::fs::write(&apple_double, "")?;
+        std::fs::write(&right_length_non_hex, "")?;
+
+        // Load a fresh store so we don't rely on the in-memory head cache.
+        let store = TableStore::load(temp_dir.path().to_path_buf(), 3);
+        let table = store.get_head()?;
+        assert_eq!(table.get_value(b"abc"), Some(b"value".as_slice()));
+
+        assert!(ds_store.exists());
+        assert!(apple_double.exists());
+        assert!(right_length_non_hex.exists());
+        Ok(())
+    }
+
+    #[test]
+    fn stacked_table_store_errors_when_all_heads_are_invalid() -> TestResult {
+        let temp_dir = new_temp_dir();
+        let store = TableStore::init(temp_dir.path().to_path_buf(), 3);
+        let mut mut_table = store.get_head()?.start_mutation();
+        mut_table.add_entry(b"abc".to_vec(), b"value".to_vec());
+        let table = store.save_table(mut_table)?;
+
+        // Replace the only (valid) head with junk, simulating a heads/
+        // directory that holds nothing but foreign files.
+        let heads_dir = temp_dir.path().join("heads");
+        std::fs::remove_file(heads_dir.join(table.name()))?;
+        std::fs::write(heads_dir.join(".DS_Store"), "")?;
+
+        let store = TableStore::load(temp_dir.path().to_path_buf(), 3);
+        assert!(store.get_head().is_err());
+        Ok(())
+    }
+
+    // APFS rejects non-UTF8 file names outright (the `fs::write` below would
+    // fail with EILSEQ), so this can only run where the filesystem allows
+    // them.
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn stacked_table_store_ignores_non_utf8_head_file_name() -> TestResult {
+        use std::ffi::OsString;
+        use std::os::unix::ffi::OsStringExt as _;
+
+        let temp_dir = new_temp_dir();
+        let store = TableStore::init(temp_dir.path().to_path_buf(), 3);
+        let mut mut_table = store.get_head()?.start_mutation();
+        mut_table.add_entry(b"abc".to_vec(), b"value".to_vec());
+        store.save_table(mut_table)?;
+
+        let heads_dir = temp_dir.path().join("heads");
+        let non_utf8_name = OsString::from_vec(vec![0x66, 0x6f, 0x80]);
+        std::fs::write(heads_dir.join(&non_utf8_name), "")?;
+
+        let store = TableStore::load(temp_dir.path().to_path_buf(), 3);
+        let table = store.get_head()?;
+        assert_eq!(table.get_value(b"abc"), Some(b"value".as_slice()));
+        Ok(())
+    }
+
+    #[test]
+    fn stacked_table_store_ignores_wrong_length_head_file_name() -> TestResult {
+        let temp_dir = new_temp_dir();
+        let store = TableStore::init(temp_dir.path().to_path_buf(), 3);
+        let mut mut_table = store.get_head()?.start_mutation();
+        mut_table.add_entry(b"abc".to_vec(), b"value".to_vec());
+        store.save_table(mut_table)?;
+
+        let heads_dir = temp_dir.path().join("heads");
+        std::fs::write(heads_dir.join("deadbeef"), "")?;
+
+        let store = TableStore::load(temp_dir.path().to_path_buf(), 3);
+        let table = store.get_head()?;
+        assert_eq!(table.get_value(b"abc"), Some(b"value".as_slice()));
+        Ok(())
+    }
 }