A --patch-inserted plugin validates its config but never activates, and ctx.logger has no sink in any shipped profile

[ichiorca]

Found while wiring an external governance tool to the Claude Code hook bridge. Posting here rather than as an issue per CONTRIBUTING.md.

Short version: a plugin inserted through a --patch overlay is resolved, applied and config-validated, and then appears never to activate — no handler ever runs. I could not find the reason from the outside because ctx.logger has no sink in either shipped profile, so the warning that would explain it is unobservable.

This is not the PowerShell exit-code fail-open in #2485. There the hook runs and its exit code is mangled; here the hook command never executes at all — a marker command that only appends to a file leaves no file.

Environment

• dsh 0.1.0-rc.7 (npm next), @deepseek-ai/dsh-hooks-claude-code 0.1.0-rc.6
• Node v25.2.1, pnpm 11.21.0, Windows 11
• Profiles headless and web, both freshly materialised

Reproduce

dsh plugin --profile headless add \
  @deepseek-ai/dsh-hooks-claude-code@next \
  @deepseek-ai/dsh-hook-protocol@next \
  @deepseek-ai/dsh-invariants@next

hooks.json — the command deliberately involves no third-party tool, so nothing but the bridge is on trial:

{ "hooks": { "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "timeout": 60,
  "command": "node -e \"require('fs').appendFileSync('C:/tmp/proj/marker.txt','fired\\n')\"" } ] } ] } }

patch.yml:

- insert:
    - id: cavesson-hooks
      name: '@deepseek-ai/dsh-hooks-claude-code'
      config:
        configPath: 'C:/tmp/proj/hooks.json'
        projectDir: 'C:/tmp/proj'

dsh --profile headless --patch patch.yml "create a file named hello.txt containing hi"

Observed: the agent creates hello.txt and exits normally. marker.txt is never created. No warning, no error, on stdout or stderr.

Expected: either the hook runs, or something says why it did not.

The mount is fine — that part is verifiable

Both ways an entry can be wrong fail loudly, so a valid entry really is resolved, applied and validated:

# unresolvable plugin name
Error: dsh: plugin tree failed to load: ... Cannot find package '@deepseek-ai/dsh-this-package-does-not-exist'

# omitting the bridge's required key
Error: dsh: plugin tree failed to load: failed to apply loader entry cavesson-hooks
  (@deepseek-ai/dsh-hooks-claude-code): invalid config: configPath required

Ruled out along the way: package not installed; version skew (rc.5 → rc.6 against runtime rc.7); the patch not composing (--dump-config shows the entry); absolute vs relative configPath; spaces in the path (the 8.3 short form behaves identically); and the config file shape — parseClaudeCodeConfig accepts a bare hooks event map of command hooks, which is what is being fed.

No diagnostic channel in either shipped profile

packages/hooks/hooks-claude-code catches a config-load failure, calls ctx.logger.warn(... — no hooks registered) and returns, and the examples/acp-agent/cordis.yml comment notes warnings "use ctx.logger, never stdout". That is reasonable, but neither shipped profile appears to mount a sink:

• dsh --profile headless --dump-config and --profile web --dump-config contain no logger entry.
• Booting web with a configPath pointing at a file that does not exist produced no warning at all.
• Inserting your own @deepseek-ai/cordis-plugin-logger-console (as in examples/headless-agent/tests/fixtures/session-telemetry-otel.cordis.yml) through the same --patch produced zero output, including from the logger itself — which may be the same activation problem, one level down.

So a mount that silently does nothing is also a mount that cannot be debugged from a released install.

Guess, offered only as a starting point

lib/index.js declares inject = ["shell"]. If activation is gated on service availability while config validation happens earlier at apply, that would explain the whole pattern at once: a config error is visible, an unsatisfied injection is not, and an inactive plugin registers nothing. I could not confirm whether headless provides a shell service — it composes dsh-bash-sandbox, dsh-shell-env, dsh-subprocess-local and dsh-tool-bash.

Questions

1. Is --patch insert expected to activate plugins the same way a bundle layer does, or is there an additional step for out-of-tree packages that declare no dsh.bundle?
2. Does headless satisfy inject: ["shell"]? If not, is that the intended reason the bridge is inert there, and is there a supported profile for running it?
3. Would you consider surfacing unsatisfied injections at boot? A plugin that validates its config and then silently never activates is indistinguishable from one that is working, which for a hook bridge means a session that looks governed and is not.

Happy to test a patch or supply fuller logs.

[Mide69]

Checked your inject hypothesis against current master — it's half right, in a useful way.

Confirmed: packages/hooks/hooks-claude-code/src/index.ts:42 does declare export const inject = ['shell']. And docs/cordis-primer.md confirms the mechanism you guessed: "A plugin that names required services waits until those services exist" — an unsatisfied inject is a silent wait, not an error, which matches your exact symptom (validated config, zero activation, nothing on stdout/stderr/logger).

But: on Windows specifically, ctx.shell is not solely provided by dsh-bash-sandbox/dsh-tool-bash. In packages/bundle/base/cordis.patch.yml, both are disabled: !!js process.platform === 'win32', and dsh-pwsh-sandbox / dsh-tool-pwsh are mounted in their place (disabled: !!js process.platform !== 'win32'). Per packages/shell/shell/src/index.ts's own doc comment, this is deliberate — "the win32 layer swaps the... service registration... so the providers share one namespace" — i.e. pwsh-sandbox registers under the same ctx.shell key bash-sandbox would on POSIX. Since that entry lives in dsh-base (which every profile patches over first, per apps/cli/composition.md), headless on Windows should have ctx.shell satisfied by pwsh-sandbox before your --patch layer's hooks-claude-code entry even mounts.

