setup: Merge git hooks into a bounded managed block instead of overwriting them

Every setup write — config assets and required git hooks alike — unlinked
the destination file before renaming the staged replacement over it. The
staging file already lives in the destination's directory, so the rename
alone is atomic; the unlink only opened a window where the file did not
exist, and on a rename failure the error path deleted the staging copy too,
leaving neither. This mattered once `.claude/settings.json` and
`.opencode/opencode.json` became merge targets holding user-owned keys that
setup cannot reconstruct. Both pre-deletes are dropped in favor of atomic
rename.

`sce setup --hooks` also replaced `pre-commit`, `commit-msg`, and
`post-commit` wholesale, destroying any hook a repository already ran
(husky, lefthook, hand-written). Each canonical hook payload is now
delimited by an SCE managed block marker pair. Install creates the full
script when no hook exists, replaces the block in place when one already
carries it, recognizes and replaces a legacy pre-marker SCE payload
wholesale, and otherwise appends the block after a foreign hook's content
so SCE always runs last. A last-effective-line heuristic reports an
advisory when a foreign hook's trailing zero-indent `exec`/`exit` would
make the appended block unreachable. `sce doctor` now classifies hook
content by managed-block currency instead of byte-exact comparison, so
foreign content around a current block does not read as drift.

Co-authored-by: SCE <sce@crocoder.dev>

Author: davidabram

cli/assets/hooks/commit-msg

@@ -1,6 +1,7 @@
 #!/bin/sh
 set -eu
 
+# >>> sce managed block (do not edit) >>>
 if ! command -v sce >/dev/null 2>&1; then
   # sce brand colors — only emit ANSI when stderr is a real terminal
   if [ -t 2 ]; then
@@ -25,4 +26,7 @@ if ! command -v sce >/dev/null 2>&1; then
   exit 0
 fi
 
-exec sce hooks commit-msg "$@"
+sce hooks commit-msg "$@"
+status=$?
+exit "$status"
+# <<< sce managed block <<<

cli/assets/hooks/post-commit

@@ -1,8 +1,7 @@
 #!/bin/sh
 set -eu
 
-remote_url="$(git remote get-url origin 2>/dev/null || true)"
-
+# >>> sce managed block (do not edit) >>>
 if ! command -v sce >/dev/null 2>&1; then
   # sce brand colors — only emit ANSI when stderr is a real terminal
   if [ -t 2 ]; then
@@ -27,8 +26,13 @@ if ! command -v sce >/dev/null 2>&1; then
   exit 0
 fi
 
+remote_url="$(git remote get-url origin 2>/dev/null || true)"
+
 if [ -n "$remote_url" ]; then
-  exec sce hooks post-commit --vcs git --remote-url "$remote_url" "$@"
+  sce hooks post-commit --vcs git --remote-url "$remote_url" "$@"
+else
+  sce hooks post-commit --vcs git "$@"
 fi
-
-exec sce hooks post-commit --vcs git "$@"
+status=$?
+exit "$status"
+# <<< sce managed block <<<

cli/assets/hooks/pre-commit

@@ -1,6 +1,7 @@
 #!/bin/sh
 set -eu
 
+# >>> sce managed block (do not edit) >>>
 if ! command -v sce >/dev/null 2>&1; then
   # sce brand colors — only emit ANSI when stderr is a real terminal
   if [ -t 2 ]; then
@@ -25,4 +26,7 @@ if ! command -v sce >/dev/null 2>&1; then
   exit 0
 fi
 
-exec sce hooks pre-commit "$@"
+sce hooks pre-commit "$@"
+status=$?
+exit "$status"
+# <<< sce managed block <<<

cli/src/services/doctor/inspect.rs

@@ -15,8 +15,9 @@ use crate::services::repository_identity::resolve::{
     resolve_repository_identity, RepositoryIdentitySource,
 };
 use crate::services::setup::{
-    config_merge, iter_embedded_assets_for_setup_target_with_selection, iter_required_hook_assets,
-    persisted_optional_workflows, repair_merge_target_asset, EmbeddedAsset, SetupTarget,
+    config_merge, hook_merge, iter_embedded_assets_for_setup_target_with_selection,
+    iter_required_hook_assets, persisted_optional_workflows, repair_merge_target_asset,
+    EmbeddedAsset, SetupTarget,
 };
 
 use super::types::{
@@ -318,17 +319,28 @@ fn inspect_hook_content_state_without_problem(
     };
 
     match fs::read(hook_path) {
-        Ok(bytes) => {
-            if bytes == expected_hook.bytes {
-                HookContentState::Current
-            } else {
-                HookContentState::Stale
-            }
-        }
+        Ok(bytes) => hook_managed_block_content_state(hook_name, &bytes, expected_hook.bytes),
         Err(_) => HookContentState::Unknown,
     }
 }
 
