@primitive.ai/prim 0.1.0-alpha.93 → 0.1.0-alpha.94

package/dist/index.js

@@ -2,23 +2,30 @@
 import {
   bindRepository,
   bindRepositoryWithClient,
-  ensureEffectivePostCommitHook,
-  ensureEffectivePostRewriteHook,
-  ensurePostCommitHookAtPath,
-  ensurePostRewriteHookAtPath,
-  inspectEffectivePostCommitHook,
-  inspectEffectivePostRewriteHook,
+  ensureEffectiveGitHook,
+  ensureGitHookAtPath,
+  externalHookRemedy,
+  gitHooksMode,
+  hasCurrentHookBlock,
+  inspectEffectiveGitHook,
+  isLegacyOwnedGlobalHook,
+  isOwnedStandalonePreCommit,
   kickDaemonEnsure,
-  postCommitHookBlock,
-  postRewriteHookBlock,
   printJson,
+  projectGitHookTarget,
+  projectHooksDir,
   registerSkillCommands,
+  resolveEffectiveGitHook,
   resolveRepositoryBinding,
-  uninstallPostCommitHookAtPath,
-  uninstallPostRewriteHookAtPath,
-  uninstallProjectPostCommitHook,
-  uninstallProjectPostRewriteHook
-} from "./chunk-DCJN6LZH.js";
+  uninstallGitHookAtPath,
+  uninstallProjectGitHook
+} from "./chunk-WUXFLE7X.js";
+import {
+  POST_COMMIT_GRACE_MS,
+  clearHooksWired,
+  inspectPostCommitFiring,
+  recordHooksWired
+} from "./chunk-FXF4JWK2.js";
 import {
   requireDurableIngestAcknowledgement
 } from "./chunk-TYAHC25F.js";
