A bad row in cordis.patch.yml doesn't disable a plugin — it stops the harness booting entirely

[taltara]

I hit this while building tooling that edits overlays, and I think it is worth stating plainly, because the failure is much larger than it looks.

I added a row naming a package that was not installed in the profile:

- insert:
    - id: probe
      name: '@example/not-installed'

I expected one dead entry that I could then inspect. What actually happens is ERR_MODULE_NOT_FOUND during boot, and the process exits. Not a degraded row - no harness at all. Which means:

• The Web UI is gone, so you cannot fix it in the Web UI.
• Anything that inspects a running tree cannot help you, because there is no running tree.
• The only way back is editing YAML by hand, or restoring a backup.

That is a sharp edge for a file people are encouraged to hand-edit, and it is the same shape as several boot incidents already reported here.

What I took from it

The check has to happen before the write, not after. In my own tooling I now verify that every inserted package is present in the profile before an overlay is written, and refuse the write otherwise - because after the write there is nothing left running to warn in.

Snapshotting the file before each write turned out to matter just as much. I bricked my own test harness twice while learning this, and the backup is what got it back.

Two things that might be worth considering upstream

Offered as questions rather than requests.

1. Could an unresolvable row fail that entry rather than the process? A plugin that cannot load is bad; a harness that will not start is worse, because it removes every tool you would otherwise use to diagnose it.
2. Would a dsh --profile <name> --check that validates an overlay without booting be welcome? There is clear appetite for a doctor command - discussion 💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics #1719 has 57 comments - and resolvability looks like the highest-value single check.

Either way, the behavior seems worth a line in the config docs. "A row naming a package you have not installed will prevent startup" is the sentence I wish I had read first.

[denial123789]

This failure mode is especially important for any UI-driven plugin store: the control plane that performs the install must not disappear before it can report or repair the failure.

I think the install contract needs to be transactional rather than treating overlay.yml as an ordinary config file:

1. Resolve/download the package before changing the active profile.
2. Inspect package.json, require dsh.bundle.patch, and parse the patch before applying it.
3. Verify every inserted module name against the dependency closure of the resulting profile.
4. Snapshot the profile, overlay, and bundle list.
5. Apply to a candidate profile and run a pre-boot validation. A command such as dsh --profile <name> --check would be very useful as the shared primitive here.
6. Start/health-probe the candidate; atomically promote it only on success, otherwise restore the snapshot.
7. Keep a CLI recovery path outside the Web UI and emit a sanitized audit receipt.

We have turned this into a concrete safety requirement for the open-source DSH Plugin Store: sandbaseai/dsh-plugin-store#6.

For transparency, the current Store is still a Preview. It validates catalog membership and invokes the DSH CLI with a fixed argument vector, but it does not yet claim the full preflight + health probe + automatic rollback guarantee above. The linked issue includes the expected regression evidence, and upstream input on a canonical offline --check contract would help avoid every installer inventing a different validator.

[denial123789]

I converted this failure mode into a source-pinned rc.8 recovery runbook: https://sandbaseai.github.io/deepseek-harness-handbook/invalid-overlay-boot-failure.html

Two details from the current launcher are especially useful when the Web control plane is already gone:

1. dsh --profile web --dump-default-config deliberately skips the profile user layer, the home-level user layer, and CLI overlays. It is the bundle-only recovery probe for a broken cordis.patch.yml.
2. A successful --dump-config proves offline parsing/composition only. It does not import an inserted module or prove lifecycle activation, so a real isolated boot remains a separate gate.

The runbook maps both persistent user-layer owners, preserves manifest/lock/layer evidence before reducing the implicated file to the valid empty array [], distinguishes an accidental raw insert from an intended bundle install, and includes a profile-root Node resolution probe. It also documents the cold-start versus live-HMR distinction: a rejected live candidate can retain the last good tree, while the same persisted bytes fail on restart because no prior tree exists.

For tooling that writes overlays, the proposed contract is resolve → parse → compose → snapshot → isolated boot + health probe → promote or restore. This stays fail-loud for missing policy/sandbox/persistence providers rather than treating every missing row as a safe degraded state.

Community-maintained operational guidance, not an upstream guarantee; all version-sensitive source links are pinned to 141eb6fef8.

[taltara]

@denial123789
Thank you - both of these are more useful than the original post.

The cold-start versus live-HMR distinction is the one that caught me. I had been treating a successful write as the end of the story, and "restart to load it" as a formality. It isn't: a running harness can reject a candidate and keep serving the tree it already has, so the write looks accepted, and the same bytes then fail from cold because there is no prior tree to fall back on. That is a worse failure than an immediate one, because the feedback arrives hours later and somewhere else. I have changed my tooling to say a restart is the real test rather than implying the write was it, and to point at --dump-default-config and the snapshot when it does not come back.

I had missed that --dump-default-config deliberately skips the user layers, so I confirmed it on rc.7 before repeating it: writing a uniquely-named row into a profile's cordis.patch.yml, --dump-config shows it and --dump-default-config does not. That is exactly the probe you want when the thing you would normally debug with is the thing that is gone, and it deserves to be in the config docs rather than discovered during an incident.

On your point that a successful --dump-config proves parse and compose only, not import or activation: agreed, and I can add a data point from the other side. My tooling refuses to write a row whose package is not present in the profile - a filesystem check against the profile's node_modules, not a resolve, because an ESM-only package that exports no require condition resolves fine for the loader and throws for a naive require.resolve. That catches the failure I actually hit, and it is strictly weaker than what you are describing. It says nothing about whether a resolvable module activates, or whether a missing provider leaves something pending forever. Those need a real boot, and I do not think any amount of static checking substitutes for one.

Which is why I think the --check primitive is the right ask, and worth being precise about what it would and would not promise. Three distinguishable gates, in increasing cost and confidence:

1. Parse and compose - what --dump-config already gives.
2. Resolvability of every inserted module against the resulting profile's dependency closure.
3. Isolated boot with a health probe - the only one that proves activation.

A canonical --check covering 1 and 2 would already remove most of the reinvention, and would let each installer be explicit about whether it claims 3. Your resolve → parse → compose → snapshot → isolated boot + health probe → promote or restore reads right to me, and the ordering matters as much as the steps: snapshot before the first mutation, not before the promote.

Two things I would add from building the write path, both learned by breaking my own harness:

Confine the writes. I own a marker-delimited block in cordis.patch.yml and nothing else, so hand-written rows, comments, and !!js expressions survive byte for byte. A config file that a tool takes ownership of is a config file people stop hand-editing, and then the recovery paths in your runbook stop being available to them.

Bind the review to the write. The preview issues a token over the exact proposed bytes and the revision they were computed against; applying without it is refused. It is a small thing, but it closes the window where a second tab or a hand edit changes what gets written after the human approved it - which in this domain means the difference between a reviewed change and an unreviewed one.

I would rather converge on your contract than ship a second validator with different semantics, so if the Store issue settles on a shape for the offline check I will match it. Fail-loud on missing policy, sandbox, and persistence providers rather than treating a missing row as a safe degraded state seems right to me too - the degraded state is not observable from inside a harness that did not start.

Thanks again for the reply 💪