+/// Classifies a hook's on-disk bytes against the canonical template by SCE
+/// managed-block currency (merging the canonical block into `bytes` is a
+/// no-op) rather than whole-file equality, so foreign content a repository
+/// has appended around the block does not read as drift. An unbalanced or
+/// partial managed block is also reported `Stale`, since it needs the same
+/// `--fix` repair as a drifted one.
+fn hook_managed_block_content_state(
+    hook_name: &str,
+    bytes: &[u8],
+    canonical: &[u8],
+) -> HookContentState {
+    match hook_merge::merge_or_create_hook(Some(bytes), canonical, hook_name) {
+        Ok(merge) if merge.bytes == bytes => HookContentState::Current,
+        Ok(_) | Err(_) => HookContentState::Stale,
+    }
+}
+
 #[allow(dead_code)]
 fn inspect_repository_hooks(
     repository_root: &Path,
@@ -1568,13 +1580,7 @@ fn inspect_hook_content_state(
     };
 
     match fs::read(hook_path) {
-        Ok(bytes) => {
-            if bytes == expected_hook.bytes {
-                HookContentState::Current
-            } else {
-                HookContentState::Stale
-            }
-        }
+        Ok(bytes) => hook_managed_block_content_state(hook_name, &bytes, expected_hook.bytes),
         Err(error) => {
             problems.push(DoctorProblem {
                 kind: ProblemKind::HookReadFailed,
@@ -1602,8 +1608,9 @@ mod tests {
     use std::path::PathBuf;
 
     use super::{
-        collect_claude_integration_groups, collect_opencode_integration_groups,
-        collect_pi_integration_groups, inspect_claude_integration_health, IntegrationContentState,
+        collect_claude_integration_groups, collect_hook_file_health,
+        collect_opencode_integration_groups, collect_pi_integration_groups,
+        inspect_claude_integration_health, HookContentState, IntegrationContentState,
         IntegrationGroupHealth,
     };
     use crate::services::setup::OPTIONAL_WORKFLOWS;
@@ -1942,4 +1949,150 @@ mod tests {
 
         std::fs::remove_dir_all(&root).ok();
     }
+
+    fn canonical_pre_commit_bytes() -> &'static [u8] {
+        crate::services::setup::iter_required_hook_assets()
+            .find(|asset| asset.relative_path == "pre-commit")
+            .expect("embedded catalog carries pre-commit")
+            .bytes
+    }
+
+    #[cfg(unix)]
+    fn mark_executable(path: &std::path::Path) {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755))
+            .expect("mark hook executable");
+    }
+
+    #[test]
+    fn hook_with_foreign_content_and_current_block_reports_current() {
+        let dir = unique_temp_repository_root("hook-foreign-current");
+        let foreign_prefix = b"#!/bin/sh\necho husky-style-guard\n".to_vec();
+        let merge = crate::services::setup::hook_merge::merge_or_create_hook(
+            Some(&foreign_prefix),
+            canonical_pre_commit_bytes(),
+            "pre-commit",
+        )
+        .expect("merge over foreign hook should succeed");
+
+        let hook_path = dir.join("pre-commit");
+        std::fs::write(&hook_path, &merge.bytes).expect("write foreign-plus-block hook");
+        #[cfg(unix)]
+        mark_executable(&hook_path);
+
+        let health = collect_hook_file_health(&dir);
+        let pre_commit = health
+            .iter()
+            .find(|hook| hook.name == "pre-commit")
+            .expect("pre-commit health present");
+        assert_eq!(pre_commit.content_state, HookContentState::Current);
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    #[test]
+    fn hook_with_drifted_managed_block_reports_stale() {
+        let dir = unique_temp_repository_root("hook-drifted-stale");
+        let canonical_text =
+            String::from_utf8(canonical_pre_commit_bytes().to_vec()).expect("hook is utf8");
+        let drifted_text = canonical_text.replace(
+            "sce hooks pre-commit \"$@\"",
+            "sce hooks pre-commit \"$@\" # drifted",
+        );
+        assert_ne!(
+            drifted_text, canonical_text,
+            "drift fixture should actually differ from canonical"
+        );
+
+        let hook_path = dir.join("pre-commit");
+        std::fs::write(&hook_path, drifted_text.as_bytes()).expect("write drifted hook");
+        #[cfg(unix)]
+        mark_executable(&hook_path);
+
+        let health = collect_hook_file_health(&dir);
+        let pre_commit = health
+            .iter()
+            .find(|hook| hook.name == "pre-commit")
+            .expect("pre-commit health present");
+        assert_eq!(pre_commit.content_state, HookContentState::Stale);
+
+        std::fs::remove_dir_all(&dir).ok();
+    }
+
+    fn init_git_repo(label: &str) -> PathBuf {
+        let repo = unique_temp_repository_root(label);
+        let output = std::process::Command::new("git")
+            .args(["init", "-q"])
+            .current_dir(&repo)
+            .output()
+            .expect("git init should spawn");
+        assert!(
+            output.status.success(),
+            "git init failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        repo
+    }
+
+    #[test]
+    fn fix_repairs_drifted_hook_content_while_preserving_foreign_content() {
+        let repo = init_git_repo("hook-fix-repair");
+
+        let initial_outcome = crate::services::setup::install_required_git_hooks(&repo)
+            .expect("initial hook install should succeed");
+        let pre_commit_path = initial_outcome
+            .hook_results
+            .iter()
+            .find(|result| result.hook_name == "pre-commit")
+            .expect("pre-commit hook installed")
+            .hook_path
+            .clone();
+        let hooks_directory = pre_commit_path
+            .parent()
+            .expect("hook path has a parent directory")
+            .to_path_buf();
+
+        let foreign_prefix = b"#!/bin/sh\necho husky-style-guard\n".to_vec();
+        let foreign_plus_block = crate::services::setup::hook_merge::merge_or_create_hook(
+            Some(&foreign_prefix),
+            canonical_pre_commit_bytes(),
+            "pre-commit",
+        )
+        .expect("merge over foreign hook should succeed");
+        let drifted_text = String::from_utf8(foreign_plus_block.bytes.clone())
+            .expect("hook is utf8")
+            .replace(
+                "sce hooks pre-commit \"$@\"",
+                "sce hooks pre-commit \"$@\" # drifted",
+            );
+        std::fs::write(&pre_commit_path, drifted_text.as_bytes())
+            .expect("seed foreign-plus-drifted-block hook");
+        #[cfg(unix)]
+        mark_executable(&pre_commit_path);
+
+        let health_before = collect_hook_file_health(&hooks_directory);
+        let pre_commit_before = health_before
+            .iter()
+            .find(|hook| hook.name == "pre-commit")
+            .expect("pre-commit health present");
+        assert_eq!(pre_commit_before.content_state, HookContentState::Stale);
+
+        crate::services::setup::install_required_git_hooks(&repo)
+            .expect("'--fix' repair reuses the canonical setup hook installation");
+
+        let repaired_bytes = std::fs::read(&pre_commit_path).expect("read repaired hook");
+        assert!(
+            repaired_bytes.starts_with(&foreign_prefix),
+            "foreign content should survive the repair"
+        );
+
+        let health_after = collect_hook_file_health(&hooks_directory);
+        let pre_commit_after = health_after
+            .iter()
+            .find(|hook| hook.name == "pre-commit")
+            .expect("pre-commit health present");
+        assert_eq!(pre_commit_after.content_state, HookContentState::Current);
+
+        std::fs::remove_dir_all(&repo).ok();
+    }
 }

cli/src/services/hooks/lifecycle.rs

@@ -11,7 +11,7 @@ use crate::services::lifecycle::{
     RequiredHooksInstallOutcome, ServiceLifecycle, SetupOutcome,
 };
 use crate::services::setup::{
-    install_required_git_hooks, iter_required_hook_assets,
+    hook_merge, install_required_git_hooks, iter_required_hook_assets,
     RequiredHookInstallStatus as SetupRequiredHookInstallStatus,
     RequiredHooksInstallOutcome as SetupRequiredHooksInstallOutcome,
 };
@@ -298,10 +298,9 @@ fn inspect_hook_content_state(
 
     match fs::read(hook_path) {
         Ok(bytes) => {
-            if bytes == expected_hook.bytes {
-                HookContentState::Current
-            } else {
-                HookContentState::Stale
+            match hook_merge::merge_or_create_hook(Some(&bytes), expected_hook.bytes, hook_name) {
+                Ok(merge) if merge.bytes == bytes => HookContentState::Current,
+                Ok(_) | Err(_) => HookContentState::Stale,
             }
         }
         Err(error) => {
@@ -375,6 +374,7 @@ fn required_hooks_outcome_from_setup(
                             RequiredHookInstallStatus::Skipped
                         }
                     },
+                    unreachable_block_advisory: result.unreachable_block_advisory,
                 },
             )
             .collect(),

cli/src/services/lifecycle.rs

@@ -103,6 +103,7 @@ pub struct RequiredHookInstallResult {
     pub hook_name: String,
     pub hook_path: PathBuf,
     pub status: RequiredHookInstallStatus,
+    pub unreachable_block_advisory: bool,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]

cli/src/services/setup/command.rs

@@ -123,6 +123,7 @@ fn setup_required_hooks_outcome_from_lifecycle(
                     RequiredHookInstallStatus::Updated => setup::RequiredHookInstallStatus::Updated,
                     RequiredHookInstallStatus::Skipped => setup::RequiredHookInstallStatus::Skipped,
                 },
+                unreachable_block_advisory: result.unreachable_block_advisory,
             })
             .collect(),
     }