pnpm install fails in submodule checkouts: install-lefthook cannot enable extensions.worktreeConfig while core.worktree is in the common config

[Private0xCC]

Summary

When this repository is checked out as a git submodule of a parent repository, the root postinstall script (scripts/install-lefthook.mjs) always fails, so pnpm install exits with code 1. Dependencies install fine and pnpm run build passes, but the failing install step breaks scripted/CI setups that check exit codes, prevents lefthook from being installed, and — because of verifyDepsBeforeRun — the failure re-runs (and warns) on every pnpm run / pnpm dsh invocation.

Environment

• Commit: 86a402200d (dsh-v0.2.1-alpha.2-941-g86a402200d, default branch, tested 2026-10-16)
• macOS (Darwin 25.6.0, arm64), git 2.50.1 (Apple Git-155)
• node v26.5.0, pnpm 11.28.5 (matches packageManager exactly, so toolchain mismatch is not a factor)

Reproduction

TESTDIR=$(mktemp -d) && cd "$TESTDIR"
git init parent && cd parent
git commit -q --allow-empty -m init
git submodule add https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

Result:

. postinstall$ node scripts/install-lefthook.mjs
. postinstall: [install-lefthook] cannot enable extensions.worktreeConfig while core.worktree is in the common config (file:/…/parent/.git/modules/deepseek-harness/config: "../../../deepseek-harness"); move it to the main worktree config first
. postinstall: Failed
[ELIFECYCLE] Command failed with exit code 1.

The same failure then re-runs before every pnpm run / pnpm dsh invocation:

[WARN] The install that runs before scripts failed, so your node_modules may be out of sync with your lockfile. Set "verifyDepsBeforeRun: false" to skip this install.

Root cause

For any submodule, git itself writes core.worktree = <relative path back to the worktree> into the module's common config ($PARENT/.git/modules/<name>/config). That is standard submodule behavior, not something the user configured.

scripts/install-lefthook.mjs unconditionally needs to enable extensions.worktreeConfig, but refuses to do so when core.worktree is present in the common config (check around scripts/install-lefthook.mjs:260):

if (worktreeText !== undefined) {
  throw new Error(
    `cannot enable extensions.worktreeConfig while core.worktree is in the common config `
    + `(file:${commonConfigPath}: ${JSON.stringify(worktreeText)}); `
    + 'move it to the main worktree config first',
  )
}

Since core.worktree is always in the common config for submodules, the script always fails there — and "move it to the main worktree config first" is not actionable, because git needs that entry to locate the submodule worktree. DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE does not cover this check (it only handles a pre-existing core.hooksPath configured elsewhere).

Impact

• pnpm install exits 1 in every submodule checkout, including fresh clones.
• lefthook git hooks are never installed in the submodule checkout.
• Every pnpm run re-triggers the failing pre-run install and prints the warning (noisy, though not blocking).
• pnpm run build itself passes (9/9 gates on my machine) and pnpm dsh --version works, so this does not block building or running — it affects the install exit code, hook installation, and any scripted setup that checks exit codes.

Suggested fix

Roughly in order of preference:

1. Detect the submodule case (e.g. .git is a file, or core.worktree present in the common config) and fall back to a plain, non-worktree-scoped git config core.hooksPath dsh-hooks in the module config — or simply skip the worktree-config migration — with a warning.
2. Make the postinstall non-fatal when hooks cannot be installed (warn and exit 0), since the build does not depend on hooks.
3. At minimum, document the submodule limitation and provide an escape-hatch env var similar to DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE.

Happy to provide more details or test a fix.

Workaround for consumers (verified)

Until this is fixed, consumers embedding the repo as a git submodule can use the script's own CI short-circuit (line 624) for the install step:

cd deepseek-harness
CI=true pnpm install

After one successful install, verifyDepsBeforeRun stops re-running the failing install, so subsequent pnpm run / pnpm dsh invocations are clean. CI=true only affects two other code paths in the repo (parallelism worker cap and oxlint output format), neither of which impacts build correctness. The trade-off is that lefthook hooks are not installed in the submodule checkout, which only matters if you commit inside the submodule.

[argszero]

Confirmed at source — including the CI escape hatch you found

I read scripts/install-lefthook.mjs at the current head (86a40220) rather than working from your log, and every element of your report is in the tree:

• The refusal and its message, verbatim (:261-267):

  const worktreeText = assertSingle(
    directFileConfigValues(root, commonConfigPath, 'core.worktree'),
    'core.worktree',
  )
  if (worktreeText !== undefined) {
    throw new Error(
      `cannot enable extensions.worktreeConfig while core.worktree is in the common config `
      + `(file:${commonConfigPath}: ${JSON.stringify(worktreeText)}); `
      + 'move it to the main worktree config first',
    )
  }

• Your CI=true workaround is exact: :624 is the first statement of main() — if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') return — so it returns before any git call. Nothing else in that script runs, which is why the shortcut is complete rather than partial.
• Your reading of DSH_LEFTHOOK_ALLOW_HOOKS_PATH_OVERRIDE is right: it is defined at :28 and read at exactly one place, :692, inside the inherited-core.hooksPath refusal branch. It never reaches the core.worktree check.
• And there is no submodule branch anywhere in the script. It resolves --absolute-git-dir and --git-common-dir (:634-635) and compares them to detect multi-worktree layouts; a submodule, whose .git is a file and whose common dir is the parent's .git/modules/<name>, is simply not a case it considers.

Why the check exists, which is what makes the remedy unactionable

The extension is not incidental to what the script is doing. It writes the hook path worktree-scoped (:711):

      git(['config', '--worktree', 'core.hooksPath', hooksPath], root)

and then asserts the write actually became the effective direct worktree value (:713-720) — that invariant is the whole reason extensions.worktreeConfig has to be on. Your point that "move it to the main worktree config first" is not actionable is therefore sharper than a wording complaint: the entry the script refuses to coexist with is the entry git itself wrote so that the module's worktree can be located at all.

A refinement to your option 1

Look at what the value being written actually is: hooksPath = join(gitDirectory, HOOKS_DIRECTORY) (:639), where gitDirectory is the absolute git dir from --absolute-git-dir (:634), and HOOKS_DIRECTORY is 'dsh-hooks' (:20). The value is absolute, and it lives inside the git directory — so it cannot collide with the host repository's own .git/hooks no matter which scope carries it.

That matters for the submodule case specifically: a submodule's common config governs exactly one worktree, so a plain local core.hooksPath <absolute path> in that same file is equivalent in effect to the worktree-scoped one, and needs no extension. Your fallback is sound; the only thing it has to carry over is the ownership check the script already performs before adopting a directory (inspectOwnedHooksDirectory, :499-528 — it refuses a non-directory, a symlink, or an unowned path), so that a fallback path does not become the one place a foreign dsh-hooks is silently taken over.

Two smaller things from the read

• The core.worktree lookup is directFileConfigValues(...), so only an entry literally present in that file triggers the refusal — which is exactly the submodule shape git creates, and also why nothing else on your machine hits it.
• On the repeated warning: the durable fix for the pre-run install is the same as the install-time one, since the pre-run invocation is the same script. If you keep the CI=true route, setting it in the environment for every pnpm call inside the submodule (rather than only the first install) is what removes the dependence on the first run having been recorded as successful.

I have not reproduced the submodule layout here — creating one needs network for git submodule add — so the git-side behaviour is your measurement. What I verified in the tree is the refusal, its trigger, the absence of any submodule handling, the worktree-scoped write and its asserted invariant, the single read site of the override variable, and that :624 short-circuits before any git work.