@@ -78,6 +85,7 @@ import {
   isMoveIngestRequest,
   isRepoActiveForCapture,
   isValidRepoSyncId,
+  repoActiveFlag,
   repoSyncId,
   repositoryBindingState,
   setRepoActive,
@@ -101,6 +109,7 @@ import {
   terminalSafeLine
 } from "./chunk-G2VMA2QO.js";
 import {
+  MANAGED_GIT_HOOK_NAMES,
   assertOwnedHookRuntime,
   atomicWrite,
   binFile,
@@ -110,15 +119,16 @@ import {
   entryHasCommand,
   hookCommandResolutions,
   hookRuntimePaths,
+  inspectGitHookEntrypoint,
   inspectHookRuntime,
   inspectHookRuntimeResolutions,
   inspectHookRuntimeResolutions2,
   makeRegistration,
+  managedHookBlock,
   packageRoot,
   packageVersion,
   performStatus,
   performStatus2,
-  pinnedHookCommand,
   pinnedNpxArgs,
   projectRoot,
   readSettings,
@@ -129,7 +139,7 @@ import {
   stableNodePath,
   stageHookRuntime,
   stripCommand
-} from "./chunk-X64HTHUF.js";
+} from "./chunk-AXQQMX2U.js";
 import {
   canonicalGitRoot,
   canonicalRepositoryPath,
@@ -157,7 +167,7 @@ import {
 
 // src/index.ts
 import { readFileSync as readFileSync10 } from "fs";
-import { dirname as dirname7, resolve as resolve4 } from "path";
+import { dirname as dirname6, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 import updateNotifier from "update-notifier";
@@ -1352,8 +1362,8 @@ import {
   writeFileSync
 } from "fs";
 import { homedir } from "os";
-import { dirname, join, resolve } from "path";
-import { Option } from "commander";
+import { join, resolve } from "path";
+import { Argument, Option } from "commander";
 var PRE_COMMIT = { hookName: "pre-commit", binName: "prim-pre-commit" };
 var POST_COMMIT = { hookName: "post-commit", binName: "prim-post-commit" };
 var POST_REWRITE = { hookName: "post-rewrite", binName: "prim-post-rewrite" };
@@ -1369,84 +1379,15 @@ var PRIM_BLOCK_START = blockMarkers(PRE_COMMIT).start;
 var PRIM_BLOCK_END = blockMarkers(PRE_COMMIT).end;
 var PRIM_MANAGED_MARK = "prim-managed-hook";
 var PRIM_CREATED_MARK = "prim-created-hook";
-function hookShim(binName) {
-  return `{ ${pinnedHookCommand(binName)}; } || true`;
-}
-function gatedShim(binName) {
-  return `if [ "$(git config --get prim.active 2>/dev/null)" = "true" ]; then
-${hookShim(binName)}
-fi`;
-}
-function dotGitScript(spec) {
-  return `#!/bin/sh
-# prim ${spec.hookName} hook \u2014 installed by: prim hooks install (${PRIM_MANAGED_MARK})
-
-${hookShim(spec.binName)}
-`;
-}
-function isOwnedStandalonePreCommit(content) {
-  if (content === "#!/bin/sh\nprim-pre-commit\n") return true;
-  const prefix = `#!/bin/sh
-# prim pre-commit hook \u2014 installed by: prim hooks install (${PRIM_MANAGED_MARK})
-
-`;
-  const suffix = "; } || true\n";
-  if (!content.startsWith(prefix) || !content.endsWith(suffix)) return false;
-  const body = content.slice(prefix.length, -suffix.length);
-  if (!body.startsWith("{ ") || /[\r\n]/u.test(body)) return false;
-  return commandMatchesBin(body.slice(2), PRE_COMMIT.binName);
-}
-function huskyBlock(spec) {
-  if (spec.hookName === POST_COMMIT.hookName) return postCommitHookBlock();
-  if (spec.hookName === POST_REWRITE.hookName) return postRewriteHookBlock();
-  const { start, end } = blockMarkers(spec);
-  return `${start}
-${hookShim(spec.binName)}
-${end}`;
-}
-function gatedBlock(spec) {
-  if (spec.hookName === POST_COMMIT.hookName) return postCommitHookBlock();
-  if (spec.hookName === POST_REWRITE.hookName) return postRewriteHookBlock();
-  const { start, end } = blockMarkers(spec);
-  return `${start}
-${gatedShim(spec.binName)}
-${end}`;
-}
-function primBlockRange(existing, spec) {
-  const { start, end } = blockMarkers(spec);
-  const starts = existing.split(start).length - 1;
-  const ends = existing.split(end).length - 1;
-  if (starts === 0 && ends === 0) return null;
-  const from = existing.indexOf(start);
-  const endAt = existing.indexOf(end);
-  if (starts !== 1 || ends !== 1 || endAt < from) {
-    throw new Error(`malformed Prim hook markers for ${spec.hookName}`);
-  }
-  return { start: from, through: endAt + end.length };
-}
-function mergePrimBlock(hookPath, block, spec) {
-  if (existsSync2(hookPath)) {
-    const existing = readFileSync2(hookPath, "utf-8");
-    const range = primBlockRange(existing, spec);
-    if (range) {
-      const refreshed = existing.slice(0, range.start) + block + existing.slice(range.through);
-      if (refreshed === existing) return false;
-      writeFileSync(hookPath, refreshed, { mode: 493 });
-      return true;
-    }
-    if (containsPrimHook(existing, spec.binName)) return false;
-    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-    writeFileSync(hookPath, `${existing}${separator}${block}
-`, { mode: 493 });
+function stageGitHookRuntime() {
+  try {
+    stageHookRuntime();
     return true;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error(`[prim] git hooks stay inert until the hook runtime is staged: ${detail}`);
+    return false;
   }
-  mkdirSync(dirname(hookPath), { recursive: true });
-  writeFileSync(hookPath, `#!/bin/sh
-# ${PRIM_CREATED_MARK}
-
-${block}
-`, { mode: 493 });
-  return true;
 }
 function getGitRoot() {
   const root = gitToplevel();
@@ -1473,52 +1414,6 @@ function detectHusky(gitRoot) {
   }
   return false;
 }
-function containsPrimHook(content, binName = PRE_COMMIT.binName) {
-  return content.includes(binName);
-}
-function installToHusky(gitRoot, spec = PRE_COMMIT) {
-  const hookPath = resolve(gitRoot, ".husky", spec.hookName);
-  const existed = existsSync2(hookPath);
-  const wrote = mergePrimBlock(hookPath, huskyBlock(spec), spec);
-  if (!wrote) {
-    console.log(`Prim ${spec.hookName} hook is already installed in .husky/${spec.hookName}.`);
-  } else if (existed) {
-    console.log(`Appended prim hook block to .husky/${spec.hookName}.`);
-  } else {
-    console.log(`Created .husky/${spec.hookName} with prim hook block.`);
-  }
-}
-function installToDotGit(gitRoot, spec = PRE_COMMIT) {
-  const hooksDir = projectHooksDir(gitRoot);
-  const hookPath = resolve(hooksDir, spec.hookName);
-  if (!existsSync2(hooksDir)) {
-    mkdirSync(hooksDir, { recursive: true });
-  }
-  if (existsSync2(hookPath)) {
-    const existing = readFileSync2(hookPath, "utf-8");
-    if (containsPrimHook(existing, spec.binName)) {
-      console.log(`Prim ${spec.hookName} hook is already installed at ${hookPath}.`);
-      return;
-    }
-    console.log(`A ${spec.hookName} hook already exists at ${hookPath}.`);
-    console.log("To replace it, run: prim hooks uninstall && prim hooks install");
-    return;
-  }
-  writeFileSync(hookPath, dotGitScript(spec), { mode: 493 });
-  console.log(`Installed ${spec.hookName} hook at ${hookPath}`);
-}
-function projectHooksDir(gitRoot) {
-  const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
-    cwd: gitRoot,
-    encoding: "utf-8",
-    stdio: ["ignore", "pipe", "ignore"],
-    timeout: GIT_TIMEOUT_MS
-  }).trim();
-  if (commonDir === "") {
-    throw new Error("git returned an empty common directory");
-  }
-  return resolve(gitRoot, commonDir, "hooks");
-}
 var PRIM_GIT_HOOKS_DIR = join(primConfigDirectory(), "git-hooks");
 function expandTilde(p) {
   return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
@@ -1557,21 +1452,17 @@ var PASSTHROUGH_HOOKS = [
   //  with a query protocol, not a lifecycle event, so a bare exec stub is wrong.)
 ];
 function globalHookScript(spec) {
-  const chainExit = spec.hookName === PRE_COMMIT.hookName ? "|| exit $?" : "|| true";
-  const managedBlock = spec.hookName === POST_COMMIT.hookName ? postCommitHookBlock() : spec.hookName === POST_REWRITE.hookName ? postRewriteHookBlock() : void 0;
-  const invocation = managedBlock ?? gatedShim(spec.binName);
-  const managedRepoGuard = managedBlock ? ` && ! grep -Fq '${blockMarkers(spec).start.slice(0, -3)}'">>>" "$repo_hook" 2>/dev/null` : "";
-  const beforeComments = managedBlock ? `${invocation}
-` : "";
-  const afterComments = managedBlock ? "" : `${invocation}
-`;
+  const preCommit = spec.hookName === PRE_COMMIT.hookName;
+  const chainExit = preCommit ? "|| exit $?" : "|| true";
+  const managedRepoGuard = preCommit ? "" : ` && ! grep -Fq '${blockMarkers(spec).start.slice(0, -3)}'">>>" "$repo_hook" 2>/dev/null`;
   return `#!/bin/sh
-${beforeComments}# prim global ${spec.hookName} hook (core.hooksPath) \u2014 managed by prim; do not edit.
+${managedHookBlock(spec.hookName)}
+# prim global ${spec.hookName} hook (core.hooksPath) \u2014 managed by prim; do not edit.
 # Install/uninstall: prim hooks install|uninstall --scope user
 # Runs prim only where activated \u2014 'prim enable' (this repo) or
 # 'git config --global prim.active true' (every repo). Chains to the repo's own
 # hook regardless, so inactive repos are unaffected.
-${afterComments}common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || exit 0
+common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || exit 0
 repo_hook="$common_dir/hooks/${spec.hookName}"
 if [ -x "$repo_hook" ] && ! grep -q '${PRIM_MANAGED_MARK}' "$repo_hook" 2>/dev/null${managedRepoGuard}; then
   "$repo_hook" "$@" ${chainExit}
@@ -1596,30 +1487,12 @@ function expectedOwnedHookContent(hookName) {
   }
   return null;
 }
-var PINNED_PACKAGE_VERSION_RE = /@primitive\.ai\/prim@[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?/gu;
-function normalizeOwnedGlobalHook(content, hookName) {
-  if (hookName === PRE_COMMIT.hookName) {
-    const lines = content.split("\n");
-    const invocationIndexes = lines.flatMap(
-      (line2, index) => line2.startsWith("{ ") && line2.endsWith("; } || true") ? [index] : []
-    );
-    if (invocationIndexes.length !== 1) return null;
-    const invocationIndex = invocationIndexes[0];
-    const line = lines[invocationIndex];
-    const command = line.slice(2, -"; } || true".length);
-    if (!commandMatchesBin(command, PRE_COMMIT.binName)) return null;
-    lines[invocationIndex] = "{ <recognized Prim pre-commit invocation>; } || true";
-    return lines.join("\n");
-  }
-  return content.replace(PINNED_PACKAGE_VERSION_RE, "@primitive.ai/prim@<version>");
-}
 function isExpectedOwnedGlobalHook(content, hookName) {
   const expected = expectedOwnedHookContent(hookName);
   if (expected === null) return false;
   if (content === expected) return true;
-  const normalized = normalizeOwnedGlobalHook(content, hookName);
-  const normalizedExpected = normalizeOwnedGlobalHook(expected, hookName);
-  return normalized !== null && normalized === normalizedExpected;
+  const managed = HOOKS.find((spec) => spec.hookName === hookName);
+  return managed !== void 0 && isLegacyOwnedGlobalHook(content, managed.hookName);
 }
 function lstatIfPresent(path) {
   try {
@@ -1654,6 +1527,12 @@ function assertOwnedHooksDirectorySafeToRemove() {
   return entries;
 }
 function writeOwnHooks() {
+  if (inspectGitHookEntrypoint() !== "ready") {
+    console.error(
+      `[prim] did not write prim's global hooks in ${PRIM_GIT_HOOKS_DIR}: the hook runtime they run is not staged yet. Run \`prim setup\` (or an agent install such as \`prim claude install\`) first, then retry.`
+    );
+    return false;
+  }
   if (!existsSync2(PRIM_GIT_HOOKS_DIR)) {
     mkdirSync(PRIM_GIT_HOOKS_DIR, { recursive: true });
   }
@@ -1665,47 +1544,17 @@ function writeOwnHooks() {
   for (const name of PASSTHROUGH_HOOKS) {
     writeFileSync(resolve(PRIM_GIT_HOOKS_DIR, name), passThroughScript(name), { mode: 493 });
   }
+  return true;
 }
 function refreshOwnedGlobalHooks() {
   if (!isOurHooksDir(gitConfigGet("--global"))) return false;
-  writeOwnHooks();
-  return true;
+  return writeOwnHooks();
 }
 function appendPrimBlock(hookPath, spec) {
-  if (spec.hookName === POST_COMMIT.hookName) {
-    ensurePostCommitHookAtPath(hookPath);
-    return;
-  }
-  if (spec.hookName === POST_REWRITE.hookName) {
-    ensurePostRewriteHookAtPath(hookPath);
-    return;
-  }
-  mergePrimBlock(hookPath, gatedBlock(spec), spec);
+  ensureGitHookAtPath(spec.hookName, hookPath);
 }
 function stripPrimBlock(hookPath, spec) {
-  if (spec.hookName === POST_COMMIT.hookName) {
-    uninstallPostCommitHookAtPath(hookPath);
-    return;
-  }
-  if (spec.hookName === POST_REWRITE.hookName) {
-    uninstallPostRewriteHookAtPath(hookPath);
-    return;
-  }
-  if (!existsSync2(hookPath)) return;
-  const existing = readFileSync2(hookPath, "utf-8");
-  const primCreated = existing.includes(PRIM_CREATED_MARK);
-  const range = primBlockRange(existing, spec);
-  if (!range) return;
-  const out = (existing.slice(0, range.start) + existing.slice(range.through)).replace(
-    /\n{2,}$/,
-    "\n"
-  );
-  const remainder = out.replaceAll("#!/bin/sh", "").replaceAll(`# ${PRIM_CREATED_MARK}`, "").trim();
-  if (primCreated && remainder === "") {
-    unlinkSync(hookPath);
-    return;
-  }
-  writeFileSync(hookPath, out, { mode: 493 });
+  uninstallGitHookAtPath(spec.hookName, hookPath);
 }
 function planPreCommitRemoval(hookPath, options) {
   if (!existsSync2(hookPath)) return { path: hookPath, action: "missing" };
@@ -1713,7 +1562,8 @@ function planPreCommitRemoval(hookPath, options) {
   if (options.allowOwnedStandalone && isOwnedStandalonePreCommit(existing)) {
     return { path: hookPath, action: "remove-owned-file" };
   }
-  if (primBlockRange(existing, PRE_COMMIT)) {
+  const { start, end } = blockMarkers(PRE_COMMIT);
+  if (existing.includes(start) || existing.includes(end)) {
     return { path: hookPath, action: "strip-block" };
   }
   if (existing.includes(PRE_COMMIT.binName) || existing.includes(PRIM_MANAGED_MARK) || existing.includes(PRIM_CREATED_MARK)) {
@@ -1723,79 +1573,172 @@ function planPreCommitRemoval(hookPath, options) {
   }
   return { path: hookPath, action: "leave-foreign" };
 }
-function applyPreCommitRemoval(plan) {
-  if (plan.action === "remove-owned-file") {
-    unlinkSync(plan.path);
-    console.log(`Removed pre-commit hook at ${plan.path}`);
-  } else if (plan.action === "strip-block") {
-    stripPrimBlock(plan.path, PRE_COMMIT);
-    console.log(`Removed the Prim pre-commit block from ${plan.path}.`);
-  } else if (plan.action === "leave-foreign") {
+function applyPreCommitRemoval(plan, husky) {
+  if (plan.action === "missing") return;
+  if (plan.action === "leave-foreign") {
     console.log(`Left pre-commit hook at ${plan.path} untouched (not a Prim hook).`);
+    return;
   }
+  const result = uninstallGitHookAtPath(PRE_COMMIT.hookName, plan.path, { husky });
+  console.log(
+    result.removedFile ? `Removed pre-commit hook at ${plan.path}` : `Removed the Prim pre-commit block from ${plan.path}.`
+  );
 }
 function uninstallProjectHooks(gitRoot) {
-  const plans = [
-    planPreCommitRemoval(resolve(projectHooksDir(gitRoot), PRE_COMMIT.hookName), {
+  const configured = projectGitHookTarget(PRE_COMMIT.hookName, gitRoot);
+  const destinations = [
+    {
+      path: resolve(projectHooksDir(gitRoot), PRE_COMMIT.hookName),
+      husky: false,
       allowOwnedStandalone: true
-    }),
-    planPreCommitRemoval(resolve(gitRoot, ".husky", PRE_COMMIT.hookName), {
+    },
+    {
+      path: resolve(gitRoot, ".husky", PRE_COMMIT.hookName),
+      husky: true,
       allowOwnedStandalone: false
-    })
-  ];
-  for (const plan of plans) applyPreCommitRemoval(plan);
-  for (const [hookName, uninstall] of [
-    [POST_COMMIT.hookName, uninstallProjectPostCommitHook],
-    [POST_REWRITE.hookName, uninstallProjectPostRewriteHook]
-  ]) {
-    const result = uninstall(gitRoot);
-    if (!result.changed) {
-      console.log(`No Prim ${hookName} block found at ${result.path}.`);
+    },
+    // A shared hooks dir is never stripped on this repository's behalf.
+    ...configured.location === "external" ? [] : [
+      {
+        path: configured.hookPath,
+        husky: configured.kind === "husky_v9",
+        allowOwnedStandalone: false
+      }
+    ]
+  ].filter(
+    (destination, index, all) => all.findIndex((other) => other.path === destination.path) === index
+  );
+  const plans = destinations.map(({ path, husky, allowOwnedStandalone }) => ({
+    plan: planPreCommitRemoval(path, { allowOwnedStandalone }),
+    husky
+  }));
+  for (const { plan, husky } of plans) applyPreCommitRemoval(plan, husky);
+  for (const spec of [POST_COMMIT, POST_REWRITE]) {
+    const result = uninstallProjectGitHook(spec.hookName, gitRoot);
+    if (result.skipped === "external") {
+      console.log(
+        `Left ${result.path} alone: it is outside this repository, and other repositories may run it.`
+      );
+    } else if (!result.changed) {
+      console.log(`No Prim ${spec.hookName} block found at ${result.path}.`);
     } else if (result.removedFile) {
-      console.log(`Removed Prim-created ${hookName} hook at ${result.path}.`);
+      console.log(`Removed Prim-created ${spec.hookName} hook at ${result.path}.`);
     } else {
-      console.log(`Removed the Prim ${hookName} block from ${result.path}.`);
+      console.log(`Removed the Prim ${spec.hookName} block from ${result.path}.`);
     }
   }
 }
-function installGlobalHooks(opts = {}) {
+function globalHooksPathIsPrims() {
+  return isOurHooksDir(gitConfigGet("--global"));
+}
+var EXIT_GLOBAL_HOOKS_NOT_INSTALLED = 3;
+var INSTALLED_OUTCOMES = /* @__PURE__ */ new Set([
+  "installed",
+  "refreshed",
+  "added",
+  "present"
+]);
+function planGlobalHooks(opts = {}) {
   const global = gitConfigGet("--global");
-  if (global === "") {
-    const system = gitConfigGet("--system");
-    if (system !== "" && !isOurHooksDir(system)) {
-      if (!opts.force) {
+  if (gitHooksMode({ global: true }) === "manual") return { action: "manual", global };
+  if (isOurHooksDir(global)) return { action: "refresh" };
+  if (global !== "") {
+    const dir = expandTilde(global);
+    return HOOKS.every((spec) => hasCurrentHookBlock(spec.hookName, resolve(dir, spec.hookName))) ? { action: "present_in_dir", global } : { action: "add_to_dir", global };
+  }
+  const system = gitConfigGet("--system");
+  if (system !== "" && !isOurHooksDir(system)) {
+    return opts.force ? { action: "set_pointer", overridesSystem: system } : { action: "system_declined", system };
+  }
+  return { action: "set_pointer" };
+}
+function planIsMachineWide(plan) {
+  return plan.action === "set_pointer" || plan.action === "add_to_dir";
+}
+function installGlobalHooks(opts = {}) {
+  const plan = planGlobalHooks(opts);
+  switch (plan.action) {
+    case "manual":
+      console.error(
+        isOurHooksDir(plan.global) ? `[prim] prim.gitHooks=manual: left hook files alone, but prim's global hooks in ${PRIM_GIT_HOOKS_DIR} are still active. Run \`prim hooks uninstall --scope user\` to stop them.` : "[prim] prim.gitHooks=manual: left hook files and core.hooksPath untouched. Wire prim yourself with `prim hooks snippet <hook>`."
+      );
+      return "manual";
+    case "system_declined":
+      console.error(
+        `[prim] system core.hooksPath is set to ${plan.system}; a --global set would override it, and prim chains only to .git/hooks (not a system dir), so those hooks would stop firing. Skipped. Either place \`prim hooks snippet <hook>\` in ${plan.system} yourself, or override it with \`prim hooks install --scope user --global-hooks-path --force\`. It changes every repository's hooks: an agent must ask the user before running it.`
+      );
+      return "system_declined";
+    case "refresh":
+      stageGitHookRuntime();
+      if (!writeOwnHooks()) return "runtime_missing";
+      console.log(
+        `Prim global git hooks already active (${PRIM_GIT_HOOKS_DIR}); refreshed scripts.`
+      );
+      return "refreshed";
+    case "present_in_dir":
+      if (!hookRuntimeReady()) {
         console.error(
-          `[prim] system core.hooksPath is set to ${system}; a --global set would override it, and prim chains only to .git/hooks (not a system dir), so those hooks would stop firing. Skipping \u2014 re-run with --force to override, or run per-repo \`prim hooks install\`.`
+          `[prim] prim's hooks are in ${plan.global}, but the hook runtime they run is not staged, so they do nothing yet. Run \`prim setup\` (or an agent install such as \`prim claude install\`), then retry.`
         );
-        return false;
+        return "runtime_missing";
       }
-      console.error(
-        `[prim] --force: overriding system core.hooksPath ${system}; its hooks will no longer fire (prim chains only to .git/hooks).`
-      );
+      console.log(`Prim hooks already present in core.hooksPath dir ${plan.global}.`);
+      return "present";
+    case "set_pointer":
+    case "add_to_dir":
+      break;
+  }
+  if (!hookRuntimeReady()) {
+    console.error(
+      `[prim] did not install prim's global hooks: the hook runtime they run is not staged yet. Run \`prim setup\` (or an agent install such as \`prim claude install\`) first, then retry.`
+    );
+    return "runtime_missing";
+  }
+  if (!opts.machineWide) {
+    console.error(
+      plan.action === "set_pointer" ? plan.overridesSystem !== void 0 ? `[prim] Left git's global hooks alone: setting core.hooksPath would override the system core.hooksPath ${plan.overridesSystem} (its hooks stop firing) and route every repository's hooks through prim. To do that, run \`prim hooks install --scope user --global-hooks-path --force\`. It changes every repository's hooks: an agent must ask the user before running it.` : "[prim] Left git's global hooks alone: setting core.hooksPath would route every repository's hooks through prim. `prim enable` wires each repository you activate. To route every repository through prim instead, run `prim hooks install --scope user --global-hooks-path`. It changes every repository's hooks: an agent must ask the user before running it." : `[prim] Left the hooks in ${plan.global} alone: every repository runs them, so prim edits them only with consent. Repositories that run hooks from there lack prim's hooks until you run \`prim hooks install --scope user --global-hooks-path\`. It changes every repository's hooks: an agent must ask the user before running it.`
+    );
+    return "not_requested";
+  }
+  stageGitHookRuntime();
+  if (plan.action === "add_to_dir") {
+    const dir = expandTilde(plan.global);
+    for (const spec of HOOKS) {
+      appendPrimBlock(resolve(dir, spec.hookName), spec);
     }
-    writeOwnHooks();
-    execFileSync("git", ["config", "--global", "core.hooksPath", PRIM_GIT_HOOKS_DIR], {
-      stdio: ["ignore", "ignore", "pipe"],
-      timeout: GIT_TIMEOUT_MS
-    });
     console.log(
-      `Installed prim global git hooks; set core.hooksPath to ${PRIM_GIT_HOOKS_DIR}. Repos are opt-in: run \`prim enable\` in each repo to capture, or \`git config --global prim.active true\` for all.`
+      `Added prim hooks into existing core.hooksPath dir ${plan.global} (pointer unchanged).`
     );
-    return true;
+    return "added";
   }
-  if (isOurHooksDir(global)) {
-    writeOwnHooks();
-    console.log(`Prim global git hooks already active (${PRIM_GIT_HOOKS_DIR}); refreshed scripts.`);
-    return true;
-  }
-  const dir = expandTilde(global);
-  for (const spec of HOOKS) {
-    appendPrimBlock(resolve(dir, spec.hookName), spec);
+  if (plan.overridesSystem !== void 0) {
+    console.error(
+      `[prim] --force: overriding system core.hooksPath ${plan.overridesSystem}; its hooks will no longer fire (prim chains only to .git/hooks).`
+    );
   }
+  if (!writeOwnHooks()) return "runtime_missing";
+  execFileSync("git", ["config", "--global", "core.hooksPath", PRIM_GIT_HOOKS_DIR], {
+    stdio: ["ignore", "ignore", "pipe"],
+    timeout: GIT_TIMEOUT_MS
+  });
   console.log(
-    `Appended prim hooks into existing core.hooksPath dir ${global} (pointer unchanged).`
+    `Installed prim global git hooks; set core.hooksPath to ${PRIM_GIT_HOOKS_DIR}. Repos are opt-in: run \`prim enable\` in each repo to capture, or \`git config --global prim.active true\` for all.`
+  );
+  return "installed";
+}
+function hookRuntimeReady() {
+  if (inspectGitHookEntrypoint() === "ready") return true;
+  stageGitHookRuntime();
+  return inspectGitHookEntrypoint() === "ready";
+}
+async function consentToMachineWideHooks(plan, flag, nonInteractive) {
+  if (!planIsMachineWide(plan) || !hookRuntimeReady()) return false;
+  if (flag) return true;
+  if (nonInteractive || !process.stdin.isTTY) return false;
+  return askConfirmation(
+    plan.action === "set_pointer" ? plan.overridesSystem !== void 0 ? `Set git's global core.hooksPath so every repository's hooks run through prim? This overrides the system core.hooksPath ${plan.overridesSystem}, whose hooks stop firing.` : "Set git's global core.hooksPath so every repository's hooks run through prim?" : `Add prim's hooks to ${plan.action === "add_to_dir" ? plan.global : "the global hooks dir"}, which every repository runs?`,
+    process.stderr
   );
-  return true;
 }
 function uninstallGlobalHooks() {
   const global = gitConfigGet("--global");
@@ -1819,26 +1762,75 @@ function uninstallGlobalHooks() {
   }
   console.log("No prim global git hooks found.");
 }
+function reportInstall(result, gitRoot) {
+  const { hookName, path } = result;
+  switch (result.outcome) {
+    case "created":
+      console.log(`Installed prim ${hookName} hook at ${path}.`);
+      return;
+    case "updated":
+      console.log(`Updated prim ${hookName} hook at ${path}.`);
+      return;
+    case "unchanged":
+      console.log(`Already current: prim ${hookName} hook at ${path}.`);
+      return;
+    case "external":
+      console.error(
+        `[prim] ${hookName}: Git runs this repository's hooks from ${path}, outside the repository, so prim left it alone. ${externalHookRemedy(hookName, gitRoot)}.`
+      );
+      return;
+    case "kept":
+      console.error(
+        `[prim] ${hookName}: kept the working pre-v1 prim block at ${path}, outside the repository; it still captures. To upgrade it, ${externalHookRemedy(hookName, gitRoot)}.`
+      );
+      return;
+    case "runtime_missing":
+      console.error(
+        `[prim] ${hookName}: kept the existing prim hook at ${path}; it still works, and its replacement would stay inert until the hook runtime is staged.`
+      );
+      return;
+    default:
+      console.error(`[prim] ${hookName}: left ${path} as it was (${result.outcome}).`);
+  }
+}
 function installHooks(gitRoot, target) {
-  if (target === "husky") {
-    installToHusky(gitRoot, PRE_COMMIT);
-  } else {
-    installToDotGit(gitRoot, PRE_COMMIT);
+  let changed = false;
+  if (target !== "effective") {
+    const effectiveDir = resolveEffectiveGitHook(PRE_COMMIT.hookName, gitRoot).hooksDir;
+    const chosenDir = target === "husky" ? resolve(gitRoot, ".husky") : projectHooksDir(gitRoot);
+    if (resolve(effectiveDir) !== chosenDir && resolve(effectiveDir, "..") !== chosenDir) {
+      console.error(
+        `[prim] note: Git runs this repository's hooks from ${effectiveDir}; hooks in ${chosenDir} will not fire unless that directory chains to them.`
+      );
+    }
   }
-  const postCommit = ensureEffectivePostCommitHook(gitRoot);
-  console.log(
-    `${postCommit.changed ? "Installed" : "Refreshed"} effective post-commit hook at ${postCommit.path}.`
-  );
-  try {
-    const postRewrite = ensureEffectivePostRewriteHook(gitRoot);
-    console.log(
-      `${postRewrite.changed ? "Installed" : "Refreshed"} effective post-rewrite hook at ${postRewrite.path}.`
-    );
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    console.error(`[prim] post-rewrite hook coverage is degraded: ${detail}`);
+  for (const spec of HOOKS) {
+    try {
+      const result = target === "effective" ? ensureEffectiveGitHook(spec.hookName, gitRoot, { context: "explicit" }) : ensureGitHookAtPath(
+        spec.hookName,
+        target === "husky" ? resolve(gitRoot, ".husky", spec.hookName) : resolve(projectHooksDir(gitRoot), spec.hookName),
+        { husky: target === "husky" }
+      );
+      reportInstall(result, gitRoot);
+      if (spec === POST_COMMIT) changed ||= result.changed;
+      if (spec === POST_COMMIT && result.outcome === "external") process.exitCode = 1;
+    } catch (error) {
+      if (spec === POST_COMMIT) throw error;
+      const detail = error instanceof Error ? error.message : String(error);
+      console.error(
+        `[prim] ${spec.hookName} hook coverage is degraded: ${detail}. To wire it by hand, run \`prim hooks snippet ${spec.hookName}\`.`
+      );
+    }
+  }
+  if (repoActiveFlag(gitRoot) === "true") {
+    recordHooksWired(gitRoot, { onlyIfAbsent: !changed });
   }
 }
+function printManualNote(gitRoot) {
+  console.error(
+    `[prim] prim.gitHooks=manual: left the hook files in ${gitRoot} untouched. Wire each hook with \`prim hooks snippet <hook>\`; \`prim doctor\` reports what it finds.`
+  );
+}
 function registerHooksCommands(program2) {
   const hooks = program2.command("hooks").description("Manage git hooks");
   hooks.command("install").description(
@@ -1851,20 +1843,47 @@ function registerHooksCommands(program2) {
   ).addOption(
     new Option(
       "--scope <scope>",
-      "project (default, this repo) or user (a global core.hooksPath capturing every repo)"
+      "project (default, this repo) or user (prim's global hooks; needs --global-hooks-path or a yes at a terminal to change git's global config)"
     ).choices(["project", "user"])
-  ).option("--force", "with --scope user, override a system-level core.hooksPath").action(
+  ).option("--force", "with --scope user, override a system-level core.hooksPath").option(
+    "--global-hooks-path",
+    "with --scope user, change git's global hooks so every repository runs prim's hooks"
+  ).action(
     async (opts, command) => {
+      const globals = command.optsWithGlobals();
+      const nonInteractive = isNonInteractive(globals);
       if (opts.scope === "user") {
-        installGlobalHooks({ force: opts.force });
+        const plan = planGlobalHooks({ force: opts.force });
+        const outcome = installGlobalHooks({
+          force: opts.force,
+          machineWide: await consentToMachineWideHooks(
+            plan,
+            opts.globalHooksPath,
+            nonInteractive
+          )
+        });
+        if (outcome === "runtime_missing") {
+          process.exitCode = 1;
+        } else if (opts.globalHooksPath && !INSTALLED_OUTCOMES.has(outcome)) {
+          process.exitCode = EXIT_GLOBAL_HOOKS_NOT_INSTALLED;
+        }
+        return;
+      }
+      if (opts.globalHooksPath) {
+        console.error("[prim] --global-hooks-path applies only with --scope user");
+        process.exitCode = 2;
         return;
       }
-      const globals = command.optsWithGlobals();
-      const nonInteractive = isNonInteractive(globals);
       const gitRoot = getGitRoot();
+      if (gitHooksMode({ cwd: gitRoot }) === "manual") {
+        printManualNote(gitRoot);
+        return;
+      }
+      stageGitHookRuntime();
       if (opts.target === "husky") return installHooks(gitRoot, "husky");
       if (opts.target === "git-hooks") return installHooks(gitRoot, "git-hooks");
-      if (detectHusky(gitRoot)) {
+      const effectiveDir = resolveEffectiveGitHook(PRE_COMMIT.hookName, gitRoot).hooksDir;
+      if (resolve(effectiveDir) === projectHooksDir(gitRoot) && detectHusky(gitRoot)) {
         if (globals.yes) return installHooks(gitRoot, "husky");
         if (nonInteractive) {
           throw new Error(
@@ -1882,10 +1901,25 @@ function registerHooksCommands(program2) {
         } else {
           console.log("Falling back to .git/hooks install.");
         }
+        return installHooks(gitRoot, "git-hooks");
       }
-      installHooks(gitRoot, "git-hooks");
+      installHooks(gitRoot, "effective");
     }
   );
+  hooks.command("snippet").description("Print the block that wires one prim git hook (STDOUT), to place by hand").addArgument(new Argument("<hook>", "git hook").choices(MANAGED_GIT_HOOK_NAMES)).action((hook) => {
+    process.stdout.write(`${managedHookBlock(hook)}
+`);
+    let entrypoint = "<prim config>/prim-git-hook-v1";
+    try {
+      entrypoint = hookRuntimePaths().gitHookEntrypoint;
+    } catch {
+    }
+    process.stderr.write(
+      `[prim] Place this block right after the shebang of your ${hook} hook (in a Husky v8 hook, right after the husky.sh line), before any exit or exec. It runs prim's ${hook} step where prim is installed and enabled, and does nothing elsewhere.${hook === "post-rewrite" ? " It re-arms stdin, so commands after it still read Git's rewrite pairs." : ""}
+[prim] From a hook manager, run \`${entrypoint} ${hook} "$@"\`${hook === "post-rewrite" ? " with Git's stdin" : ""} instead. Set \`git config prim.gitHooks manual\` so prim leaves your hook files alone.
+`
+    );
+  });
   hooks.command("uninstall").description(
     "Remove the prim git hooks (.git/hooks, or the global core.hooksPath with --scope user)"
   ).addOption(
@@ -1905,6 +1939,49 @@ function registerHooksCommands(program2) {
 // src/commands/activation.ts
 var CONNECT_PROMPT = "[prim] GitHub repo connection is required to enable repository-specific file attribution, Conflict Gate verification, and commit correlation. Start the GitHub App connection now?";
 var GITHUB_CONNECTION_REQUIRED = "GitHub repo connection is required before using Primitive in this repository. It enables repository-specific file attribution, Conflict Gate verification, and commit correlation. Run `prim github connect` to complete it.";
+function wireRepositoryHooks(root) {
+  stageGitHookRuntime();
+  refreshOwnedGlobalHooks();
+  const paths = {};
+  let manual = false;
+  let changed = false;
+  for (const hookName of MANAGED_GIT_HOOK_NAMES) {
+    try {
+      const result = ensureEffectiveGitHook(hookName, root, { context: "explicit" });
+      if (result.outcome === "external") {
+        throw new Error(
+          `Git runs this repository's ${hookName} hook from ${result.path}, outside the repository; ${externalHookRemedy(hookName, root)}`
+        );
+      }
+      if (result.outcome === "kept") {
+        process.stderr.write(
+          `[prim] kept the working pre-v1 ${hookName} hook at ${result.path}, outside the repository; to upgrade it, ${externalHookRemedy(hookName, root)}
+`
+        );
+      }
+      if (result.outcome === "runtime_missing") {
+        process.stderr.write(
+          `[prim] kept the working pre-v1 ${hookName} hook at ${result.path}; it is replaced once the hook runtime is staged
+`
+        );
+      }
+      paths[hookName] = result.path;
+      manual ||= result.outcome === "manual";
+      if (hookName === "post-commit") changed ||= result.changed;
+    } catch (error) {
+      if (hookName === "post-commit") throw error;
+      const detail = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`[prim] ${hookName} hook coverage is degraded: ${detail}
+`);
+    }
+  }
+  if (manual) {
+    process.stderr.write(
+      "[prim] prim.gitHooks=manual: left hook files untouched; wire them with `prim hooks snippet <hook>`\n"
+    );
+  }
+  return { paths, changed };
+}
 async function maybeConnectRepository(root, globals) {
   if (isNonInteractive(globals)) return void 0;
   const approved = Boolean(globals.yes) || await askConfirmation(CONNECT_PROMPT, process.stderr);
@@ -1924,6 +2001,13 @@ async function maybeConnectRepository(root, globals) {
   }
   return void 0;
 }
+function hookPathFields(paths) {
+  return {
+    ...paths["pre-commit"] ? { preCommitHook: paths["pre-commit"] } : {},
+    ...paths["post-commit"] ? { postCommitHook: paths["post-commit"] } : {},
+    ...paths["post-rewrite"] ? { postRewriteHook: paths["post-rewrite"] } : {}
+  };
+}
 async function applyActivation(active, globals = {}) {
   const root = gitToplevel();
   if (!root) {
@@ -1936,18 +2020,11 @@ async function applyActivation(active, globals = {}) {
   let phase = active ? "post-commit hook coverage" : "local deactivation";
   try {
     let binding;
-    let postCommitHook;
-    let postRewriteHook;
+    let hookPaths = {};
+    let hooksChanged = false;
+    const wasActive = repoActiveFlag(root) === "true";
     if (active) {
-      refreshOwnedGlobalHooks();
-      postCommitHook = ensureEffectivePostCommitHook(root).path;
-      try {
-        postRewriteHook = ensureEffectivePostRewriteHook(root).path;
-      } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`[prim] post-rewrite hook coverage is degraded: ${detail}
-`);
-      }
+      ({ paths: hookPaths, changed: hooksChanged } = wireRepositoryHooks(root));
       phase = "GitHub repo connection";
       binding = await bindRepository(root);
     }
@@ -1961,8 +2038,7 @@ async function applyActivation(active, globals = {}) {
           repo: root,
           bindingStatus: binding.status,
           repositoryFullName: binding.repositoryFullName,
-          ...postCommitHook ? { postCommitHook } : {},
-          ...postRewriteHook ? { postRewriteHook } : {}
+          ...hookPathFields(hookPaths)
         });
         process.exitCode = 1;
         return;
@@ -1977,6 +2053,10 @@ async function applyActivation(active, globals = {}) {
     }
     phase = "local activation";
     setRepoActive(root, active);
+    if (!active) clearHooksWired(root);
+    if (active) {
+      recordHooksWired(root, { onlyIfAbsent: wasActive && !hooksChanged });
+    }
     await daemonRequest("statusline_invalidate", {}, { timeoutMs: 250 });
     process.stderr.write(`[prim] prim ${active ? "enabled" : "disabled"} in ${root}
 `);
@@ -1988,8 +2068,7 @@ async function applyActivation(active, globals = {}) {
         repositoryFullName: binding.repositoryFullName,
         ...binding.status === "connected" ? { repoSyncId: binding.repoSyncId } : {}
       } : {},
-      ...postCommitHook ? { postCommitHook } : {},
-      ...postRewriteHook ? { postRewriteHook } : {}
+      ...hookPathFields(hookPaths)
     });
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
@@ -2286,7 +2365,7 @@ import {
   writeFileSync as writeFileSync2
 } from "fs";
 import { homedir as homedir3 } from "os";
-import { basename, dirname as dirname2, isAbsolute, join as join4, resolve as resolve2 } from "path";
+import { basename, dirname, isAbsolute, join as join4, resolve as resolve2 } from "path";
 
 // src/lib/bounded-file.ts
 import { constants, closeSync, fstatSync, lstatSync as lstatSync2, openSync, readSync } from "fs";
@@ -2398,7 +2477,7 @@ function daemonControlPaths(options = {}) {
   };
 }
 function findPackageVersion(entryFile) {
-  let dir = dirname2(resolve2(entryFile));
+  let dir = dirname(resolve2(entryFile));
   for (let depth = 0; depth < 6; depth++) {
     const packagePath = join4(dir, "package.json");
     if (existsSync3(packagePath)) {
@@ -2410,7 +2489,7 @@ function findPackageVersion(entryFile) {
       } catch {
       }
     }
-    const parent = dirname2(dir);
+    const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -2832,7 +2911,7 @@ function readDaemonLauncherFile(path) {
 function readUsableDaemonConfig(path) {
   const config = readDaemonLauncher(path);
   if (!config) return null;
-  const manifest = readRuntimeManifest(join4(dirname2(config.daemonPath), "manifest.json"));
+  const manifest = readRuntimeManifest(join4(dirname(config.daemonPath), "manifest.json"));
   try {
     accessSync(config.nodePath, constants2.X_OK);
     return manifest?.version === config.runtimeVersion && manifest.nodePath === config.nodePath && manifest.daemonSha256 === sha256File(config.daemonPath) ? config : null;
@@ -2926,7 +3005,7 @@ function atomicWrite2(path, content, mode, validate) {
     }
   } catch {
   }
-  mkdirSync2(dirname2(path), { recursive: true, mode: RUNTIME_DIR_MODE });
+  mkdirSync2(dirname(path), { recursive: true, mode: RUNTIME_DIR_MODE });
   const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
   writeFileSync2(temp, content, { encoding: "utf8", mode, flag: "wx" });
   try {
@@ -2962,7 +3041,7 @@ function canonicalProspectivePath(path) {
   const suffix = [];
   let ancestor = resolve2(path);
   while (!existsSync3(ancestor)) {
-    const parent = dirname2(ancestor);
+    const parent = dirname(ancestor);
     if (parent === ancestor) return resolve2(path);
     suffix.unshift(basename(ancestor));
     ancestor = parent;
@@ -3302,7 +3381,7 @@ async function ensureMacDaemonLocked(options) {
     };
   }
   const servicePaths = launchdPaths(options);
-  mkdirSync2(dirname2(servicePaths.logPath), { recursive: true, mode: RUNTIME_DIR_MODE });
+  mkdirSync2(dirname(servicePaths.logPath), { recursive: true, mode: RUNTIME_DIR_MODE });
   writeFileSync2(servicePaths.logPath, "", { mode: RUNTIME_FILE_MODE, flag: "a" });
   chmodSync(servicePaths.logPath, RUNTIME_FILE_MODE);
   const launcher = generateDaemonLauncher(daemonConfig);
@@ -7534,7 +7613,26 @@ async function checkRepositoryBinding() {
     };
   }
 }
-function classifyManagedHook(hookName, inspection) {
+function managedHookRemedy(inspection) {
+  switch (inspection.reason) {
+    case "missing":
+    case "missing_block":
+    case "stale_block":
+    case "legacy_block":
+    case "unreachable_block":
+    case "misplaced_block":
+      if (inspection.location === "prim") return "run `prim enable` to refresh prim's global hooks";
+      if (inspection.location === "external") {
+        return `outside this repository \u2014 ${externalHookRemedy(inspection.hookName, inspection.gitRoot)}`;
+      }
+      return "run `prim hooks install`";
+    case "entrypoint_missing":
+      return "run `prim enable` to stage the hook runtime";
+    default:
+      return void 0;
+  }
+}
+function classifyManagedHook(hookName, inspection, firing) {
   if (inspection.covered) {
     return {
       name: hookName,
@@ -7542,15 +7640,78 @@ function classifyManagedHook(hookName, inspection) {
       detail: `effective and executable \xB7 ${inspection.kind} \xB7 ${inspection.hookPath}`
     };
   }
+  const reason = inspection.reason ?? "uncovered";
+  if (inspection.mode === "manual") {
+    if (hookName === "post-commit" && firing?.state === "fired") {
+      return {
+        name: hookName,
+        status: "ok",
+        detail: `manual (prim.gitHooks=manual) \xB7 ran for the latest commit \xB7 ${inspection.hookPath}`
+      };
+    }
+    return {
+      name: hookName,
+      status: "warn",
+      detail: `manual (prim.gitHooks=manual) \xB7 ${reason} \xB7 wire with \`prim hooks snippet ${hookName}\` \xB7 ${inspection.hookPath}`
+    };
+  }
+  const remedy = managedHookRemedy(inspection);
+  const stillCaptures = reason === "legacy_block" || reason === "misplaced_block";
   return {
     name: hookName,
-    status: "fail",
-    detail: `${inspection.reason ?? "uncovered"} \xB7 ${inspection.hookPath}`
+    status: hookName === "pre-commit" || stillCaptures ? "warn" : "fail",
+    detail: `${reason}${remedy ? ` \xB7 ${remedy}` : ""} \xB7 ${inspection.hookPath}`
   };
 }
-function checkManagedHook(hookName, inspect) {
+function minutesAgo(at, now) {
+  const minutes = Math.max(0, Math.round((now - at) / 6e4));
+  return minutes === 0 ? "just now" : `${String(minutes)}m ago`;
+}
+function classifyHookFiring(firing, now = Date.now()) {
+  const name = "hook-fired";
+  switch (firing.state) {
+    case "inactive":
+      return { name, status: "ok", detail: "repository not active \u2014 no post-commit run expected" };
+    case "unverified":
+      return {
+        name,
+        status: "ok",
+        detail: "no local commit since the hooks were wired \u2014 the next commit is checked"
+      };
+    case "pending":
+      return {
+        name,
+        status: "ok",
+        detail: `latest commit is under ${String(POST_COMMIT_GRACE_MS / 1e3)}s old \u2014 capture may still be starting`
+      };
+    case "fired":
+      return {
+        name,
+        status: "ok",
+        detail: `post-commit reached prim for the latest commit (${minutesAgo(firing.firedAt, now)})`
+      };
+    case "not_firing":
+      return {
+        name,
+        status: "fail",
+        detail: `post-commit never reached prim for the commit made ${minutesAgo(firing.commitAt, now)}${firing.firedAt === void 0 ? "" : ` (last run ${minutesAgo(firing.firedAt, now)})`} \xB7 likely an exit/exec before prim's block, hooks turned off for that commit (HUSKY=0, a core.hooksPath override), or a git client without prim's environment \xB7 fix the cause, then commit to re-check \xB7 if prim was off for that commit (set with \`git config prim.active\` directly), run \`prim disable\` then \`prim enable\` to restart the check`
+      };
+  }
+}
+function inspectFiringHere() {
+  try {
+    const root = gitToplevel();
+    return root ? inspectPostCommitFiring(root) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function checkHookFiring(firing) {
+  return firing ? classifyHookFiring(firing) : { name: "hook-fired", status: "warn", detail: "not a git repository" };
+}
+function checkManagedHook(hookName, firing) {
   try {
-    return classifyManagedHook(hookName, inspect());
+    return classifyManagedHook(hookName, inspectEffectiveGitHook(hookName), firing);
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     return {
@@ -7869,15 +8030,9 @@ async function checkFeedbackCapability() {
     return { name: "feedback-api", status: "warn", detail: message.slice(0, 80) };
   }
 }
-function refreshOwnedGlobalHooksForHealth() {
-  try {
-    refreshOwnedGlobalHooks();
-  } catch {
-  }
-}
 async function independentChecks() {
-  refreshOwnedGlobalHooksForHealth();
   const backend = await checkBackend();
+  const firing = inspectFiringHere();
   return {
     before: [checkAuth()],
     after: [
@@ -7886,8 +8041,10 @@ async function independentChecks() {
       ...checkAgentHooks(),
       checkHookRuntime(),
       await checkRepositoryBinding(),
-      checkManagedHook("post-commit", inspectEffectivePostCommitHook),
-      checkManagedHook("post-rewrite", inspectEffectivePostRewriteHook),
+      checkManagedHook("pre-commit"),
+      checkManagedHook("post-commit", firing),
+      checkManagedHook("post-rewrite"),
+      checkHookFiring(firing),
       ...backend,
       await checkFeedbackCapability()
     ]
@@ -7936,7 +8093,7 @@ import { join as join9 } from "path";
 
 // src/flusher.ts
 import { createReadStream, renameSync as renameSync3, statSync as statSync3, unlinkSync as unlinkSync3 } from "fs";
-import { dirname as dirname4, join as join8 } from "path";
+import { dirname as dirname3, join as join8 } from "path";
 
 // src/dead-letter.ts
 import { createHash as createHash3, randomBytes as randomBytes4 } from "crypto";
@@ -7953,12 +8110,12 @@ import {
   rmSync as rmSync3,
   writeFileSync as writeFileSync3
 } from "fs";
-import { dirname as dirname3, join as join7 } from "path";
+import { dirname as dirname2, join as join7 } from "path";
 var DIRECTORY_MODE = 448;
 var FILE_MODE = 384;
 var DEAD_LETTER_DIRNAME = "dead-letter";
 function deadLetterDirectoryForRotation(flushingPath) {
-  return join7(dirname3(flushingPath), DEAD_LETTER_DIRNAME);
+  return join7(dirname2(flushingPath), DEAD_LETTER_DIRNAME);
 }
 function deadLetterPathForRawLine(flushingPath, rawLine) {
   const quarantineId = createHash3("sha256").update(rawLine).digest("hex");
@@ -7968,7 +8125,7 @@ function ensureDeadLetterDirectory(flushingPath, persistDirectory) {
   const directory = deadLetterDirectoryForRotation(flushingPath);
   mkdirSync4(directory, { recursive: true, mode: DIRECTORY_MODE });
   chmodSync2(directory, DIRECTORY_MODE);
-  persistDirectory(dirname3(directory));
+  persistDirectory(dirname2(directory));
   return directory;
 }
 function persistDeadLetter(directory, path, quarantineId, record3, persistDirectory) {
@@ -8387,7 +8544,7 @@ async function flushOnce() {
   return inspection.retainedBuckets.length > 0 ? { flushed: total, quarantined, retained: inspection.retainedBuckets } : { flushed: total, quarantined };
 }
 var flushInFlight;
-var FLUSH_LOCK_PATH = join8(dirname4(JOURNAL_DIR), ".flush.lock");
+var FLUSH_LOCK_PATH = join8(dirname3(JOURNAL_DIR), ".flush.lock");
 var FLUSH_LOCK_TIMEOUT_MS = 250;
 function isFlushLockContended(error) {
   return error instanceof Error && error.message.startsWith("timed out waiting for file lock");
@@ -8735,12 +8892,16 @@ function planSetupSteps(opts) {
       required: true
     });
   }
-  steps.push({
-    key: "hooks",
-    label: "Git hooks",
-    args: ["hooks", "install", ...scopeArgs],
-    required: true
-  });
+  if (opts.scope === "project") {
+    steps.push({ key: "hooks", label: "Git hooks", args: ["hooks", "install"], required: true });
+  } else if (opts.globalHooksPath) {
+    steps.push({
+      key: "hooks",
+      label: "Git hooks (global)",
+      args: ["hooks", "install", "--scope", "user", "--global-hooks-path"],
+      required: true
+    });
+  }
   const skillArgs = ["skill", "install", "--agent", opts.agent, ...scopeArgs];
   steps.push({ key: "skill", label: "Agent skill", args: skillArgs, required: true });
   steps.push({
@@ -8771,7 +8932,44 @@ function planCleanupUninstalls(agent, conflicts) {
   if (conflicts.includes(CONFLICT_SKILL)) steps.push(["skill", "uninstall", "--agent", agent]);
   return steps;
 }
-function detectProjectConflicts(agent, run) {
+function preCommitRunsPrim(content) {
+  return content.includes("# >>> prim pre-commit hook >>>") || content.includes("prim-pre-commit");
+}
+function projectHooksConflict(globalHooksActive, preCommit) {
+  return globalHooksActive && preCommit !== void 0 && preCommitRunsPrim(preCommit);
+}
+function enableWiresRepository(root) {
+  if (!root) return void 0;
+  try {
+    if (gitHooksMode({ cwd: root }) === "manual") return void 0;
+    return resolveEffectiveGitHook("post-commit", root).location !== "external";
+  } catch {
+    return void 0;
+  }
+}
+function setupGitHooksNote(plan, wiresThisRepository) {
+  if (wiresThisRepository === true && plan.action === "add_to_dir") {
+    return `git hooks \xB7 Git runs this repository's hooks from inside it, so \`prim enable\` wires it; other repositories may run ${plan.global}, which prim edits only with --global-hooks-path, after asking the user`;
+  }
+  if (wiresThisRepository === true && plan.action === "system_declined") {
+    return `git hooks \xB7 Git runs this repository's hooks from inside it, so \`prim enable\` wires it; other repositories may run the system hooks dir ${plan.system}, which prim never edits`;
+  }
+  switch (plan.action) {
+    case "refresh":
+      return "git hooks \xB7 prim's global hooks stay active; `prim enable` refreshes them";
+    case "present_in_dir":
+      return `git hooks \xB7 prim's hooks are already in your global hooks dir ${plan.global}`;
+    case "add_to_dir":
+      return `git hooks \xB7 your global core.hooksPath (${plan.global}) runs every repository's hooks, so \`prim enable\` cannot wire this repository without it; add prim there with --global-hooks-path, after asking the user`;
+    case "system_declined":
+      return `git hooks \xB7 the system core.hooksPath (${plan.system}) runs every repository's hooks, so \`prim enable\` cannot wire this repository: place \`prim hooks snippet <hook>\` there, or, after asking the user, run \`prim hooks install --scope user --global-hooks-path --force\` (its hooks stop firing)`;
+    case "manual":
+      return "git hooks \xB7 prim.gitHooks=manual: prim writes no hook files; wire them with `prim hooks snippet <hook>`";
+    default:
+      return "git hooks \xB7 wired per repository by `prim enable`; git's global hooks are untouched (opt in with --global-hooks-path)";
+  }
+}
+function detectProjectConflicts(agent, run, globalHooksActive) {
   const conflicts = [];
   if (agent !== "hermes") {
     try {
@@ -8780,14 +8978,14 @@ function detectProjectConflicts(agent, run) {
     } catch {
     }
   }
+  let preCommit;
   try {
     const root = gitToplevel();
-    const preCommit = root && join11(root, ".git", "hooks", "pre-commit");
-    if (preCommit && existsSync10(preCommit) && readFileSync7(preCommit, "utf-8").includes("prim-pre-commit")) {
-      conflicts.push(CONFLICT_HOOKS);
-    }
+    const path = root && join11(root, ".git", "hooks", "pre-commit");
+    if (path && existsSync10(path)) preCommit = readFileSync7(path, "utf-8");
   } catch {
   }
+  if (projectHooksConflict(globalHooksActive, preCommit)) conflicts.push(CONFLICT_HOOKS);
   try {
     const parsed = JSON.parse(
       run(["skill", "status", "--agent", agent, "--json"], true).stdout || "{}"
@@ -8827,8 +9025,11 @@ function registerSetupCommand(program2, dependencies = {}) {
     "Install everything in one shot (auth, session + git hooks, daemon, skill, welcome)"
   ).option("--agent <agent>", "claude, codex, cursor, or hermes (auto-detected when omitted)").option(
     "--scope <scope>",
-    "user (default \u2014 install once for every repo) or project (this repo only)",
+    "user (default \u2014 agent integration and skill for every repo; git hooks per repo via enable) or project (this repo only)",
     "user"
+  ).option(
+    "--global-hooks-path",
+    "with the default user scope, also change git's global hooks so prim's hooks run in every repository"
   ).option(
     "--migrate",
     "with the default user scope, remove any project-scoped prim config in this repo (else just warn)"
@@ -8848,6 +9049,11 @@ function registerSetupCommand(program2, dependencies = {}) {
       (dependencies.exit ?? process.exit)(EXIT_USAGE3);
       return;
     }
+    if (opts.globalHooksPath && opts.scope !== "user") {
+      process.stderr.write("[prim] --global-hooks-path applies only with --scope user\n");
+      (dependencies.exit ?? process.exit)(EXIT_USAGE3);
+      return;
+    }
     const agent = agentInput;
     const scope = opts.scope;
     const self = process.argv[1];
@@ -8899,16 +9105,24 @@ function registerSetupCommand(program2, dependencies = {}) {
       note("pre-authorize \xB7 writing prim allow-rule (user scope)\u2026");
       results.preauth = run(["claude", "preauth", "--scope", "user"]).code === 0 ? "ok" : "skipped";
     }
-    const setupSteps = planSetupSteps({ agent, daemon: opts.daemon, scope });
+    const setupSteps = planSetupSteps({
+      agent,
+      daemon: opts.daemon,
+      scope,
+      globalHooksPath: opts.globalHooksPath === true
+    });
     for (const step of setupSteps.filter(
       (candidate) => candidate.key !== "enable" && candidate.key !== "health"
     )) {
       note(`${step.label} \xB7 installing\u2026`);
       const { code } = run(step.args);
-      results[step.key] = code === 0 ? "ok" : step.required ? "failed" : "skipped";
+      results[step.key] = code === 0 ? "ok" : code === EXIT_GLOBAL_HOOKS_NOT_INSTALLED && step.key === "hooks" ? "skipped" : step.required ? "failed" : "skipped";
+    }
+    if (scope === "user" && !opts.globalHooksPath) {
+      note(setupGitHooksNote(planGlobalHooks(), enableWiresRepository(gitToplevel())));
     }
     if (scope === "user") {
-      const conflicts = detectProjectConflicts(agent, run);
+      const conflicts = detectProjectConflicts(agent, run, globalHooksPathIsPrims());
       if (conflicts.length > 0 && opts.migrate) {
         note(`migrate \xB7 removing project-scoped config (${conflicts.join(", ")})\u2026`);
         const ok = planCleanupUninstalls(agent, conflicts).map((args) => run(args).code === 0).every(Boolean);
@@ -8949,12 +9163,12 @@ function registerSetupCommand(program2, dependencies = {}) {
 
 // src/commands/statusline.ts
 import { readFileSync as readFileSync8 } from "fs";
-import { dirname as dirname5, resolve as resolve3 } from "path";
+import { dirname as dirname4, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 var STATUSLINE_TIMEOUT_MS = 200;
 function readPackageVersion() {
   try {
-    const here = dirname5(fileURLToPath(import.meta.url));
+    const here = dirname4(fileURLToPath(import.meta.url));
     const candidates = [
       // Schema-v2 runtimes staged a manifest beside this standalone bundle.
       // Keep resolving it while those legacy launchers transition to schema v3.
@@ -9470,7 +9684,7 @@ import { readFileSync as readFileSync9 } from "fs";
 
 // src/daemon/health.ts
 import { chmodSync as chmodSync3, existsSync as existsSync11, mkdirSync as mkdirSync7, renameSync as renameSync4, writeFileSync as writeFileSync6 } from "fs";
-import { dirname as dirname6, join as join12 } from "path";
+import { dirname as dirname5, join as join12 } from "path";
 var HEARTBEAT_FRESH_MS = 9e4;
 var DAEMON_HEALTH_PATH = join12(primConfigDirectory(), "daemon-health.json");
 
@@ -9599,7 +9813,7 @@ function runStartupBackgroundWork(argv, env, work) {
 }
 
 // src/index.ts
-var __dirname = dirname7(fileURLToPath2(import.meta.url));
+var __dirname = dirname6(fileURLToPath2(import.meta.url));
 var pkg = JSON.parse(readFileSync10(resolve4(__dirname, "../package.json"), "utf-8"));
 runStartupBackgroundWork(process.argv.slice(2), process.env, {
   notify: () => updateNotifier({ pkg }).notify(),