So if ctx.shell really is the gate, something is preventing pwsh-sandbox specifically from registering in your exact composition — not a platform-wide gap. Worth checking --dump-config for whether pwsh-sandbox (not just bash-sandbox) shows up active, since I can't rule out an interaction between your --patch insert and the base bundle's win32 conditional from source reading alone. If it is present and the bridge still doesn't activate, that would falsify the inject theory entirely and point elsewhere.

Your third question (surfacing unsatisfied injections at boot) seems worth pursuing regardless of which explanation is right — "config-valid but silently inert forever" is a real diagnosability gap either way.

[argszero]

Verified against the current checkout (master @ 99f6f02fec, rc.7). This is a first-class report — it belongs in the loader-entry-lifecycle family, and the "no diagnostic channel" observation is the part that makes it undebuggable from outside. Answers to your three questions, then the mechanism I found.

Q1 — --patch insert activates through the exact same path as a bundle layer. No additional step exists.
composeProfile (apps/cli/src/profile-boot.ts:126-161) flattens bundlePatches + profile.patches + homePatches + overlays into ONE patch stack and applies it with the same applyEntryPatches call the bundles use (:152, composeEntries). Your inserted row lands in the same in-memory root tree as every bundle row. The only asymmetry: dsh plugin add's reconcile (apps/cli/src/plugin.ts:59-91) promotes a package into dsh.profile.bundles only when its manifest declares dsh.bundle.patch — hooks-claude-code is a plain plugin, so it's installed as a dependency with the "declares no dsh.bundle" warning, and the entry has to come from a patch. You did exactly that, so the mount is complete and should activate.

Q2 — your inject hypothesis is mechanistically real, but falsified as the cause on your own evidence.

• The gate exists: Plugin.Base.inject — "Services the plugin requires; it only loads while all are available" (vendor/cordis/src/registry.ts:105). A fiber whose injected services aren't all in the store sits INACTIVE until they appear (vendor/cordis/src/fiber.ts:610-620, _refresh() epoch).
• But on Windows your headless profile does provide ctx.shell — via pwsh-sandbox, not bash-sandbox. The base bundle platform-gates its shell rows: bash-sandbox is disabled: !!js process.platform === 'win32' (packages/bundle/base/cordis.patch.yml:180) and tool-bash likewise (:212); the active pair is pwsh-sandbox (:186, "Registers as ctx.shell") and tool-pwsh (:216). So your dump-config listing dsh-bash-sandbox is showing the disabled row.
• The decisive proof: tool-pwsh declares inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] (packages/shell/tool-pwsh/src/index.ts:49) — and your agent created hello.txt, so the tool that ran required ctx.shell and got it. ctx.shell was live; the bridge's inject: ['shell'] was satisfiable; the inertness has another cause.

Q3 — surfacing unsatisfied injections at boot: agreed, and the gap is worse than you thought — but only in one place.

• The loader's own apply/unload diagnostics go through this.ctx.root.logger?.(...) (vendor/loader/src/index.ts:172-174) — the ?. is total silence without a sink, and loader logs additionally require enableLogs on the include tree (vendor/include/src/index.ts:169,196, default false).
• dsh-base's cordis.patch.yml (78 rows) mounts no logger plugin — verified at source. hooks-claude-code's five warn paths (index.ts:111,114,176,179,213) all route through ctx.logger. So both layers of diagnostics for this exact failure mode (loader unload log + plugin warn) are invisible in shipped profiles.
• One correction: your logger-console insert test is inconclusive. cordis-plugin-logger-console prints nothing on its own activation — it only relays other plugins' logs through its formatter (vendor/logger-console/src/index.ts). Zero output doesn't prove it didn't activate; it proves nothing logged after it activated. And since --patch inserts land last (data.push in applyEntryPatches, vendor/include/src/index.ts:94), it activates after every bundle row already logged — nothing left to capture.

What I think is actually happening — two silent candidates, discriminated by one command:

1. The entry is disabled. The loader self-dispose path (vendor/loader/src/index.ts:146-156) marks fiber.entry.options.disabled = true and writes the tree when a fiber is disposed by loader behavior (inject checker, hot-reload). Platform/!!js gating can also carry it. An entry that is disabled still validates its config (your bad-configPath loud error proves validation runs) but never activates. This is exactly "resolved, applied, validated, inert".
2. Config-load failure with the warn dropped. apply()'s catch path (packages/hooks/hooks-claude-code/src/index.ts:113-115) warns and returns without registering — and with no logger sink that warn is invisible. If hooks.json isn't at the exact resolved path at boot time (cwd/anchoring), this is silent.

One command discriminates: dsh --profile headless --patch patch.yml --dump-config → does the cavesson-hooks row carry disabled: true? If yes, that's candidate 1 (and worth a separate report: the loader silently back-writes disabled onto entries, so a row that "looks fine" in dump-config can be persistently inert). If no, mount a logger to see candidate 2 — insert @deepseek-ai/cordis-plugin-logger-console first in the entry list (or set enableLogs: true on the include) so the loader's own "apply plugin cavesson-hooks" line becomes visible.

Family note. This is the 6th loader-entry-lifecycle report (with #1377/#1404/#1610/#2854/#2889): an entry that resolves and validates but is inert, with no observable channel to say why. The disabled: true back-write on self-dispose is the same silent-state-mutation class as #2854's shared-object mutation — a loader writing state into an entry the user never asked to change. If you confirm candidate 1, that back-write deserves its own thread.