Refuse root-config changes the config environment would undo, remove a dropped component's entry last, and release a scanner-held lock ticket

[dawsontoth]

A deploy or drop_component whose root config change HARPER_CONFIG or HARPER_SET_CONFIG would undo is now refused with a 409 before anything moves, where it used to report success and then be rewritten by the next config refresh. drop_component now removes the component's root config entry last and puts the tree back if the removal fails, so a failed drop no longer leaves a live component whose package, settings and isolation are gone. And a lock release whose ticket a Windows scanner is holding now completes, instead of leaving the ticket to read as a live holder. These are follow-ups to #2789 and #2796 (harper#2315 step 3), from kriszyp's review of them.

The first gap: with HARPER_SET_CONFIG forcing web.package, an activation of another package wrote its entry, and the refresh that follows the write put the forced package back. The activation still returned success and retired its journal, leaving the new release live under the old entry, so a later install could restore the old package; the same refresh could reintroduce an entry drop_component had just removed. The second: the drop removed the entry before the tree, so a failure to unlink the node_modules link or rename the tree rejected the drop after the entry was already gone. The third: the release read its ticket's owner before removing it, and a read refused by a scanner threw before the release-marker fallback #2796 added could run.

For the human reviewer

1. An effect the config environment would undo is refused, not published with a warning. HARPER_CONFIG and HARPER_SET_CONFIG reassert every key they name at each start and each config refresh, over the file and over edits to it. The pre-flight and the writer under the lock compose both together over the document they would write, as a refresh applies them, and refuse an effect they contradict: a declared key set to another value, or, for a payload deploy or a drop, a package a variable keeps. A start installs a component from its entry only when the entry names a package, so install options, credentials and settings such as isolated or host a variable keeps for the name reinstall nothing and do not block it; the integration harness passes suite config that way, and isolated-application.test.ts drops such a component. Each key is attributed to the variable that wins it, and the 409 names both the variable and the key. Keys a variable only adds beside the declared ones are no contradiction, so an operator-forced isolated: true stays beside a deploy's package. The alternative was to publish and warn that the environment wins; refusing means env-forced config can block a component's deploys everywhere that variable is set, Fabric included, until the variable changes. It is easy to relax.
2. HARPER_DEFAULT_CONFIG is caught only after the refresh. At runtime it fills in keys the file lacks, and whether it puts a removed key back depends on its state file: a key it once supplied reads as the user's once removed. Composing it without that state would refuse drops and payload deploys that do stick. So after its refresh the writer re-reads the file and throws a 409 if the effect no longer holds, refusing a document that no longer parses. It checks the file, not this thread's memoized view, because a worker applies the default in memory for keys the main thread would treat as removed by the user. For an activation that throw lands after the commit, so the journal is kept and the component fails closed until the conflict is resolved: a late failure, but a reversible choice.
3. drop_component removes the entry last, rather than journaling the drop. It refuses what the removal would refuse before anything moves, renames the tree aside with retireComponentDirectory, which flushes both parent directories before the entry's durable removal, and removes the entry. If the removal fails, the tree is renamed back while the file still holds the entry, a document that no longer parses counting as holding it. If the failure came in the refresh after the removal was written, the drop is finished instead. The window this leaves is a crash between the rename and the removal: the entry survives without its tree, the next start reinstalls a package component, and repeating the drop finishes it. The old order's crash left the tree live without its entry, which runs a component without its isolation. Journaling remove like the activation effects would close the window, at the cost of a journal format change.
4. The node_modules link is now cleanup after the entry, so failing to remove it no longer fails the drop. Its unlink is logged, and the drop completes with a dangling link. kriszyp's suggested check expected that failure to fail the drop with both halves intact. Nothing irreversible follows the link any more, though, and failing a drop whose entry and tree are already gone would report the wrong outcome.
5. A release whose ownership read is refused goes ahead with the token it holds. Only this acquisition publishes a ticket at a path its token names, so a record that is there but cannot be read (EACCES, EBUSY or EPERM) is still its own. The release then retries the unlink and falls back to the release marker as before. A readable record still gets the lost-ownership check. This rests on the token-named path, and it rides along here because it is the same review's follow-up; it reverts on its own.

How it works

Every root-config effect is now checked against the reasserting env layers twice. It is checked before it is written, where a refusal changes nothing, and it is re-checked in the file after the refresh that follows the write, which catches what composing those layers cannot predict.

flowchart TB
  eff["an effect: set, unset-package or remove"] --> comp["compose HARPER_CONFIG and HARPER_SET_CONFIG<br/>over the document about to be written"]
  comp --> q{"does the effect<br/>still hold?"}
  q -- no --> ref["409 naming the variable and keys:<br/>nothing written, nothing moved"]
  q -- yes --> write["write the entry durably,<br/>then refresh the config"]
  write --> q2{"does the file<br/>still hold it?"}
  q2 -- no --> err["409: the refresh undid it,<br/>e.g. HARPER_DEFAULT_CONFIG"]
  q2 -- yes --> ok["published"]
  classDef quiet fill:#eaf5ea,stroke:#4a8a4a,color:#1d3b1d
  class ref quiet

Loading

A drop now reaches its entry only after the tree is out of the way, and can walk that back. The rename is the one step that moves the live tree, and everything after the entry removal is cleanup.

flowchart TB
  subgraph before["Before"]
    direction LR
    b1["remove the entry"] --> b2["unlink the node_modules link"] --> b3["rename the tree aside"]
    b2 -. "fails" .-> bx["component live,<br/>entry gone"]
  end
  subgraph after["After"]
    direction LR
    a0{"pre-flight"} -- yes --> a1["rename the tree aside"] --> a2["remove the entry<br/>(the commit)"] --> a3["discard the tree,<br/>unlink the link (logged)"]
    a0 -- no --> an["refused,<br/>nothing moved"]
    a2 -. "fails" .-> ab["rename the tree back:<br/>tree and entry intact"]
  end
  before ~~~ after

Loading

Changes

• components/rootConfigPublication.ts: the env-layer check, what contradicts an effect and which variable sets a key, run by the pre-flight and the writer; the file check after the refresh; and hasRootConfigEntry for the drop.
• config/harperConfigEnvVars.ts: REASSERTING_CONFIG_ENV_VARS and composeReassertedEnvConfig, which shares composeConfigFromEnv's composition loop, so directive leaves and the base file's empty objects compose the same way.
• components/Application.ts: retireComponentDirectory moves a tree aside reversibly and durably, with restore() and a best-effort discard(). dropComponentDirectory is retire plus discard, for the legacy apps drop.
• components/operations.js: drop_component's new order, with the tree discarded and the link removed after the entry.
• components/componentPreparationLock.ts: the release's fallback for a record it cannot read. The Windows race where a claim read meets another contender's unlink is Retry a lock claim read that Windows refuses mid-unlink instead of failing the acquire #2803's, which main now has.
• components/DESIGN.md: the remove effect's order and crash window, the env-layer rule, and the release marker's owner, when a scanner hides the record.

Verification

End to end, a new suite in root-config-activation-effect.test.ts runs kriszyp's check for the first finding. It boots Harper with HARPER_SET_CONFIG forcing a component's package, which is how the harness passes a suite's config. It then deploys a different package, which answers 409 naming HARPER_SET_CONFIG and leaves the release and its entry as they were, and drops the component, which is refused and leaves it whole. The suite passes, 2 of 2, and the three deploy and drop integration files pass 40 of 40, as does isolated-application.test.ts, whose drop of a component a variable configures is what caught the over-strict first version of the drop rule.

• rootConfigPublication.test.js covers the refusal for each effect kind and both variables, a drop that neither settings nor install options and credentials without a package a variable keeps can block, a key HARPER_SET_CONFIG already sets to the declared value, a key a variable only adds, and the file check after the refresh, both a contradiction and a document that stops parsing. For the drop it covers a tree that cannot be moved, an entry that cannot be removed, which puts the tree back, a refresh that fails after the removal, which finishes the drop, a document that stops parsing, which keeps the tree, and a link that cannot be removed, which no longer fails the drop.
• componentPreparationLock.test.js releases a ticket whose record cannot be read at release, which is kriszyp's check for the third finding, with a mode the owner cannot read standing in for the scanner on POSIX. On macOS it publishes the marker when the record can be neither read nor removed, and the next holder then acquires. On Windows, a handle opened with libuv's UV_FS_O_EXLOCK, which shares nothing, is held through the release: the release publishes the marker, and once the handle closes the next holder acquires, which is the Windows check kriszyp described.
• deployStageActivate.test.js refuses an activation a variable would undo before anything moves, and harperConfigEnvVars-compose.test.js pins the composition.
• Every new unit test except the two no-contradiction cases fails against the code before it, and those two pass on both, as guards. Against Publish a component's root config entry only once its deploy goes live #2789's head that is eight in rootConfigPublication.test.js and the activation case, and the review fixes and the release fallback were checked the same way against this branch's first commit.

Gates, run locally on macOS with Node 24 at c24777a38, with HOME naming a sentinel home, whose boot properties point at a throwaway install, and a fresh short TMPDIR. The last commit's changes ran in the affected suites (347 pass).

Gate	This branch	main
test:unit:main	5879 pass, 26 fail	the same 26 fail
root-config-activation-effect, stage-then-activate, components.test.mjs	40 pass

• The unit failures are the same 26 by name as on main. They are environment-specific on this Mac: /private/var realpath comparisons, the shell's git-credential environment, git-reference fixtures that fail under a swapped HOME, the uWS UDS adapter, and process-group reclaim ordering. applicationSpawn.test.js is excluded because it wedges locally, on main too.
• The sentinel install is byte-identical after every run.
• Formatting, lint, the type check and the design-docs check are clean on every changed file.

Complexity: complicated

_{Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-kimi,cursor-muse; rounds=3; full=1 @ 34265c6}

_{Human-Review-Need: 3 (decisions: env-contradiction-refuse-vs-warn, drop-allows-env-settings-residue, drop-rename-before-entry, default-config-backstop-only, windows-lock-changes-in-this-branch) @ d25dbaf}

[gemini-code-assist]

Code Review

This pull request refactors the component drop and deployment process to ensure transactional safety and prevent inconsistent states during failures. It introduces a reversible directory retirement mechanism (retireComponentDirectory) and adds pre-flight checks to refuse configuration changes that would be overridden by environment variables like HARPER_CONFIG or HARPER_SET_CONFIG. Additionally, it improves lock release resilience when lock files cannot be read. The review feedback suggests using optional chaining (error?.code) when handling caught errors in components/operations.js to safely check error properties and prevent secondary TypeErrors.

[claude]

Reviewed; no blockers found.

[kriszyp]

_{🤖 Reviewed with Codex}

[kriszyp]

On POSIX, renaming a directory requires write permission on its source and destination parent directories; making the source directory 0o555 does not block the rename at components/Application.ts:3496. On non-root Linux, this drop can proceed instead of producing the EACCES/EPERM asserted below. Could this test make the components root unwritable after pre-creating the lock and aside directories, then restore its mode in finally, or use another deterministic rename failure? I could not run the file-writing test in this read-only checkout; a focused non-root Linux run would confirm the failure and the replacement setup.