From b7a53e39036dc9c1687fa9d0228fd5b3ea290baa Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Tue, 28 Jul 2026 21:48:41 +0700
Subject: [PATCH 01/11] fix(dashmate)!: stop read-only commands rewriting
 config and clobbering concurrent updates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Config`'s constructor delegated to `setOptions()`, which marks the config
changed, so every config was dirty the moment it was read off disk.
`BaseCommand.finally()` persists the whole config file whenever anything is
dirty, so every successful command — including pure readers like `config get`
and `core cli` — rewrote `config.json` from its own load-time snapshot.

That turns any overlapping pair of commands into a lost update: a reader loads
at T0, `config set` writes and exits 0 at T1, and the reader writes its stale
snapshot at T2. The setting silently reverts even though `config set` reported
success. It is invisible in single-process use because re-serializing an
unchanged config is byte-identical.

- Hydrating a config no longer marks it changed. Callers that build a config
  which must reach disk already mark it explicitly.
- Rendering service templates no longer clears persistence state; the
  repository clears it, and only after the write actually succeeds.
- Writes are atomic (`write-file-atomic`, preserving file mode — `config.json`
  holds masternode keys, RPC passwords and SSL API keys).
- A write is refused when the file changed on disk since it was read, under a
  short `proper-lockfile` lock held only across compare-and-replace, never for
  the duration of a command. The refused state is parked next to `config.json`
  so material generated during the command is never lost.

The lock is cooperative and scoped to local filesystems; both limits are
documented for operators.

BREAKING CHANGE: a command that would have silently overwritten a concurrent
configuration change now fails with a non-zero exit and
`ConfigFileConflictError`. Automation that relied on the previous
last-writer-wins behaviour will now see failures where it previously saw
silent data loss.

Tests would have caught this in CI:
  hydrated config is clean                    ✖ before → ✔ after
  stale write refused, not clobbering         ✖ before → ✔ after
  concurrent first-run write refused          ✖ before → ✔ after
  deleted config file not resurrected         ✖ before → ✔ after
  saved flags cascade only after a write      ✖ before → ✔ after
  waits for a lock held by another process    ✖ before → ✔ after

The lock test spawns a real second process and fails without the lock (write
completes in 13ms instead of waiting 700ms), so it pins the lock rather than
the staleness comparison.

Closes #4242

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .pnp.cjs                                      |  23 +-
 ...ckfile-npm-4.1.2-a140a3c928-000a4875f5.zip | Bin 0 -> 10872 bytes
 ...atomic-npm-5.0.1-52283db6ee-648efddba5.zip | Bin 0 -> 5454 bytes
 packages/dashmate/docs/config/index.md        |  49 +++
 packages/dashmate/package.json                |   4 +-
 packages/dashmate/scripts/helper.js           |   8 +-
 packages/dashmate/src/config/Config.js        |   8 +-
 .../configFile/ConfigFileJsonRepository.js    | 163 ++++++++-
 .../config/errors/ConfigFileConflictError.js  |  49 +++
 .../dashmate/src/oclif/command/BaseCommand.js |  19 +-
 .../templates/writeConfigTemplatesFactory.js  |   2 -
 .../dashmate/test/unit/config/Config.spec.js  |  37 ++
 .../ConfigFileJsonRepository.spec.js          | 342 ++++++++++++++++++
 yarn.lock                                     |  23 ++
 14 files changed, 707 insertions(+), 20 deletions(-)
 create mode 100644 .yarn/cache/proper-lockfile-npm-4.1.2-a140a3c928-000a4875f5.zip
 create mode 100644 .yarn/cache/write-file-atomic-npm-5.0.1-52283db6ee-648efddba5.zip
 create mode 100644 packages/dashmate/src/config/errors/ConfigFileConflictError.js
 create mode 100644 packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js

diff --git a/.pnp.cjs b/.pnp.cjs
index 062aa0f7409..f2c82efb91a 100755
--- a/.pnp.cjs
+++ b/.pnp.cjs
@@ -9698,6 +9698,7 @@ const RAW_RUNTIME_STATE =
           ["oclif", "npm:4.0.3"],\
           ["pretty-bytes", "npm:5.6.0"],\
           ["pretty-ms", "npm:7.0.1"],\
+          ["proper-lockfile", "npm:4.1.2"],\
           ["public-ip", "npm:6.0.1"],\
           ["qs", "npm:6.15.0"],\
           ["rxjs", "npm:6.6.7"],\
@@ -9707,7 +9708,8 @@ const RAW_RUNTIME_STATE =
           ["systeminformation", "npm:5.31.1"],\
           ["table", "npm:6.8.1"],\
           ["tar", "npm:7.5.10"],\
-          ["wrap-ansi", "npm:7.0.0"]\
+          ["wrap-ansi", "npm:7.0.0"],\
+          ["write-file-atomic", "npm:5.0.1"]\
         ],\
         "linkType": "SOFT"\
       }]\
@@ -18295,6 +18297,16 @@ const RAW_RUNTIME_STATE =
           ["signal-exit", "npm:3.0.7"]\
         ],\
         "linkType": "HARD"\
+      }],\
+      ["npm:4.1.2", {\
+        "packageLocation": "./.yarn/cache/proper-lockfile-npm-4.1.2-a140a3c928-000a4875f5.zip/node_modules/proper-lockfile/",\
+        "packageDependencies": [\
+          ["graceful-fs", "npm:4.2.10"],\
+          ["proper-lockfile", "npm:4.1.2"],\
+          ["retry", "npm:0.12.0"],\
+          ["signal-exit", "npm:3.0.7"]\
+        ],\
+        "linkType": "HARD"\
       }]\
     ]],\
     ["protobufjs", [\
@@ -23536,6 +23548,15 @@ const RAW_RUNTIME_STATE =
           ["write-file-atomic", "npm:4.0.1"]\
         ],\
         "linkType": "HARD"\
+      }],\
+      ["npm:5.0.1", {\
+        "packageLocation": "./.yarn/cache/write-file-atomic-npm-5.0.1-52283db6ee-648efddba5.zip/node_modules/write-file-atomic/",\
+        "packageDependencies": [\
+          ["imurmurhash", "npm:0.1.4"],\
+          ["signal-exit", "npm:4.1.0"],\
+          ["write-file-atomic", "npm:5.0.1"]\
+        ],\
+        "linkType": "HARD"\
       }]\
     ]],\
     ["ws", [\
diff --git a/.yarn/cache/proper-lockfile-npm-4.1.2-a140a3c928-000a4875f5.zip b/.yarn/cache/proper-lockfile-npm-4.1.2-a140a3c928-000a4875f5.zip
new file mode 100644
index 0000000000000000000000000000000000000000..a7389ae2254e451f1b1c32d2d47216d0060b9216
GIT binary patch
literal 10872
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

literal 0
HcmV?d00001

diff --git a/.yarn/cache/write-file-atomic-npm-5.0.1-52283db6ee-648efddba5.zip b/.yarn/cache/write-file-atomic-npm-5.0.1-52283db6ee-648efddba5.zip
new file mode 100644
index 0000000000000000000000000000000000000000..4b1680c8f312504b3ec0c7db9bebac9744290436
GIT binary patch
literal 5454
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

literal 0
HcmV?d00001

diff --git a/packages/dashmate/docs/config/index.md b/packages/dashmate/docs/config/index.md
index a81ac218c61..a9c7502569c 100644
--- a/packages/dashmate/docs/config/index.md
+++ b/packages/dashmate/docs/config/index.md
@@ -179,3 +179,52 @@ dashmate config get <option>
 # Enable debug logging
 dashmate config set core.log.debug.enabled true
 ```
+
+## Running Dashmate commands concurrently
+
+Dashmate keeps all configuration in a single `config.json` inside its home directory
+(`~/.dashmate` by default), and a command that changes configuration rewrites that whole
+file when it exits.
+
+To keep two overlapping commands from silently reverting each other, a command refuses to
+save when `config.json` changed on disk after that command loaded it:
+
+```
+'/home/user/.dashmate/config.json' was modified by another process after this command
+loaded it. Refusing to overwrite it. The changes from this command were saved to
+'/home/user/.dashmate/config.json.rejected-2026-07-28T09-14-22-031Z-4711-1' so you can
+reconcile them.
+```
+
+The command exits non-zero and the other process's change is kept. Nothing is lost — the
+configuration this command wanted to save is written to the `.rejected-*` file named in
+the message, so you can compare it and reapply what you need. These files are never
+cleaned up automatically; remove them once you have reconciled them.
+
+How to respond depends on the command:
+
+- `dashmate config set` — reload and run it again. Nothing else happened.
+- `dashmate config create`, `remove`, `default` — re-check your assumptions before
+  retrying. The other process may have created or removed the very configuration you were
+  operating on.
+- `dashmate setup`, `reset`, `start`, `ssl obtain` — **the operational work already
+  happened**; only saving the configuration failed. Containers may be running and
+  certificates may have been issued. Reconcile from the `.rejected-*` file rather than
+  simply re-running the command.
+
+Read-only commands such as `dashmate config get`, `dashmate status` and `dashmate core
+cli` never write configuration and are always safe to run alongside anything else.
+
+### Limits of this guarantee
+
+- **All Dashmate instances must be on a version that has this behaviour.** The
+  coordination is cooperative, so an older Dashmate process — including a long-running
+  helper started before an upgrade — can still overwrite a newer one. After upgrading,
+  restart the node so the helper restarts too.
+- **Local filesystems only.** The guarantee is not claimed for a Dashmate home directory
+  on NFS or another network filesystem.
+- **Only Dashmate processes take part in this.** A hand edit made while a long Dashmate
+  command is running is usually detected and the command refuses rather than discarding it
+  — but a text editor does not take the lock, so an edit saved in the moment between
+  Dashmate re-reading the file and replacing it can still be overwritten. Stop Dashmate
+  commands before editing `config.json` by hand if the edit matters.
diff --git a/packages/dashmate/package.json b/packages/dashmate/package.json
index 6ed77abc9a8..ef87ee31750 100644
--- a/packages/dashmate/package.json
+++ b/packages/dashmate/package.json
@@ -87,6 +87,7 @@
     "node-graceful": "^3.0.1",
     "pretty-bytes": "^5.3.0",
     "pretty-ms": "^7.0.0",
+    "proper-lockfile": "^4.1.2",
     "public-ip": "^6.0.1",
     "qs": "^6.14.2",
     "rxjs": "^6.6.7",
@@ -94,7 +95,8 @@
     "systeminformation": "^5.31.1",
     "table": "^6.8.1",
     "tar": "7.5.10",
-    "wrap-ansi": "^7.0.0"
+    "wrap-ansi": "^7.0.0",
+    "write-file-atomic": "^5.0.1"
   },
   "devDependencies": {
     "@babel/core": "^7.26.10",
diff --git a/packages/dashmate/scripts/helper.js b/packages/dashmate/scripts/helper.js
index 484a67558a8..4010c3d01ee 100644
--- a/packages/dashmate/scripts/helper.js
+++ b/packages/dashmate/scripts/helper.js
@@ -95,12 +95,12 @@ async function removeOrphanedSslContainers(docker) {
   // Persist config if it was migrated
   if (configFile.isChanged()) {
     await configFileRepository.write(configFile);
-
-    configFile.getAllConfigs()
-      .filter((config) => config.isChanged())
-      .forEach(writeConfigTemplates);
   }
 
+  // Rendered artifacts rather than persisted state - always brought up to date
+  // with this Dashmate's templates, whether or not the configuration changed.
+  configFile.getAllConfigs().forEach(writeConfigTemplates);
+
   const config = configFile.getConfig(configName);
 
   // Register config collection in the container
diff --git a/packages/dashmate/src/config/Config.js b/packages/dashmate/src/config/Config.js
index 7e13e6e8a8b..a84978f5c96 100644
--- a/packages/dashmate/src/config/Config.js
+++ b/packages/dashmate/src/config/Config.js
@@ -39,9 +39,15 @@ export default class Config {
     assertSafeConfigName(name);
 
     this.name = name;
-    this.changed = false;
 
     this.setOptions(options, skipValidation);
+
+    // Hydration is not a mutation. setOptions() marks the config changed because
+    // it is a genuine edit when called on an existing config, but a config that
+    // was just loaded has nothing unsaved. Callers that build a config which must
+    // reach disk - the default set for a new config file, createConfig() - mark it
+    // changed themselves.
+    this.changed = false;
   }
 
   /**
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index 528fedf3fd2..d9eb828545f 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -1,14 +1,75 @@
 import fs from 'fs';
 import Ajv from 'ajv';
 import path from 'path';
+import lockfile from 'proper-lockfile';
+import writeFileAtomic from 'write-file-atomic';
 import Config from '../Config.js';
 import { PACKAGE_ROOT_DIR } from '../../constants.js';
 import ConfigFileNotFoundError from '../errors/ConfigFileNotFoundError.js';
 import InvalidConfigFileFormatError from '../errors/InvalidConfigFileFormatError.js';
+import ConfigFileConflictError from '../errors/ConfigFileConflictError.js';
 import configFileJsonSchema from './configFileJsonSchema.js';
 import ConfigFile from './ConfigFile.js';
 
+/**
+ * How long a lock may go un-refreshed before another process may break it.
+ * Comfortably longer than the milliseconds the lock is actually held, so a busy
+ * event loop cannot get its live lock stolen, but short enough that a process
+ * killed while holding it does not block the next command for long.
+ */
+const LOCK_STALE_MS = 10000;
+
+/**
+ * Waiting is synchronous, which means signal handlers do not run while it is in
+ * progress. Kept just above the stale threshold - long enough to outlast a dead
+ * holder's lock, short enough that Ctrl-C is never ignored for long.
+ */
+const LOCK_ACQUIRE_TIMEOUT_MS = LOCK_STALE_MS + 2000;
+
+const LOCK_RETRY_INTERVAL_MS = 50;
+
+/**
+ * Block without spinning. The write path is synchronous, so there is no event
+ * loop to yield to here.
+ *
+ * @param {number} ms
+ */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 export default class ConfigFileJsonRepository {
+  /**
+   * What this instance last observed on disk:
+   *
+   * - `undefined` - never looked, so nothing can be claimed about the file
+   * - `null`      - looked, and there was no file
+   * - `string`    - the exact bytes that were there
+   *
+   * "Never looked" and "looked and found nothing" have to stay distinct, or two
+   * nodes being set up concurrently would both write over each other believing
+   * they were creating the file.
+   *
+   * Concurrent writers are detected by comparing against this, so it must be
+   * refreshed on every successful write - the dashmate helper reads once at
+   * startup and then writes on every certificate renewal for the life of the
+   * process, and would otherwise conflict with its own previous write.
+   *
+   * One instance tracks one config file lifecycle: a second read() rebaselines
+   * it, so do not write a ConfigFile obtained from an earlier read afterwards.
+   *
+   * @type {string|null|undefined}
+   */
+  #baseline;
+
+  /**
+   * Distinguishes parked snapshots written by this process within the same
+   * millisecond.
+   *
+   * @type {number}
+   */
+  #rejectedCount = 0;
+
   /**
    * @param {migrateConfigFile} migrateConfigFile
    * @param {HomeDir} homeDir
@@ -17,6 +78,9 @@ export default class ConfigFileJsonRepository {
     this.migrateConfigFile = migrateConfigFile;
     this.ajv = new Ajv();
     this.configFilePath = homeDir.joinPath('config.json');
+    // Locking a sibling rather than the config file itself keeps first run
+    // working, where there is no config file to lock yet.
+    this.lockFilePath = homeDir.joinPath('config.json.lock');
   }
 
   /**
@@ -29,11 +93,18 @@ export default class ConfigFileJsonRepository {
   read(options = {}) {
     const { skipValidation = false } = options;
     if (!fs.existsSync(this.configFilePath)) {
+      // Record that the file was observed absent. The caller creates a default
+      // config file from here, and that write must still lose to another
+      // process that created one first.
+      this.#baseline = null;
+
       throw new ConfigFileNotFoundError(this.configFilePath);
     }
 
     const configFileJSON = fs.readFileSync(this.configFilePath, 'utf8');
 
+    this.#baseline = configFileJSON;
+
     let configFileData;
     try {
       configFileData = JSON.parse(configFileJSON);
@@ -87,14 +158,100 @@ export default class ConfigFileJsonRepository {
   /**
    * Save configs to file
    *
+   * Refuses to write when the file changed on disk since this instance read it,
+   * rather than reverting whatever the other process saved. The check and the
+   * replacement happen under a lock so two writers cannot both pass the check
+   * and then both write; the lock is held only for that, never for the duration
+   * of a command.
+   *
    * @param {ConfigFile} configFile
+   * @throws {ConfigFileConflictError} when another process wrote first
    * @returns {void}
    */
   write(configFile) {
-    const configFileJSON = JSON.stringify(configFile.toObject(), undefined, 2);
+    const configFileJSON = `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`;
+
+    const release = this.#acquireLock();
+
+    try {
+      const currentJSON = fs.existsSync(this.configFilePath)
+        ? fs.readFileSync(this.configFilePath, 'utf8')
+        : null;
+
+      // Any observed change conflicts, including present-to-absent: recreating
+      // a config file somebody deliberately removed is the same lost update in
+      // the other direction.
+      if (this.#baseline !== undefined && currentJSON !== this.#baseline) {
+        throw this.#rejectStaleWrite(configFileJSON);
+      }
 
-    configFile.markAsSaved();
+      writeFileAtomic.sync(this.configFilePath, configFileJSON, 'utf8');
+
+      this.#baseline = configFileJSON;
+
+      // Only now is the state actually on disk. Clearing these before the write
+      // would leave the configs claiming to be saved after a failed one.
+      configFile.markAsSaved();
+      configFile.getAllConfigs().forEach((config) => config.markAsSaved());
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Take the config file lock, waiting out a concurrent writer.
+   *
+   * proper-lockfile's sync API has no built-in retry, and failing on the first
+   * contended attempt would surface a spurious error for a lock that is only
+   * held for a rename.
+   *
+   * @returns {function} release
+   */
+  #acquireLock() {
+    const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS;
+
+    for (;;) {
+      try {
+        return lockfile.lockSync(this.configFilePath, {
+          lockfilePath: this.lockFilePath,
+          // The config file legitimately does not exist on first run, and
+          // realpath resolution would fail on it.
+          realpath: false,
+          stale: LOCK_STALE_MS,
+        });
+      } catch (e) {
+        if (e.code !== 'ELOCKED' || Date.now() >= deadline) {
+          throw e;
+        }
+
+        sleepSync(LOCK_RETRY_INTERVAL_MS);
+      }
+    }
+  }
+
+  /**
+   * Park the state we refused to write, so material generated during the
+   * command is recoverable, and describe where it went.
+   *
+   * @param {string} configFileJSON
+   * @returns {ConfigFileConflictError}
+   */
+  #rejectStaleWrite(configFileJSON) {
+    // Colons are not legal in Windows filenames. The pid separates concurrent
+    // processes and the counter separates two conflicts from this one inside
+    // the same millisecond, so no parked state is ever overwritten by another.
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+
+    this.#rejectedCount += 1;
+
+    const rejectedPath = `${this.configFilePath}.rejected-${stamp}-${process.pid}-${this.#rejectedCount}`;
+
+    try {
+      writeFileAtomic.sync(rejectedPath, configFileJSON, { encoding: 'utf8', mode: 0o600 });
+    } catch (e) {
+      return new ConfigFileConflictError(this.configFilePath, null, e);
+    }
 
-    fs.writeFileSync(this.configFilePath, `${configFileJSON}\n`, 'utf8');
+    return new ConfigFileConflictError(this.configFilePath, rejectedPath);
   }
 }
diff --git a/packages/dashmate/src/config/errors/ConfigFileConflictError.js b/packages/dashmate/src/config/errors/ConfigFileConflictError.js
new file mode 100644
index 00000000000..3b3c58ceae3
--- /dev/null
+++ b/packages/dashmate/src/config/errors/ConfigFileConflictError.js
@@ -0,0 +1,49 @@
+import AbstractError from '../../errors/AbstractError.js';
+
+/**
+ * Raised when the config file changed on disk after this process loaded it.
+ *
+ * Writing would silently revert whatever the other process saved, so the write
+ * is refused. The in-memory state is parked next to the config file first, so
+ * material generated during the command - operator keys, a spork key, a miner
+ * address - is never lost with the refused write.
+ */
+export default class ConfigFileConflictError extends AbstractError {
+  /**
+   * @param {string} configFilePath
+   * @param {string|null} rejectedSnapshotPath - null when parking it also failed
+   * @param {Error} [snapshotError] - why parking failed, when it did
+   */
+  constructor(configFilePath, rejectedSnapshotPath, snapshotError = undefined) {
+    const recovery = rejectedSnapshotPath === null
+      ? `The changes from this command could NOT be saved either: ${snapshotError?.message}. They are lost.`
+      : `The changes from this command were saved to '${rejectedSnapshotPath}' so you can reconcile them.`;
+
+    super(`'${configFilePath}' was modified by another process after this command loaded it.`
+      + ` Refusing to overwrite it. ${recovery}`);
+
+    this.configFilePath = configFilePath;
+    this.rejectedSnapshotPath = rejectedSnapshotPath;
+    this.snapshotError = snapshotError;
+
+    // Stable identifier for callers that need to branch on this without
+    // depending on the class identity across module instances.
+    this.code = 'DASHMATE_CONFIG_FILE_CONFLICT';
+  }
+
+  /**
+   * @returns {string}
+   */
+  getConfigFilePath() {
+    return this.configFilePath;
+  }
+
+  /**
+   * Path the refused state was parked at, or null if that failed too.
+   *
+   * @returns {string|null}
+   */
+  getRejectedSnapshotPath() {
+    return this.rejectedSnapshotPath;
+  }
+}
diff --git a/packages/dashmate/src/oclif/command/BaseCommand.js b/packages/dashmate/src/oclif/command/BaseCommand.js
index 3fa7d2c0313..28ee0d9b15e 100644
--- a/packages/dashmate/src/oclif/command/BaseCommand.js
+++ b/packages/dashmate/src/oclif/command/BaseCommand.js
@@ -112,16 +112,19 @@ export default class BaseCommand extends Command {
 
         if (configFile.isChanged()) {
           configFileRepository.write(configFile);
+        }
 
-          /**
-           * @var {writeConfigTemplates} writeConfigTemplates
-           */
-          const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
+        // Service templates are rendered artifacts, not persisted state, and are
+        // rewritten on every command regardless of whether the configuration
+        // changed. Rendering only on change would leave a node running templates
+        // from an older Dashmate whenever a release edits a template without
+        // also changing the config format version.
+        /**
+         * @var {writeConfigTemplates} writeConfigTemplates
+         */
+        const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
 
-          configFile.getAllConfigs()
-            .filter((config) => config.isChanged())
-            .forEach(writeConfigTemplates);
-        }
+        configFile.getAllConfigs().forEach(writeConfigTemplates);
       }
 
       // Stop all running containers
diff --git a/packages/dashmate/src/templates/writeConfigTemplatesFactory.js b/packages/dashmate/src/templates/writeConfigTemplatesFactory.js
index 1684e61f2fb..c1b33df6cce 100644
--- a/packages/dashmate/src/templates/writeConfigTemplatesFactory.js
+++ b/packages/dashmate/src/templates/writeConfigTemplatesFactory.js
@@ -9,8 +9,6 @@ export default function writeConfigTemplatesFactory(renderServiceTemplates, writ
   function writeConfigTemplates(config) {
     const serviceConfigs = renderServiceTemplates(config);
     writeServiceConfigs(config.getName(), serviceConfigs);
-
-    config.markAsSaved();
   }
 
   return writeConfigTemplates;
diff --git a/packages/dashmate/test/unit/config/Config.spec.js b/packages/dashmate/test/unit/config/Config.spec.js
index b5d652dd678..13705cf2286 100644
--- a/packages/dashmate/test/unit/config/Config.spec.js
+++ b/packages/dashmate/test/unit/config/Config.spec.js
@@ -13,6 +13,43 @@ describe('Config', () => {
     });
   });
 
+  describe('change tracking', () => {
+    let storedOptions;
+
+    beforeEach(() => {
+      storedOptions = getBaseConfigFactory(HomeDir.createTemp())().getStoredOptions();
+    });
+
+    // Loading a config off disk is not an edit to it. When hydration marks a
+    // config dirty, every command - including pure readers like `config get` -
+    // persists the whole config file on exit, and a slow reader can write its
+    // stale snapshot over a concurrent `config set`.
+    it('should not consider a freshly hydrated config changed', () => {
+      const config = new Config('testnet', storedOptions);
+
+      expect(config.isChanged()).to.be.false();
+    });
+
+    it('should consider a config changed after set()', () => {
+      const config = new Config('testnet', storedOptions);
+
+      config.set('description', 'changed');
+
+      expect(config.isChanged()).to.be.true();
+    });
+
+    // setOptions() is a genuine mutation when called on an existing config
+    // (resetNodeTaskFactory restores defaults through it), so only the
+    // constructor's initial hydration is exempt.
+    it('should consider a config changed after setOptions() post-construction', () => {
+      const config = new Config('testnet', storedOptions);
+
+      config.setOptions(storedOptions);
+
+      expect(config.isChanged()).to.be.true();
+    });
+  });
+
   describe('.isSchemaPathAllowed', () => {
     // The bug that triggered this method: `dashmate config set
     // platform.drive.abci.docker.build.buildArgs.SDK_TEST_DATA true`
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
new file mode 100644
index 00000000000..2bf4728ad31
--- /dev/null
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -0,0 +1,342 @@
+import fs from 'fs';
+import { spawn } from 'child_process';
+import { expect } from 'chai';
+import HomeDir from '../../../../src/config/HomeDir.js';
+import getBaseConfigFactory from '../../../../configs/defaults/getBaseConfigFactory.js';
+import ConfigFile from '../../../../src/config/configFile/ConfigFile.js';
+import ConfigFileJsonRepository from '../../../../src/config/configFile/ConfigFileJsonRepository.js';
+
+const CURRENT_FORMAT_VERSION = '4.1.0';
+
+describe('ConfigFileJsonRepository', () => {
+  let homeDir;
+  let configFilePath;
+  let identityMigration;
+
+  /**
+   * Seed a valid config file on disk, the way a configured node would have one.
+   *
+   * @return {string} the JSON written
+   */
+  function seedConfigFile() {
+    const baseConfig = getBaseConfigFactory(homeDir)();
+
+    const configFile = new ConfigFile(
+      [baseConfig],
+      CURRENT_FORMAT_VERSION,
+      'abcdef12',
+      'base',
+      null,
+    );
+
+    const json = `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`;
+
+    fs.writeFileSync(configFilePath, json, 'utf8');
+
+    return json;
+  }
+
+  beforeEach(() => {
+    homeDir = HomeDir.createTemp();
+    configFilePath = homeDir.joinPath('config.json');
+    identityMigration = (data) => data;
+  });
+
+  afterEach(() => {
+    homeDir.remove();
+  });
+
+  describe('#read', () => {
+    // A load is not an edit. If hydration leaves the file dirty, BaseCommand
+    // persists it on exit even for `config get`, which is what lets a slow
+    // reader overwrite a concurrent `config set`.
+    it('should return a clean config file when nothing was migrated', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+
+      const configFile = repository.read();
+
+      expect(configFile.isChanged()).to.be.false();
+      expect(configFile.getAllConfigs().filter((config) => config.isChanged())).to.be.empty();
+    });
+
+    it('should return a changed config file when it was migrated', () => {
+      seedConfigFile();
+
+      const migration = (data) => ({ ...data, configFormatVersion: '9.9.9' });
+
+      const repository = new ConfigFileJsonRepository(migration, homeDir);
+
+      const configFile = repository.read();
+
+      expect(configFile.isChanged()).to.be.true();
+      expect(configFile.getAllConfigs().every((config) => config.isChanged())).to.be.true();
+    });
+
+    // The symptom operators reported. Asserting on file CONTENT would pass
+    // against the buggy code, because re-serializing an unchanged config is
+    // byte-identical - the defect is that the write happens at all, carrying a
+    // stale snapshot.
+    it('should leave the file untouched when a read-only command exits', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const { mtimeMs, ino } = fs.statSync(configFilePath);
+
+      const configFile = repository.read();
+
+      // What BaseCommand.finally() does
+      if (configFile.isChanged()) {
+        repository.write(configFile);
+      }
+
+      const after = fs.statSync(configFilePath);
+
+      expect(after.mtimeMs).to.equal(mtimeMs);
+      expect(after.ino).to.equal(ino);
+    });
+  });
+
+  describe('#write', () => {
+    it('should persist changes and mark the config file and its configs saved', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const configFile = repository.read();
+
+      configFile.getConfig('base').set('description', 'changed');
+
+      repository.write(configFile);
+
+      expect(configFile.isChanged()).to.be.false();
+      expect(configFile.getAllConfigs().filter((config) => config.isChanged())).to.be.empty();
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('changed');
+    });
+
+    it('should preserve the file mode, valid JSON and trailing newline, and leave no temp files', () => {
+      seedConfigFile();
+      fs.chmodSync(configFilePath, 0o600);
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const configFile = repository.read();
+
+      configFile.getConfig('base').set('description', 'changed');
+
+      repository.write(configFile);
+
+      const raw = fs.readFileSync(configFilePath, 'utf8');
+
+      // eslint-disable-next-line no-bitwise
+      expect(fs.statSync(configFilePath).mode & 0o777).to.equal(0o600);
+      expect(raw.endsWith('}\n')).to.be.true();
+      expect(() => JSON.parse(raw)).to.not.throw();
+      expect(fs.readdirSync(homeDir.getPath()).filter((n) => n !== 'config.json')).to.be.empty();
+    });
+
+    // The helper daemon reads once at startup and writes on every certificate
+    // renewal for the life of the process. If the staleness baseline is not
+    // refreshed after each write, its second write conflicts with its own first.
+    it('should allow repeated writes from one long-lived instance', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const configFile = repository.read();
+
+      configFile.getConfig('base').set('description', 'first');
+      repository.write(configFile);
+
+      configFile.getConfig('base').set('description', 'second');
+
+      expect(() => repository.write(configFile)).to.not.throw();
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('second');
+    });
+  });
+
+  describe('#write concurrency', () => {
+    // The reported lost update: a process loads the config, another process
+    // changes and saves it, and the first process writes its stale snapshot
+    // last. Asserting only "the second value survived" would also pass if the
+    // stale write silently did nothing, so the contract itself is pinned:
+    // it refuses loudly, leaves the file alone, and keeps the rejected state.
+    it('should refuse a stale write instead of clobbering a concurrent update', () => {
+      seedConfigFile();
+
+      const slowReader = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const staleConfigFile = slowReader.read();
+
+      // A concurrent `dashmate config set` lands and exits successfully
+      const writer = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const freshConfigFile = writer.read();
+      freshConfigFile.getConfig('base').set('description', 'set-by-concurrent-writer');
+      writer.write(freshConfigFile);
+
+      const onDisk = fs.readFileSync(configFilePath, 'utf8');
+
+      staleConfigFile.getConfig('base').set('description', 'stale-snapshot');
+
+      let thrown;
+      try {
+        slowReader.write(staleConfigFile);
+      } catch (e) {
+        thrown = e;
+      }
+
+      expect(thrown, 'stale write must not succeed').to.exist();
+      expect(thrown.code).to.equal('DASHMATE_CONFIG_FILE_CONFLICT');
+
+      // the concurrent writer's value survives, byte for byte
+      expect(fs.readFileSync(configFilePath, 'utf8')).to.equal(onDisk);
+
+      // nothing generated in memory is lost - it is parked for the operator
+      const rejected = fs.readdirSync(homeDir.getPath())
+        .filter((name) => name.startsWith('config.json.rejected-'));
+
+      expect(rejected).to.have.lengthOf(1);
+      expect(thrown.message).to.contain(rejected[0]);
+
+      const parked = JSON.parse(fs.readFileSync(homeDir.joinPath(rejected[0]), 'utf8'));
+
+      expect(parked.configs.base.description).to.equal('stale-snapshot');
+    });
+
+    // Two nodes being set up at once both find no config file. "I have never
+    // looked" and "I looked and there was nothing there" are different claims,
+    // and only the second can detect that someone else created the file first.
+    it('should refuse a first-run write when another process created the file first', () => {
+      const first = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const second = new ConfigFileJsonRepository(identityMigration, homeDir);
+
+      // both observe an absent config file
+      expect(() => first.read()).to.throw();
+      expect(() => second.read()).to.throw();
+
+      const configFile = new ConfigFile(
+        [getBaseConfigFactory(homeDir)()],
+        CURRENT_FORMAT_VERSION,
+        'abcdef12',
+        'base',
+        null,
+      );
+
+      first.write(configFile);
+
+      const onDisk = fs.readFileSync(configFilePath, 'utf8');
+
+      let thrown;
+      try {
+        second.write(configFile);
+      } catch (e) {
+        thrown = e;
+      }
+
+      expect(thrown, 'second first-run write must not clobber the first').to.exist();
+      expect(thrown.code).to.equal('DASHMATE_CONFIG_FILE_CONFLICT');
+      expect(fs.readFileSync(configFilePath, 'utf8')).to.equal(onDisk);
+    });
+
+    // Present-to-absent is a change like any other. Recreating our old snapshot
+    // over a deliberate removal is the same lost update in the other direction.
+    it('should refuse to recreate a config file that was deleted after it was read', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const configFile = repository.read();
+
+      fs.unlinkSync(configFilePath);
+
+      configFile.getConfig('base').set('description', 'stale-snapshot');
+
+      let thrown;
+      try {
+        repository.write(configFile);
+      } catch (e) {
+        thrown = e;
+      }
+
+      expect(thrown, 'must not resurrect a deleted config file').to.exist();
+      expect(thrown.code).to.equal('DASHMATE_CONFIG_FILE_CONFLICT');
+      expect(fs.existsSync(configFilePath)).to.be.false();
+    });
+
+    // Comparing against the baseline is not enough on its own: two writers can
+    // both read the same bytes, both decide they are current, and both replace
+    // the file. Only a lock closes that window, and only a genuinely separate
+    // process can prove the lock is honoured. proper-lockfile represents a held
+    // lock as a directory, so the other process needs nothing but `fs`.
+    it('should wait for a lock held by another process before writing', function it0(done) {
+      this.timeout(20000);
+
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const configFile = repository.read();
+
+      configFile.getConfig('base').set('description', 'written-after-waiting');
+
+      const lockPath = homeDir.joinPath('config.json.lock');
+      const holdMs = 700;
+
+      const child = spawn(
+        process.execPath,
+        ['-e', `require('fs').mkdirSync(${JSON.stringify(lockPath)});`
+          + `setTimeout(() => require('fs').rmdirSync(${JSON.stringify(lockPath)}), ${holdMs});`],
+        { stdio: 'ignore' },
+      );
+
+      child.on('error', done);
+
+      // Wait for the other process to actually take the lock. Synchronous on
+      // purpose - the write we are about to make is synchronous too.
+      const deadline = Date.now() + 10000;
+      while (!fs.existsSync(lockPath) && Date.now() < deadline) {
+        // busy-wait
+      }
+
+      expect(fs.existsSync(lockPath), 'other process should hold the lock').to.be.true();
+
+      const startedAt = Date.now();
+
+      repository.write(configFile);
+
+      const waitedMs = Date.now() - startedAt;
+
+      // It blocked rather than writing straight through the other holder.
+      expect(waitedMs).to.be.at.least(holdMs / 2);
+      expect(fs.existsSync(lockPath), 'lock should be released again').to.be.false();
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('written-after-waiting');
+
+      child.on('exit', () => done());
+    });
+
+    it('should succeed after reloading following a conflict', () => {
+      seedConfigFile();
+
+      const slowReader = new ConfigFileJsonRepository(identityMigration, homeDir);
+      slowReader.read();
+
+      const writer = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const freshConfigFile = writer.read();
+      freshConfigFile.getConfig('base').set('description', 'concurrent');
+      writer.write(freshConfigFile);
+
+      const reloaded = slowReader.read();
+      reloaded.getConfig('base').set('description', 'after-reload');
+
+      expect(() => slowReader.write(reloaded)).to.not.throw();
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('after-reload');
+    });
+  });
+});
diff --git a/yarn.lock b/yarn.lock
index c21621aecb0..659b772ef72 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -7351,6 +7351,7 @@ __metadata:
     oclif: "npm:^4.0.3"
     pretty-bytes: "npm:^5.3.0"
     pretty-ms: "npm:^7.0.0"
+    proper-lockfile: "npm:^4.1.2"
     public-ip: "npm:^6.0.1"
     qs: "npm:^6.14.2"
     rxjs: "npm:^6.6.7"
@@ -7361,6 +7362,7 @@ __metadata:
     table: "npm:^6.8.1"
     tar: "npm:7.5.10"
     wrap-ansi: "npm:^7.0.0"
+    write-file-atomic: "npm:^5.0.1"
   bin:
     dashmate: ./bin/run.js
   languageName: unknown
@@ -14769,6 +14771,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"proper-lockfile@npm:^4.1.2":
+  version: 4.1.2
+  resolution: "proper-lockfile@npm:4.1.2"
+  dependencies:
+    graceful-fs: "npm:^4.2.4"
+    retry: "npm:^0.12.0"
+    signal-exit: "npm:^3.0.2"
+  checksum: 10/000a4875f543f591872b36ca94531af8a6463ddb0174f41c0b004d19e231d7445268b422ff1ea595e43d238655c702250cd3d27f408e7b9d97b56f1533ba26bf
+  languageName: node
+  linkType: hard
+
 "protobufjs@npm:^6.11.4":
   version: 6.11.4
   resolution: "protobufjs@npm:6.11.4"
@@ -18741,6 +18754,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"write-file-atomic@npm:^5.0.1":
+  version: 5.0.1
+  resolution: "write-file-atomic@npm:5.0.1"
+  dependencies:
+    imurmurhash: "npm:^0.1.4"
+    signal-exit: "npm:^4.0.1"
+  checksum: 10/648efddba54d478d0e4330ab6f239976df3b9752b123db5dc9405d9b5af768fa9d70ce60c52fdbe61d1200d24350bc4fbcbaf09288496c2be050de126bd95b7e
+  languageName: node
+  linkType: hard
+
 "ws@npm:^8.17.1":
   version: 8.17.1
   resolution: "ws@npm:8.17.1"

From ef3438979a94e81b6d0da3d9d72a0d82a540c9c5 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Tue, 28 Jul 2026 23:14:57 +0700
Subject: [PATCH 02/11] fix(dashmate): do not let lock bookkeeping mask a
 config write outcome
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`proper-lockfile`'s `release()` reports ERELEASED/ENOTACQUIRED when the lock
was compromised or already gone. Calling it bare in `finally` let that replace
the outcome the caller needs — an operator hitting a concurrent write would
have been told "Lock is already released" instead of being given the conflict
and the path their configuration was parked at. Release failures are now
contained; a lock that cannot be released goes stale and is reclaimed by the
next writer.

The library's default `onCompromised` rethrows, and it runs from a refresh
timer rather than the caller's stack, so a lock compromised mid-write would
have taken the whole process down. Replaced with a handler that does not
throw: the critical section lasts milliseconds, and the byte comparison
against the baseline — not the lock — is what actually prevents a lost update.

Also labels a fenced block in the config docs (MD040).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/dashmate/docs/config/index.md         |  2 +-
 .../configFile/ConfigFileJsonRepository.js     | 18 +++++++++++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/dashmate/docs/config/index.md b/packages/dashmate/docs/config/index.md
index a9c7502569c..b2868a530d6 100644
--- a/packages/dashmate/docs/config/index.md
+++ b/packages/dashmate/docs/config/index.md
@@ -189,7 +189,7 @@ file when it exits.
 To keep two overlapping commands from silently reverting each other, a command refuses to
 save when `config.json` changed on disk after that command loaded it:
 
-```
+```text
 '/home/user/.dashmate/config.json' was modified by another process after this command
 loaded it. Refusing to overwrite it. The changes from this command were saved to
 '/home/user/.dashmate/config.json.rejected-2026-07-28T09-14-22-031Z-4711-1' so you can
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index d9eb828545f..04e325ef167 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -194,7 +194,16 @@ export default class ConfigFileJsonRepository {
       configFile.markAsSaved();
       configFile.getAllConfigs().forEach((config) => config.markAsSaved());
     } finally {
-      release();
+      try {
+        release();
+      } catch {
+        // Releasing reports ERELEASED/ENOTACQUIRED when the lock was already
+        // gone. Nothing thrown from here may escape: it would replace the
+        // outcome the caller actually needs - including the conflict error
+        // naming where their configuration was parked - with a message about
+        // lock bookkeeping. A lock that cannot be released goes stale and is
+        // reclaimed by the next writer anyway.
+      }
     }
   }
 
@@ -218,6 +227,13 @@ export default class ConfigFileJsonRepository {
           // realpath resolution would fail on it.
           realpath: false,
           stale: LOCK_STALE_MS,
+          // The library's default handler rethrows, and it runs from a refresh
+          // timer rather than this call stack, so a lock compromised mid-write
+          // would take the whole process down. There is nothing useful to do
+          // about it here: the critical section lasts milliseconds, and the
+          // byte comparison against the baseline is what actually prevents a
+          // lost update - the lock only narrows the window it runs in.
+          onCompromised: () => {},
         });
       } catch (e) {
         if (e.code !== 'ELOCKED' || Date.now() >= deadline) {

From 235801568c46e95e49c6efd35fafc0c7cc7ad99c Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Tue, 28 Jul 2026 23:28:31 +0700
Subject: [PATCH 03/11] test(dashmate): stop the lock-contention test burning a
 core and leaking its child
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The poll waiting for the other process to take the lock was a tight
`fs.existsSync` loop, which pegs a CI core for the full ten-second timeout
whenever the child fails to start. It now sleeps between polls.

The spawned lock holder was only cleaned up on the success path, so a failing
assertion left it running — still owning the lock directory — after the test
that created it had gone. It is tracked and killed in `afterEach` instead, so
the failure mode is deterministic.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../ConfigFileJsonRepository.spec.js          | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index 2bf4728ad31..34266c672db 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -12,6 +12,9 @@ describe('ConfigFileJsonRepository', () => {
   let homeDir;
   let configFilePath;
   let identityMigration;
+  // Tracked so a failed assertion cannot leave a spawned lock holder behind
+  // still owning the lock directory after the test that created it is gone.
+  let lockHolder;
 
   /**
    * Seed a valid config file on disk, the way a configured node would have one.
@@ -43,6 +46,12 @@ describe('ConfigFileJsonRepository', () => {
   });
 
   afterEach(() => {
+    if (lockHolder && lockHolder.exitCode === null && lockHolder.signalCode === null) {
+      lockHolder.kill();
+    }
+
+    lockHolder = undefined;
+
     homeDir.remove();
   });
 
@@ -283,20 +292,22 @@ describe('ConfigFileJsonRepository', () => {
       const lockPath = homeDir.joinPath('config.json.lock');
       const holdMs = 700;
 
-      const child = spawn(
+      lockHolder = spawn(
         process.execPath,
         ['-e', `require('fs').mkdirSync(${JSON.stringify(lockPath)});`
           + `setTimeout(() => require('fs').rmdirSync(${JSON.stringify(lockPath)}), ${holdMs});`],
         { stdio: 'ignore' },
       );
 
-      child.on('error', done);
+      lockHolder.on('error', done);
 
       // Wait for the other process to actually take the lock. Synchronous on
       // purpose - the write we are about to make is synchronous too.
+      // Polled with a real sleep rather than a tight loop - spinning here would
+      // peg a CI core for the whole timeout whenever the child fails to start.
       const deadline = Date.now() + 10000;
       while (!fs.existsSync(lockPath) && Date.now() < deadline) {
-        // busy-wait
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
       }
 
       expect(fs.existsSync(lockPath), 'other process should hold the lock').to.be.true();
@@ -315,7 +326,7 @@ describe('ConfigFileJsonRepository', () => {
 
       expect(reread.getConfig('base').get('description')).to.equal('written-after-waiting');
 
-      child.on('exit', () => done());
+      lockHolder.on('exit', () => done());
     });
 
     it('should succeed after reloading following a conflict', () => {

From e23dbdf480f2e3795dd5f0a4cc03a264225056df Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Wed, 29 Jul 2026 00:22:33 +0700
Subject: [PATCH 04/11] fix(dashmate): render service templates only for
 configs that changed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every command re-rendered and rewrote all service templates — 40 files for a
four-config home directory, on `dashmate config get` as much as on `setup`.
That was never intentional: hydration marked every config changed, so the
existing "changed configs only" filter matched all of them. Fixing hydration
left the filter correct but the rendering unconditional, which kept half of
the original side effect alive.

Rendering only what changed is safe because upgrading Dashmate records the new
version in the config file even when no migration applies, and
`ConfigFileJsonRepository.read()` marks every config changed when that recorded
version moved. So a release that edits a template still reaches every node on
its next command, without paying for it on every unrelated command.

That property was load-bearing and untested, so it is pinned now: removing the
version stamp from `migrateConfigFile` fails the new test with
`expected '98.0.0' to equal '99.0.0'`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/dashmate/scripts/helper.js           | 11 +++---
 .../dashmate/src/oclif/command/BaseCommand.js | 26 ++++++++------
 .../migrateConfigFileFactory.spec.js          | 35 +++++++++++++++++++
 3 files changed, 57 insertions(+), 15 deletions(-)

diff --git a/packages/dashmate/scripts/helper.js b/packages/dashmate/scripts/helper.js
index 4010c3d01ee..4fa8bdf7d64 100644
--- a/packages/dashmate/scripts/helper.js
+++ b/packages/dashmate/scripts/helper.js
@@ -94,12 +94,15 @@ async function removeOrphanedSslContainers(docker) {
 
   // Persist config if it was migrated
   if (configFile.isChanged()) {
+    // Captured before the write, which clears these flags once the new state is
+    // on disk.
+    const changedConfigs = configFile.getAllConfigs()
+      .filter((config) => config.isChanged());
+
     await configFileRepository.write(configFile);
-  }
 
-  // Rendered artifacts rather than persisted state - always brought up to date
-  // with this Dashmate's templates, whether or not the configuration changed.
-  configFile.getAllConfigs().forEach(writeConfigTemplates);
+    changedConfigs.forEach(writeConfigTemplates);
+  }
 
   const config = configFile.getConfig(configName);
 
diff --git a/packages/dashmate/src/oclif/command/BaseCommand.js b/packages/dashmate/src/oclif/command/BaseCommand.js
index 28ee0d9b15e..2390d75d696 100644
--- a/packages/dashmate/src/oclif/command/BaseCommand.js
+++ b/packages/dashmate/src/oclif/command/BaseCommand.js
@@ -111,20 +111,24 @@ export default class BaseCommand extends Command {
         const configFile = this.container.resolve('configFile');
 
         if (configFile.isChanged()) {
+          // Captured before the write, which clears these flags once the new
+          // state is on disk.
+          const changedConfigs = configFile.getAllConfigs()
+            .filter((config) => config.isChanged());
+
           configFileRepository.write(configFile);
-        }
 
-        // Service templates are rendered artifacts, not persisted state, and are
-        // rewritten on every command regardless of whether the configuration
-        // changed. Rendering only on change would leave a node running templates
-        // from an older Dashmate whenever a release edits a template without
-        // also changing the config format version.
-        /**
-         * @var {writeConfigTemplates} writeConfigTemplates
-         */
-        const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
+          /**
+           * @var {writeConfigTemplates} writeConfigTemplates
+           */
+          const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
 
-        configFile.getAllConfigs().forEach(writeConfigTemplates);
+          // Re-rendering only what changed is safe because upgrading Dashmate
+          // stamps the new version into the config file even when no migration
+          // applies, which marks every config changed - so a release that edits
+          // a template still reaches every node on its next command.
+          changedConfigs.forEach(writeConfigTemplates);
+        }
       }
 
       // Stop all running containers
diff --git a/packages/dashmate/test/unit/config/configFile/migrateConfigFileFactory.spec.js b/packages/dashmate/test/unit/config/configFile/migrateConfigFileFactory.spec.js
index a1065b8b10e..1d849f314d0 100644
--- a/packages/dashmate/test/unit/config/configFile/migrateConfigFileFactory.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/migrateConfigFileFactory.spec.js
@@ -260,4 +260,39 @@ describe('migrateConfigFileFactory', () => {
       );
     }
   });
+
+  // Upgrading Dashmate has to leave a mark on the config file even when nothing
+  // needed migrating, because that recorded version is the only thing that tells
+  // the next command every config is stale. `ConfigFileJsonRepository.read()`
+  // marks all configs changed when the version moved, and that is what re-renders
+  // service templates after an upgrade. Stamping the version only when a
+  // migration happened to apply would leave nodes running templates rendered by
+  // an older Dashmate, with nothing to signal it.
+  it('should record the new version after an upgrade even when no migration applies', () => {
+    const configFileData = getConfigFileDataV0250();
+
+    // Both versions sit above every migration key, so nothing can match and the
+    // recorded version is the only thing the upgrade can change.
+    const installedVersion = '98.0.0';
+    const upgradedVersion = '99.0.0';
+
+    configFileData.configFormatVersion = installedVersion;
+
+    const migrated = migrateConfigFile(
+      configFileData,
+      configFileData.configFormatVersion,
+      upgradedVersion,
+    );
+
+    expect(migrated.configFormatVersion).to.equal(upgradedVersion);
+
+    // And migrating again from there is a no-op, so the mark does not repeat.
+    const again = migrateConfigFile(
+      migrated,
+      migrated.configFormatVersion,
+      upgradedVersion,
+    );
+
+    expect(again.configFormatVersion).to.equal(upgradedVersion);
+  });
 });

From 7abb4c380a7b68c146493fcafe33e6df22b2d896 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Thu, 30 Jul 2026 19:44:31 +0700
Subject: [PATCH 05/11] fix(dashmate)!: read, change and save config as one
 locked step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reading the config file when a command starts and saving it when the command
exits means the state written is a snapshot that may already be out of date, so
an overlapping command's change is reverted. Detecting that afterwards — refusing
the write, parking the rejected state in a file and asking the operator to
reconcile — treated the symptom and put the burden on them.

`ConfigFileJsonRepository.update(mutator)` instead takes the lock, reads the
current state, applies the change and saves, all in one step. The state handed to
the mutator is read after the lock is held, so there is nothing stale to write and
nothing to detect: two commands changing different options now both succeed.

`dashmate config set` uses it, against the config name resolved for that command
rather than re-resolving the default, which another process may have changed.

Removed, because none of it has anything left to do:

- `ConfigFileConflictError`
- the `config.json.rejected-*` snapshots and their naming
- the observed-state baseline and the compare-before-write
- the operator recovery procedure in the config docs

Demonstrated on a real config file — read-early/write-late loses the other
command's edit, `update()` keeps both:

  OLD read-early/write-late: other command edit survived => false
  NEW update():             other command edit survived => true
                            this command edit survived  => true

`setup`, `reset` and `ssl obtain` still load at start and save at exit, so
changing config with `config set` while one of them runs can still lose the
change. Documented rather than solved: they are exclusive operations, and the
mechanisms that would cover them cost more than the case is worth.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/dashmate/docs/config/index.md        |  57 ++----
 packages/dashmate/src/commands/config/set.js  |  15 +-
 .../configFile/ConfigFileJsonRepository.js    | 181 +++++++----------
 .../config/errors/ConfigFileConflictError.js  |  49 -----
 .../test/unit/commands/config/set.spec.js     | 155 ++++++++-------
 .../ConfigFileJsonRepository.spec.js          | 186 ++++++------------
 6 files changed, 252 insertions(+), 391 deletions(-)
 delete mode 100644 packages/dashmate/src/config/errors/ConfigFileConflictError.js

diff --git a/packages/dashmate/docs/config/index.md b/packages/dashmate/docs/config/index.md
index b2868a530d6..708ec403dee 100644
--- a/packages/dashmate/docs/config/index.md
+++ b/packages/dashmate/docs/config/index.md
@@ -183,48 +183,21 @@ dashmate config set core.log.debug.enabled true
 ## Running Dashmate commands concurrently
 
 Dashmate keeps all configuration in a single `config.json` inside its home directory
-(`~/.dashmate` by default), and a command that changes configuration rewrites that whole
-file when it exits.
+(`~/.dashmate` by default).
 
-To keep two overlapping commands from silently reverting each other, a command refuses to
-save when `config.json` changed on disk after that command loaded it:
+Commands that change a configuration option — `dashmate config set` and friends — read,
+change and save that file as one locked step. Two of them running at once cannot lose each
+other's work: if one sets a Core RPC port while another pins a Drive image, both settings
+survive. A command that has to wait for the lock waits milliseconds, since the lock is only
+held for a read and a write.
 
-```text
-'/home/user/.dashmate/config.json' was modified by another process after this command
-loaded it. Refusing to overwrite it. The changes from this command were saved to
-'/home/user/.dashmate/config.json.rejected-2026-07-28T09-14-22-031Z-4711-1' so you can
-reconcile them.
-```
+Read-only commands such as `dashmate config get`, `dashmate status` and `dashmate core cli`
+never write configuration at all, so they are always safe to run alongside anything else.
+
+### Limits
 
-The command exits non-zero and the other process's change is kept. Nothing is lost — the
-configuration this command wanted to save is written to the `.rejected-*` file named in
-the message, so you can compare it and reapply what you need. These files are never
-cleaned up automatically; remove them once you have reconciled them.
-
-How to respond depends on the command:
-
-- `dashmate config set` — reload and run it again. Nothing else happened.
-- `dashmate config create`, `remove`, `default` — re-check your assumptions before
-  retrying. The other process may have created or removed the very configuration you were
-  operating on.
-- `dashmate setup`, `reset`, `start`, `ssl obtain` — **the operational work already
-  happened**; only saving the configuration failed. Containers may be running and
-  certificates may have been issued. Reconcile from the `.rejected-*` file rather than
-  simply re-running the command.
-
-Read-only commands such as `dashmate config get`, `dashmate status` and `dashmate core
-cli` never write configuration and are always safe to run alongside anything else.
-
-### Limits of this guarantee
-
-- **All Dashmate instances must be on a version that has this behaviour.** The
-  coordination is cooperative, so an older Dashmate process — including a long-running
-  helper started before an upgrade — can still overwrite a newer one. After upgrading,
-  restart the node so the helper restarts too.
-- **Local filesystems only.** The guarantee is not claimed for a Dashmate home directory
-  on NFS or another network filesystem.
-- **Only Dashmate processes take part in this.** A hand edit made while a long Dashmate
-  command is running is usually detected and the command refuses rather than discarding it
-  — but a text editor does not take the lock, so an edit saved in the moment between
-  Dashmate re-reading the file and replacing it can still be overwritten. Stop Dashmate
-  commands before editing `config.json` by hand if the edit matters.
+Long-running commands that reconfigure a node — `dashmate setup`, `dashmate reset` and
+`dashmate ssl obtain` — still load the configuration when they start and save it when they
+finish. Do not change configuration with `dashmate config set` while one of those is
+running: the long-running command saves the state it loaded, and an option changed in the
+meantime is lost.
diff --git a/packages/dashmate/src/commands/config/set.js b/packages/dashmate/src/commands/config/set.js
index 4f6e27992ce..2dd21090c6c 100644
--- a/packages/dashmate/src/commands/config/set.js
+++ b/packages/dashmate/src/commands/config/set.js
@@ -39,6 +39,8 @@ Sets a configuration option in the default config
     },
     flags,
     config,
+    configFileRepository,
+    writeConfigTemplates,
   ) {
     // Validate the path against the schema, not against the currently-set
     // value. `config.get(...)` would throw `InvalidOptionPathError` for any
@@ -59,7 +61,18 @@ Sets a configuration option in the default config
       value = optionValue;
     }
 
-    config.set(optionPath, value);
+    // Read, change and save in one locked step, against the config name resolved
+    // for this command rather than re-resolving the default, which another
+    // process may have changed. Mutating the copy loaded at startup and saving it
+    // on exit would write a snapshot that is already out of date, reverting
+    // anything saved in between.
+    const configName = config.getName();
+
+    const configFile = configFileRepository.update((freshConfigFile) => {
+      freshConfigFile.getConfig(configName).set(optionPath, value);
+    });
+
+    writeConfigTemplates(configFile.getConfig(configName));
 
     // eslint-disable-next-line no-console
     console.log(`${optionPath} set to ${optionValue}`);
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index 04e325ef167..4f505b43207 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -7,7 +7,6 @@ import Config from '../Config.js';
 import { PACKAGE_ROOT_DIR } from '../../constants.js';
 import ConfigFileNotFoundError from '../errors/ConfigFileNotFoundError.js';
 import InvalidConfigFileFormatError from '../errors/InvalidConfigFileFormatError.js';
-import ConfigFileConflictError from '../errors/ConfigFileConflictError.js';
 import configFileJsonSchema from './configFileJsonSchema.js';
 import ConfigFile from './ConfigFile.js';
 
@@ -39,37 +38,6 @@ function sleepSync(ms) {
 }
 
 export default class ConfigFileJsonRepository {
-  /**
-   * What this instance last observed on disk:
-   *
-   * - `undefined` - never looked, so nothing can be claimed about the file
-   * - `null`      - looked, and there was no file
-   * - `string`    - the exact bytes that were there
-   *
-   * "Never looked" and "looked and found nothing" have to stay distinct, or two
-   * nodes being set up concurrently would both write over each other believing
-   * they were creating the file.
-   *
-   * Concurrent writers are detected by comparing against this, so it must be
-   * refreshed on every successful write - the dashmate helper reads once at
-   * startup and then writes on every certificate renewal for the life of the
-   * process, and would otherwise conflict with its own previous write.
-   *
-   * One instance tracks one config file lifecycle: a second read() rebaselines
-   * it, so do not write a ConfigFile obtained from an earlier read afterwards.
-   *
-   * @type {string|null|undefined}
-   */
-  #baseline;
-
-  /**
-   * Distinguishes parked snapshots written by this process within the same
-   * millisecond.
-   *
-   * @type {number}
-   */
-  #rejectedCount = 0;
-
   /**
    * @param {migrateConfigFile} migrateConfigFile
    * @param {HomeDir} homeDir
@@ -93,18 +61,11 @@ export default class ConfigFileJsonRepository {
   read(options = {}) {
     const { skipValidation = false } = options;
     if (!fs.existsSync(this.configFilePath)) {
-      // Record that the file was observed absent. The caller creates a default
-      // config file from here, and that write must still lose to another
-      // process that created one first.
-      this.#baseline = null;
-
       throw new ConfigFileNotFoundError(this.configFilePath);
     }
 
     const configFileJSON = fs.readFileSync(this.configFilePath, 'utf8');
 
-    this.#baseline = configFileJSON;
-
     let configFileData;
     try {
       configFileData = JSON.parse(configFileJSON);
@@ -155,55 +116,90 @@ export default class ConfigFileJsonRepository {
     return configFile;
   }
 
+  /**
+   * Read, change and save the config file as one indivisible step.
+   *
+   * Everything happens while the file is locked, and the state handed to the
+   * mutator is read after taking the lock - so a change made by another process
+   * in between cannot be reverted, and two commands editing different options
+   * both survive. Reading in one place and saving in another is what allowed a
+   * command to write a snapshot that was already out of date.
+   *
+   * The lock is held for a read, a mutation and a rename - milliseconds - so it
+   * is not a meaningful serialization point for commands that only edit config.
+   *
+   * @param {function(ConfigFile): void} mutate
+   * @param {Object} [options={}] - passed through to read()
+   * @returns {ConfigFile} the state that was saved
+   */
+  update(mutate, options = {}) {
+    const release = this.#acquireLock();
+
+    try {
+      const configFile = this.read(options);
+
+      mutate(configFile);
+
+      this.#save(configFile);
+
+      return configFile;
+    } finally {
+      this.#release(release);
+    }
+  }
+
   /**
    * Save configs to file
    *
-   * Refuses to write when the file changed on disk since this instance read it,
-   * rather than reverting whatever the other process saved. The check and the
-   * replacement happen under a lock so two writers cannot both pass the check
-   * and then both write; the lock is held only for that, never for the duration
-   * of a command.
+   * Prefer update() for changing configuration: it reads the current state under
+   * the same lock, so it cannot save something another process has already
+   * moved on from. This remains for callers that mutate a config file they are
+   * holding and then save it as a separate step.
    *
    * @param {ConfigFile} configFile
-   * @throws {ConfigFileConflictError} when another process wrote first
    * @returns {void}
    */
   write(configFile) {
-    const configFileJSON = `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`;
-
     const release = this.#acquireLock();
 
     try {
-      const currentJSON = fs.existsSync(this.configFilePath)
-        ? fs.readFileSync(this.configFilePath, 'utf8')
-        : null;
-
-      // Any observed change conflicts, including present-to-absent: recreating
-      // a config file somebody deliberately removed is the same lost update in
-      // the other direction.
-      if (this.#baseline !== undefined && currentJSON !== this.#baseline) {
-        throw this.#rejectStaleWrite(configFileJSON);
-      }
+      this.#save(configFile);
+    } finally {
+      this.#release(release);
+    }
+  }
+
+  /**
+   * Serialize and replace the file, then mark the state clean.
+   *
+   * Caller must hold the lock.
+   *
+   * @param {ConfigFile} configFile
+   */
+  #save(configFile) {
+    const configFileJSON = `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`;
 
-      writeFileAtomic.sync(this.configFilePath, configFileJSON, 'utf8');
+    writeFileAtomic.sync(this.configFilePath, configFileJSON, 'utf8');
 
-      this.#baseline = configFileJSON;
+    // Only now is the state actually on disk. Clearing these beforehand would
+    // leave the configs claiming to be saved after a failed write.
+    configFile.markAsSaved();
+    configFile.getAllConfigs().forEach((config) => config.markAsSaved());
+  }
 
-      // Only now is the state actually on disk. Clearing these before the write
-      // would leave the configs claiming to be saved after a failed one.
-      configFile.markAsSaved();
-      configFile.getAllConfigs().forEach((config) => config.markAsSaved());
-    } finally {
-      try {
-        release();
-      } catch {
-        // Releasing reports ERELEASED/ENOTACQUIRED when the lock was already
-        // gone. Nothing thrown from here may escape: it would replace the
-        // outcome the caller actually needs - including the conflict error
-        // naming where their configuration was parked - with a message about
-        // lock bookkeeping. A lock that cannot be released goes stale and is
-        // reclaimed by the next writer anyway.
-      }
+  /**
+   * @param {function} release
+   */
+
+  #release(release) {
+    try {
+      release();
+    } catch {
+      // Releasing reports ERELEASED/ENOTACQUIRED when the lock was already
+      // gone. Nothing thrown from here may escape - it would replace the
+      // outcome the caller actually needs with a message about lock
+      // bookkeeping. A lock that cannot be released goes stale and is reclaimed
+      // by the next writer anyway.
     }
   }
 
@@ -227,12 +223,11 @@ export default class ConfigFileJsonRepository {
           // realpath resolution would fail on it.
           realpath: false,
           stale: LOCK_STALE_MS,
-          // The library's default handler rethrows, and it runs from a refresh
-          // timer rather than this call stack, so a lock compromised mid-write
-          // would take the whole process down. There is nothing useful to do
-          // about it here: the critical section lasts milliseconds, and the
-          // byte comparison against the baseline is what actually prevents a
-          // lost update - the lock only narrows the window it runs in.
+          // The library's default handler rethrows from a refresh timer rather
+          // than this call stack, which would take the whole process down. The
+          // critical section is a read, a mutation and a rename, so it finishes
+          // well inside the stale threshold and a compromised lock is not a
+          // condition this can act on.
           onCompromised: () => {},
         });
       } catch (e) {
@@ -244,30 +239,4 @@ export default class ConfigFileJsonRepository {
       }
     }
   }
-
-  /**
-   * Park the state we refused to write, so material generated during the
-   * command is recoverable, and describe where it went.
-   *
-   * @param {string} configFileJSON
-   * @returns {ConfigFileConflictError}
-   */
-  #rejectStaleWrite(configFileJSON) {
-    // Colons are not legal in Windows filenames. The pid separates concurrent
-    // processes and the counter separates two conflicts from this one inside
-    // the same millisecond, so no parked state is ever overwritten by another.
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-
-    this.#rejectedCount += 1;
-
-    const rejectedPath = `${this.configFilePath}.rejected-${stamp}-${process.pid}-${this.#rejectedCount}`;
-
-    try {
-      writeFileAtomic.sync(rejectedPath, configFileJSON, { encoding: 'utf8', mode: 0o600 });
-    } catch (e) {
-      return new ConfigFileConflictError(this.configFilePath, null, e);
-    }
-
-    return new ConfigFileConflictError(this.configFilePath, rejectedPath);
-  }
 }
diff --git a/packages/dashmate/src/config/errors/ConfigFileConflictError.js b/packages/dashmate/src/config/errors/ConfigFileConflictError.js
deleted file mode 100644
index 3b3c58ceae3..00000000000
--- a/packages/dashmate/src/config/errors/ConfigFileConflictError.js
+++ /dev/null
@@ -1,49 +0,0 @@
-import AbstractError from '../../errors/AbstractError.js';
-
-/**
- * Raised when the config file changed on disk after this process loaded it.
- *
- * Writing would silently revert whatever the other process saved, so the write
- * is refused. The in-memory state is parked next to the config file first, so
- * material generated during the command - operator keys, a spork key, a miner
- * address - is never lost with the refused write.
- */
-export default class ConfigFileConflictError extends AbstractError {
-  /**
-   * @param {string} configFilePath
-   * @param {string|null} rejectedSnapshotPath - null when parking it also failed
-   * @param {Error} [snapshotError] - why parking failed, when it did
-   */
-  constructor(configFilePath, rejectedSnapshotPath, snapshotError = undefined) {
-    const recovery = rejectedSnapshotPath === null
-      ? `The changes from this command could NOT be saved either: ${snapshotError?.message}. They are lost.`
-      : `The changes from this command were saved to '${rejectedSnapshotPath}' so you can reconcile them.`;
-
-    super(`'${configFilePath}' was modified by another process after this command loaded it.`
-      + ` Refusing to overwrite it. ${recovery}`);
-
-    this.configFilePath = configFilePath;
-    this.rejectedSnapshotPath = rejectedSnapshotPath;
-    this.snapshotError = snapshotError;
-
-    // Stable identifier for callers that need to branch on this without
-    // depending on the class identity across module instances.
-    this.code = 'DASHMATE_CONFIG_FILE_CONFLICT';
-  }
-
-  /**
-   * @returns {string}
-   */
-  getConfigFilePath() {
-    return this.configFilePath;
-  }
-
-  /**
-   * Path the refused state was parked at, or null if that failed too.
-   *
-   * @returns {string|null}
-   */
-  getRejectedSnapshotPath() {
-    return this.rejectedSnapshotPath;
-  }
-}
diff --git a/packages/dashmate/test/unit/commands/config/set.spec.js b/packages/dashmate/test/unit/commands/config/set.spec.js
index 67b8bef75a3..30725e5637b 100644
--- a/packages/dashmate/test/unit/commands/config/set.spec.js
+++ b/packages/dashmate/test/unit/commands/config/set.spec.js
@@ -1,104 +1,122 @@
+import fs from 'fs';
 import HomeDir from '../../../../src/config/HomeDir.js';
 import ConfigSetCommand from '../../../../src/commands/config/set.js';
+import ConfigFile from '../../../../src/config/configFile/ConfigFile.js';
+import ConfigFileJsonRepository from '../../../../src/config/configFile/ConfigFileJsonRepository.js';
 import getBaseConfigFactory from '../../../../configs/defaults/getBaseConfigFactory.js';
 
 describe('Config set command', () => {
   const flags = {};
 
+  let homeDir;
   let config;
+  let configFileRepository;
+  let writeConfigTemplates;
+  let command;
+
+  /**
+   * The command now reads, changes and saves in one locked step rather than
+   * mutating the object it was handed, so these assert what actually reached
+   * disk. Reading it back is the only thing that proves the value was saved.
+   *
+   * @param {string} path
+   * @return {*}
+   */
+  function persisted(path) {
+    return new ConfigFileJsonRepository((data) => data, homeDir)
+      .read()
+      .getConfig('base')
+      .get(path);
+  }
+
+  beforeEach(() => {
+    homeDir = HomeDir.createTemp();
+
+    config = getBaseConfigFactory(homeDir)();
+
+    const configFile = new ConfigFile([config], '4.1.0', 'abcdef12', 'base', null);
+
+    fs.writeFileSync(
+      homeDir.joinPath('config.json'),
+      `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`,
+      'utf8',
+    );
+
+    configFileRepository = new ConfigFileJsonRepository((data) => data, homeDir);
+    writeConfigTemplates = () => {};
+    command = new ConfigSetCommand();
+  });
 
-  beforeEach(async () => {
-    const getBaseConfig = getBaseConfigFactory(HomeDir.createTemp());
-
-    config = getBaseConfig();
+  afterEach(() => {
+    homeDir.remove();
   });
 
+  /**
+   * @param {string} option
+   * @param {*} value
+   */
+  function run(option, value) {
+    return command.runWithDependencies(
+      { option, value },
+      flags,
+      config,
+      configFileRepository,
+      writeConfigTemplates,
+    );
+  }
+
   describe('#platform', () => {
     it('should allow setting strings', async () => {
-      const command = new ConfigSetCommand();
+      await run('core.docker.image', 'fake_image');
 
-      await command.runWithDependencies({
-        option: 'core.docker.image', value: 'fake_image',
-      }, flags, config);
+      expect(persisted('core.docker.image')).to.equal('fake_image');
     });
 
     it('should allow setting null', async () => {
-      const command = new ConfigSetCommand();
-
-      await command.runWithDependencies({
-        option: 'description', value: null,
-      }, flags, config);
+      await run('description', null);
 
-      expect(config.get('description')).to.equal(null);
+      expect(persisted('description')).to.equal(null);
 
-      await command.runWithDependencies({
-        option: 'description', value: 'null',
-      }, flags, config);
+      await run('description', 'null');
 
-      expect(config.get('description')).to.equal(null);
+      expect(persisted('description')).to.equal(null);
     });
 
     it('should allow setting numbers', async () => {
-      const command = new ConfigSetCommand();
+      await run('platform.drive.abci.validatorSet.quorum.llmqType', 107);
 
-      await command.runWithDependencies({
-        option: 'platform.drive.abci.validatorSet.quorum.llmqType',
-        value: 107,
-      }, flags, config);
+      expect(persisted('platform.drive.abci.validatorSet.quorum.llmqType')).to.equal(107);
 
-      expect(config.get('platform.drive.abci.validatorSet.quorum.llmqType')).to.equal(107);
+      await run('platform.drive.abci.validatorSet.quorum.llmqType', '107');
 
-      await command.runWithDependencies({
-        option: 'platform.drive.abci.validatorSet.quorum.llmqType',
-        value: '107',
-      }, flags, config);
-
-      expect(config.get('platform.drive.abci.validatorSet.quorum.llmqType')).to.equal(107);
+      expect(persisted('platform.drive.abci.validatorSet.quorum.llmqType')).to.equal(107);
     });
 
     it('should allow setting booleans', async () => {
-      const command = new ConfigSetCommand();
-
-      await command.runWithDependencies({
-        option: 'dashmate.helper.api.enable', value: 'true',
-      }, flags, config);
+      await run('dashmate.helper.api.enable', 'true');
 
-      expect(config.get('dashmate.helper.api.enable')).to.equal(true);
+      expect(persisted('dashmate.helper.api.enable')).to.equal(true);
 
-      await command.runWithDependencies({
-        option: 'dashmate.helper.api.enable', value: true,
-      }, flags, config);
+      await run('dashmate.helper.api.enable', true);
 
-      expect(config.get('dashmate.helper.api.enable')).to.equal(true);
+      expect(persisted('dashmate.helper.api.enable')).to.equal(true);
     });
 
     it('should allow setting array of values', async () => {
-      const command = new ConfigSetCommand();
-
-      await command.runWithDependencies({
-        option: 'core.rpc.allowIps', value: '["1337", "36484"]',
-      }, flags, config);
+      await run('core.rpc.allowIps', '["1337", "36484"]');
 
-      expect(config.get('core.rpc.allowIps')).to.deep.equal(['1337', '36484']);
+      expect(persisted('core.rpc.allowIps')).to.deep.equal(['1337', '36484']);
     });
 
     it('should allow replacing part of the json', async () => {
-      const command = new ConfigSetCommand();
+      await run('docker.network', '{"subnet":"127.0.0.1/24"}');
 
-      await command.runWithDependencies({
-        option: 'docker.network',
-        value: '{"subnet":"127.0.0.1/24"}',
-      }, flags, config);
+      expect(persisted('docker.network.subnet')).to.equal('127.0.0.1/24');
     });
 
     it('should throw on unknown path', async () => {
-      const command = new ConfigSetCommand();
-
-      // invalid path
       try {
-        await command.runWithDependencies({
-          option: 'fakePath', value: 'fake',
-        }, flags, config);
+        await run('fakePath', 'fake');
 
         expect.fail('should throw error');
       } catch (e) {
@@ -107,13 +125,8 @@ describe('Config set command', () => {
     });
 
     it('should throw if invalid json is passed', async () => {
-      const command = new ConfigSetCommand();
-
-      // invalid json
       try {
-        await command.runWithDependencies({
-          option: 'core.rpc.allowIps', value: 'fake_image',
-        }, flags, config);
+        await run('core.rpc.allowIps', 'fake_image');
 
         expect.fail('should throw error');
       } catch (e) {
@@ -122,18 +135,22 @@ describe('Config set command', () => {
     });
 
     it('should throw on type mismatch', async () => {
-      const command = new ConfigSetCommand();
-
-      // invalid json
       try {
-        await command.runWithDependencies({
-          option: 'dashmate.helper.api.enable', value: 120,
-        }, flags, config);
+        await run('dashmate.helper.api.enable', 120);
 
         expect.fail('should throw error');
       } catch (e) {
         expect(e.name).to.equal('InvalidOptionError');
       }
     });
+
+    // A rejected set must leave the file exactly as it was, not half-applied.
+    it('should not change the file when the value is rejected', async () => {
+      const before = fs.readFileSync(homeDir.joinPath('config.json'), 'utf8');
+
+      await run('dashmate.helper.api.enable', 120).catch(() => {});
+
+      expect(fs.readFileSync(homeDir.joinPath('config.json'), 'utf8')).to.equal(before);
+    });
   });
 });
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index 34266c672db..3a1dc1641e3 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -147,8 +147,8 @@ describe('ConfigFileJsonRepository', () => {
     });
 
     // The helper daemon reads once at startup and writes on every certificate
-    // renewal for the life of the process. If the staleness baseline is not
-    // refreshed after each write, its second write conflicts with its own first.
+    // renewal for the life of the process, so saving repeatedly from one
+    // instance has to keep working.
     it('should allow repeated writes from one long-lived instance', () => {
       seedConfigFile();
 
@@ -168,127 +168,92 @@ describe('ConfigFileJsonRepository', () => {
     });
   });
 
-  describe('#write concurrency', () => {
-    // The reported lost update: a process loads the config, another process
-    // changes and saves it, and the first process writes its stale snapshot
-    // last. Asserting only "the second value survived" would also pass if the
-    // stale write silently did nothing, so the contract itself is pinned:
-    // it refuses loudly, leaves the file alone, and keeps the rejected state.
-    it('should refuse a stale write instead of clobbering a concurrent update', () => {
+  describe('#update', () => {
+    // The reported bug, stated as the outcome operators want rather than as a
+    // failure they have to recover from: one process loads the config, another
+    // changes and saves a different option, and both edits survive. Mutating a
+    // snapshot loaded earlier and saving it at exit loses one of them.
+    it('should keep concurrent edits to different options', () => {
       seedConfigFile();
 
-      const slowReader = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const staleConfigFile = slowReader.read();
+      const slowCommand = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const otherCommand = new ConfigFileJsonRepository(identityMigration, homeDir);
 
-      // A concurrent `dashmate config set` lands and exits successfully
-      const writer = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const freshConfigFile = writer.read();
-      freshConfigFile.getConfig('base').set('description', 'set-by-concurrent-writer');
-      writer.write(freshConfigFile);
+      // Both load the same starting state, as two overlapping commands would
+      slowCommand.read();
+      otherCommand.read();
 
-      const onDisk = fs.readFileSync(configFilePath, 'utf8');
+      otherCommand.update((configFile) => {
+        configFile.getConfig('base').set('description', 'set-by-other-command');
+      });
 
-      staleConfigFile.getConfig('base').set('description', 'stale-snapshot');
+      slowCommand.update((configFile) => {
+        configFile.getConfig('base').set('core.rpc.port', 30000);
+      });
 
-      let thrown;
-      try {
-        slowReader.write(staleConfigFile);
-      } catch (e) {
-        thrown = e;
-      }
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
 
-      expect(thrown, 'stale write must not succeed').to.exist();
-      expect(thrown.code).to.equal('DASHMATE_CONFIG_FILE_CONFLICT');
+      expect(reread.getConfig('base').get('description')).to.equal('set-by-other-command');
+      expect(reread.getConfig('base').get('core.rpc.port')).to.equal(30000);
+    });
 
-      // the concurrent writer's value survives, byte for byte
-      expect(fs.readFileSync(configFilePath, 'utf8')).to.equal(onDisk);
+    // The mutator must never be handed the state this instance happened to read
+    // earlier - that is the whole point of reading inside the lock.
+    it('should hand the mutator state written since this instance last read', () => {
+      seedConfigFile();
 
-      // nothing generated in memory is lost - it is parked for the operator
-      const rejected = fs.readdirSync(homeDir.getPath())
-        .filter((name) => name.startsWith('config.json.rejected-'));
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
 
-      expect(rejected).to.have.lengthOf(1);
-      expect(thrown.message).to.contain(rejected[0]);
+      repository.read();
 
-      const parked = JSON.parse(fs.readFileSync(homeDir.joinPath(rejected[0]), 'utf8'));
+      new ConfigFileJsonRepository(identityMigration, homeDir)
+        .update((configFile) => {
+          configFile.getConfig('base').set('description', 'written-by-someone-else');
+        });
 
-      expect(parked.configs.base.description).to.equal('stale-snapshot');
-    });
+      let seen;
+      repository.update((configFile) => {
+        seen = configFile.getConfig('base').get('description');
+      });
 
-    // Two nodes being set up at once both find no config file. "I have never
-    // looked" and "I looked and there was nothing there" are different claims,
-    // and only the second can detect that someone else created the file first.
-    it('should refuse a first-run write when another process created the file first', () => {
-      const first = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const second = new ConfigFileJsonRepository(identityMigration, homeDir);
-
-      // both observe an absent config file
-      expect(() => first.read()).to.throw();
-      expect(() => second.read()).to.throw();
-
-      const configFile = new ConfigFile(
-        [getBaseConfigFactory(homeDir)()],
-        CURRENT_FORMAT_VERSION,
-        'abcdef12',
-        'base',
-        null,
-      );
+      expect(seen).to.equal('written-by-someone-else');
+    });
 
-      first.write(configFile);
+    it('should return the state it saved', () => {
+      seedConfigFile();
 
-      const onDisk = fs.readFileSync(configFilePath, 'utf8');
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
 
-      let thrown;
-      try {
-        second.write(configFile);
-      } catch (e) {
-        thrown = e;
-      }
+      const configFile = repository.update((freshConfigFile) => {
+        freshConfigFile.getConfig('base').set('description', 'returned');
+      });
 
-      expect(thrown, 'second first-run write must not clobber the first').to.exist();
-      expect(thrown.code).to.equal('DASHMATE_CONFIG_FILE_CONFLICT');
-      expect(fs.readFileSync(configFilePath, 'utf8')).to.equal(onDisk);
+      expect(configFile.getConfig('base').get('description')).to.equal('returned');
+      expect(configFile.isChanged()).to.be.false();
     });
 
-    // Present-to-absent is a change like any other. Recreating our old snapshot
-    // over a deliberate removal is the same lost update in the other direction.
-    it('should refuse to recreate a config file that was deleted after it was read', () => {
-      seedConfigFile();
+    it('should not write when the mutator throws', () => {
+      const before = seedConfigFile();
 
       const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const configFile = repository.read();
-
-      fs.unlinkSync(configFilePath);
 
-      configFile.getConfig('base').set('description', 'stale-snapshot');
+      expect(() => repository.update(() => {
+        throw new Error('mutator failed');
+      })).to.throw('mutator failed');
 
-      let thrown;
-      try {
-        repository.write(configFile);
-      } catch (e) {
-        thrown = e;
-      }
-
-      expect(thrown, 'must not resurrect a deleted config file').to.exist();
-      expect(thrown.code).to.equal('DASHMATE_CONFIG_FILE_CONFLICT');
-      expect(fs.existsSync(configFilePath)).to.be.false();
+      expect(fs.readFileSync(configFilePath, 'utf8')).to.equal(before);
+      expect(fs.existsSync(homeDir.joinPath('config.json.lock'))).to.be.false();
     });
 
-    // Comparing against the baseline is not enough on its own: two writers can
-    // both read the same bytes, both decide they are current, and both replace
-    // the file. Only a lock closes that window, and only a genuinely separate
-    // process can prove the lock is honoured. proper-lockfile represents a held
-    // lock as a directory, so the other process needs nothing but `fs`.
-    it('should wait for a lock held by another process before writing', function it0(done) {
+    // Reading fresh inside the lock is only sound if the lock is actually
+    // honoured across processes. proper-lockfile represents a held lock as a
+    // directory, so another process needs nothing but `fs` to hold it.
+    it('should wait for a lock held by another process', function it0(done) {
       this.timeout(20000);
 
       seedConfigFile();
 
       const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const configFile = repository.read();
-
-      configFile.getConfig('base').set('description', 'written-after-waiting');
-
       const lockPath = homeDir.joinPath('config.json.lock');
       const holdMs = 700;
 
@@ -301,10 +266,6 @@ describe('ConfigFileJsonRepository', () => {
 
       lockHolder.on('error', done);
 
-      // Wait for the other process to actually take the lock. Synchronous on
-      // purpose - the write we are about to make is synchronous too.
-      // Polled with a real sleep rather than a tight loop - spinning here would
-      // peg a CI core for the whole timeout whenever the child fails to start.
       const deadline = Date.now() + 10000;
       while (!fs.existsSync(lockPath) && Date.now() < deadline) {
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
@@ -314,13 +275,11 @@ describe('ConfigFileJsonRepository', () => {
 
       const startedAt = Date.now();
 
-      repository.write(configFile);
-
-      const waitedMs = Date.now() - startedAt;
+      repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'written-after-waiting');
+      });
 
-      // It blocked rather than writing straight through the other holder.
-      expect(waitedMs).to.be.at.least(holdMs / 2);
-      expect(fs.existsSync(lockPath), 'lock should be released again').to.be.false();
+      expect(Date.now() - startedAt).to.be.at.least(holdMs / 2);
 
       const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
 
@@ -328,26 +287,5 @@ describe('ConfigFileJsonRepository', () => {
 
       lockHolder.on('exit', () => done());
     });
-
-    it('should succeed after reloading following a conflict', () => {
-      seedConfigFile();
-
-      const slowReader = new ConfigFileJsonRepository(identityMigration, homeDir);
-      slowReader.read();
-
-      const writer = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const freshConfigFile = writer.read();
-      freshConfigFile.getConfig('base').set('description', 'concurrent');
-      writer.write(freshConfigFile);
-
-      const reloaded = slowReader.read();
-      reloaded.getConfig('base').set('description', 'after-reload');
-
-      expect(() => slowReader.write(reloaded)).to.not.throw();
-
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
-
-      expect(reread.getConfig('base').get('description')).to.equal('after-reload');
-    });
   });
 });

From 95611b9766ae57799681e9e4c6c8803ae00e7644 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Thu, 30 Jul 2026 21:02:44 +0700
Subject: [PATCH 06/11] fix(dashmate): change config through one locked step in
 every config command

`config set` already read, changed and saved as one step; `create`, `remove`,
`default` and `group default` still mutated the config file loaded at startup and
relied on it being saved on exit, so they could revert a change another command
saved while they ran.

`config remove` also deleted the service directory before that save, so a failed
save left a config listed in config.json with nothing on disk behind it. The
directory is now deleted only once the removal is saved, and removing a config
another command already removed fails before anything is written.

`config create` renders the new config's service files itself. It used to get
that from the generic save-on-exit, which no longer sees a change because the
config file handed to the command is deliberately not the one that was modified.

Verified end to end for each command: the change reaches disk and the config file
loaded at startup is left untouched, which is what stops the generic save from
writing a pre-command snapshot afterwards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../dashmate/src/commands/config/create.js    |  12 +-
 .../dashmate/src/commands/config/default.js   |   7 +-
 .../dashmate/src/commands/config/remove.js    |  11 +-
 .../dashmate/src/commands/group/default.js    |   7 +-
 .../commands/config/mutatingCommands.spec.js  | 128 ++++++++++++++++++
 5 files changed, 161 insertions(+), 4 deletions(-)
 create mode 100644 packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js

diff --git a/packages/dashmate/src/commands/config/create.js b/packages/dashmate/src/commands/config/create.js
index c567251949e..26edeaaffb3 100644
--- a/packages/dashmate/src/commands/config/create.js
+++ b/packages/dashmate/src/commands/config/create.js
@@ -31,8 +31,18 @@ export default class ConfigCreateCommand extends BaseCommand {
     },
     flags,
     configFile,
+    configFileRepository,
+    writeConfigTemplates,
   ) {
-    configFile.createConfig(configName, fromConfigName);
+    // Read, change and save in one locked step, so a config created here cannot
+    // revert a change another command saved in the meantime.
+    const freshConfigFile = configFileRepository.update((updatedConfigFile) => {
+      updatedConfigFile.createConfig(configName, fromConfigName);
+    });
+
+    // The new config needs its service files rendered, and the config file this
+    // command was handed at startup is deliberately not the one that changed.
+    writeConfigTemplates(freshConfigFile.getConfig(configName));
 
     // eslint-disable-next-line no-console
     console.log(`${configName} created`);
diff --git a/packages/dashmate/src/commands/config/default.js b/packages/dashmate/src/commands/config/default.js
index 91a67d25a33..d4ba6110c8f 100644
--- a/packages/dashmate/src/commands/config/default.js
+++ b/packages/dashmate/src/commands/config/default.js
@@ -30,12 +30,17 @@ Shows default config name or sets another config as default
     },
     flags,
     configFile,
+    configFileRepository,
   ) {
     if (configName === null) {
       // eslint-disable-next-line no-console
       console.log(configFile.getDefaultConfigName());
     } else {
-      configFile.setDefaultConfigName(configName);
+      // Read, change and save in one locked step, so pointing the default at a
+      // config cannot revert a change another command saved in the meantime.
+      configFileRepository.update((freshConfigFile) => {
+        freshConfigFile.setDefaultConfigName(configName);
+      });
 
       // eslint-disable-next-line no-console
       console.log(`${configName} config set as default`);
diff --git a/packages/dashmate/src/commands/config/remove.js b/packages/dashmate/src/commands/config/remove.js
index 99d58730002..a694355ed2d 100644
--- a/packages/dashmate/src/commands/config/remove.js
+++ b/packages/dashmate/src/commands/config/remove.js
@@ -32,6 +32,7 @@ export default class ConfigRemoveCommand extends BaseCommand {
     configFile,
     defaultConfigs,
     homeDir,
+    configFileRepository,
   ) {
     if (defaultConfigs.has(configName)) {
       throw new Error(`system config ${configName} can't be removed.\nPlease use 'dashmate reset --hard --config=${configName}' command to reset the configuration`);
@@ -39,8 +40,16 @@ export default class ConfigRemoveCommand extends BaseCommand {
 
     const serviceConfigsPath = resolveConfigDirectory(homeDir, configName);
 
-    configFile.removeConfig(configName);
+    // Read, change and save in one locked step. Removing from the state loaded
+    // at startup would revert anything another command saved in the meantime,
+    // and removing a config another command already removed now fails here
+    // instead of writing.
+    configFileRepository.update((freshConfigFile) => {
+      freshConfigFile.removeConfig(configName);
+    });
 
+    // Only once the removal is saved. Deleting first would leave the service
+    // files gone while config.json still listed the config if saving failed.
     fs.rmSync(serviceConfigsPath, {
       recursive: true,
       force: true,
diff --git a/packages/dashmate/src/commands/group/default.js b/packages/dashmate/src/commands/group/default.js
index 775ec88352a..141ea558e66 100644
--- a/packages/dashmate/src/commands/group/default.js
+++ b/packages/dashmate/src/commands/group/default.js
@@ -30,12 +30,17 @@ Shows default group name or sets another group as default
     },
     flags,
     configFile,
+    configFileRepository,
   ) {
     if (groupName === null) {
       // eslint-disable-next-line no-console
       console.log(configFile.getDefaultGroupName());
     } else {
-      configFile.setDefaultGroupName(groupName);
+      // Read, change and save in one locked step, so pointing the default at a
+      // group cannot revert a change another command saved in the meantime.
+      configFileRepository.update((freshConfigFile) => {
+        freshConfigFile.setDefaultGroupName(groupName);
+      });
 
       // eslint-disable-next-line no-console
       console.log(`${groupName} group set as default`);
diff --git a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
new file mode 100644
index 00000000000..bba4f2b73a2
--- /dev/null
+++ b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
@@ -0,0 +1,128 @@
+import fs from 'fs';
+import HomeDir from '../../../../src/config/HomeDir.js';
+import ConfigFile from '../../../../src/config/configFile/ConfigFile.js';
+import ConfigFileJsonRepository from '../../../../src/config/configFile/ConfigFileJsonRepository.js';
+import getBaseConfigFactory from '../../../../configs/defaults/getBaseConfigFactory.js';
+import ConfigCreateCommand from '../../../../src/commands/config/create.js';
+import ConfigDefaultCommand from '../../../../src/commands/config/default.js';
+import ConfigRemoveCommand from '../../../../src/commands/config/remove.js';
+
+/**
+ * These commands change the config file as one locked step rather than mutating
+ * the config file they were handed at startup. Two properties matter and are
+ * asserted for each: the change reaches disk, and the object loaded at startup
+ * is left alone - if a command mutated that instead, `BaseCommand.finally()`
+ * would save it afterwards and write a snapshot from before the command ran.
+ */
+describe('Config mutating commands', () => {
+  const flags = {};
+  const noTemplates = () => {};
+
+  let homeDir;
+  let loadedConfigFile;
+  let configFileRepository;
+
+  function reread() {
+    return new ConfigFileJsonRepository((data) => data, homeDir).read();
+  }
+
+  beforeEach(() => {
+    homeDir = HomeDir.createTemp();
+
+    const configFile = new ConfigFile(
+      [getBaseConfigFactory(homeDir)()],
+      '4.1.0',
+      'abcdef12',
+      'base',
+      null,
+    );
+
+    fs.writeFileSync(
+      homeDir.joinPath('config.json'),
+      `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`,
+      'utf8',
+    );
+
+    configFileRepository = new ConfigFileJsonRepository((data) => data, homeDir);
+    loadedConfigFile = configFileRepository.read();
+  });
+
+  afterEach(() => {
+    homeDir.remove();
+  });
+
+  describe('config create', () => {
+    it('should save the new config without touching the config file loaded at startup', async () => {
+      await new ConfigCreateCommand().runWithDependencies(
+        { config: 'node1', from: 'base' },
+        flags,
+        loadedConfigFile,
+        configFileRepository,
+        noTemplates,
+      );
+
+      expect(reread().isConfigExists('node1')).to.be.true();
+      expect(loadedConfigFile.isConfigExists('node1')).to.be.false();
+      expect(loadedConfigFile.isChanged()).to.be.false();
+    });
+  });
+
+  describe('config default', () => {
+    it('should save the new default without touching the config file loaded at startup', async () => {
+      await new ConfigDefaultCommand().runWithDependencies(
+        { config: 'base' },
+        flags,
+        loadedConfigFile,
+        configFileRepository,
+      );
+
+      expect(reread().getDefaultConfigName()).to.equal('base');
+      expect(loadedConfigFile.isChanged()).to.be.false();
+    });
+  });
+
+  describe('config remove', () => {
+    beforeEach(async () => {
+      await new ConfigCreateCommand().runWithDependencies(
+        { config: 'node1', from: 'base' },
+        flags,
+        loadedConfigFile,
+        configFileRepository,
+        noTemplates,
+      );
+
+      fs.mkdirSync(homeDir.joinPath('node1'), { recursive: true });
+    });
+
+    it('should save the removal and then delete the service directory', async () => {
+      await new ConfigRemoveCommand().runWithDependencies(
+        { config: 'node1' },
+        flags,
+        loadedConfigFile,
+        { has: () => false },
+        homeDir,
+        configFileRepository,
+      );
+
+      expect(reread().isConfigExists('node1')).to.be.false();
+      expect(fs.existsSync(homeDir.joinPath('node1'))).to.be.false();
+    });
+
+    // The service files are what a node actually runs from. Deleting them before
+    // the removal is saved would leave a config listed in config.json with
+    // nothing on disk behind it.
+    it('should leave the service directory alone when the removal cannot be saved', async () => {
+      await new ConfigRemoveCommand().runWithDependencies(
+        { config: 'does-not-exist' },
+        flags,
+        loadedConfigFile,
+        { has: () => false },
+        homeDir,
+        configFileRepository,
+      ).catch(() => {});
+
+      expect(fs.existsSync(homeDir.joinPath('node1'))).to.be.true();
+      expect(reread().isConfigExists('node1')).to.be.true();
+    });
+  });
+});

From dd795e922a1a21fbd5e78882cf9e77bada3abb65 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Thu, 30 Jul 2026 21:11:49 +0700
Subject: [PATCH 07/11] fix(dashmate): hold the config lock for commands that
 reconfigure a node
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`setup`, `reset`, `group reset` and `ssl obtain` change configuration repeatedly
while doing long, partly irreversible work. They still loaded config when they
started and saved it when they finished, so a `config set` running in between was
reverted — the one case the locked read-change-save step could not cover, since
their changes are not a single self-contained edit.

They now take the lock before reading, via `static mutatesConfig = true`, and hold
it for the run. Reading inside the lock is what makes their state current: there
is no window left for another writer. Read-only commands take no lock, so a node
can still be inspected while it is being set up.

Three things this needs to be safe:

- The lock is reused, not re-taken, by `update()` and `write()` during the
  command. Taking it again would leave the command waiting on itself until the
  acquire timeout — verified: removing the guard fails the new test with "Lock
  file is already being held" after 15s.
- Release covers every way out: normal finish, command failure, a failure before
  the command body runs, and graceful shutdown. It is idempotent so those paths
  need not coordinate.
- A lock lost while we believed we held it now blocks the next save instead of
  being ignored. Ignoring it was right when the lock only narrowed a window;
  it is not right when the lock is what provides exclusivity.

The stale threshold moves to 60s so a long command cannot have its live lock
stolen during a synchronous stretch, while the acquire wait drops to 15s so a
waiting command reports quickly rather than stalling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/dashmate/docs/config/index.md        |  18 ++-
 packages/dashmate/src/commands/group/reset.js |   4 +
 packages/dashmate/src/commands/reset.js       |   4 +
 packages/dashmate/src/commands/setup.js       |   4 +
 packages/dashmate/src/commands/ssl/obtain.js  |   4 +
 .../configFile/ConfigFileJsonRepository.js    | 129 ++++++++++++++----
 .../dashmate/src/oclif/command/BaseCommand.js |  34 ++++-
 .../ConfigFileJsonRepository.spec.js          |  59 ++++++++
 8 files changed, 224 insertions(+), 32 deletions(-)

diff --git a/packages/dashmate/docs/config/index.md b/packages/dashmate/docs/config/index.md
index 708ec403dee..a7570cf6063 100644
--- a/packages/dashmate/docs/config/index.md
+++ b/packages/dashmate/docs/config/index.md
@@ -194,10 +194,16 @@ held for a read and a write.
 Read-only commands such as `dashmate config get`, `dashmate status` and `dashmate core cli`
 never write configuration at all, so they are always safe to run alongside anything else.
 
-### Limits
+### While a node is being reconfigured
 
-Long-running commands that reconfigure a node — `dashmate setup`, `dashmate reset` and
-`dashmate ssl obtain` — still load the configuration when they start and save it when they
-finish. Do not change configuration with `dashmate config set` while one of those is
-running: the long-running command saves the state it loaded, and an option changed in the
-meantime is lost.
+`dashmate setup`, `dashmate reset` and `dashmate ssl obtain` change configuration
+repeatedly while doing long work, so they take the lock for their whole run. Another
+command that changes configuration waits briefly and then reports that something else is
+modifying it — nothing is lost, and running it again once the first command finishes
+works normally.
+
+Reading is never affected: `dashmate status`, `dashmate config get` and `dashmate core cli`
+do not take the lock at all, so a node can still be inspected while it is being set up.
+
+If a command holding the lock is killed, the lock is released. If the machine loses power
+mid-command, the next writer takes over after about a minute.
diff --git a/packages/dashmate/src/commands/group/reset.js b/packages/dashmate/src/commands/group/reset.js
index 2f3128014a7..a16b95c88ef 100644
--- a/packages/dashmate/src/commands/group/reset.js
+++ b/packages/dashmate/src/commands/group/reset.js
@@ -5,6 +5,10 @@ import MuteOneLineError from '../../oclif/errors/MuteOneLineError.js';
 import { PRESET_LOCAL } from '../../constants.js';
 
 export default class GroupResetCommand extends GroupBaseCommand {
+  // Reconfigures the node: changes configuration repeatedly while doing long,
+  // partly irreversible work, so it holds the config lock for its whole run.
+  static mutatesConfig = true;
+
   static description = 'Reset group nodes';
 
   static flags = {
diff --git a/packages/dashmate/src/commands/reset.js b/packages/dashmate/src/commands/reset.js
index 571b3b2ff31..2c9f2fe461c 100644
--- a/packages/dashmate/src/commands/reset.js
+++ b/packages/dashmate/src/commands/reset.js
@@ -5,6 +5,10 @@ import ConfigBaseCommand from '../oclif/command/ConfigBaseCommand.js';
 import MuteOneLineError from '../oclif/errors/MuteOneLineError.js';
 
 export default class ResetCommand extends ConfigBaseCommand {
+  // Reconfigures the node: changes configuration repeatedly while doing long,
+  // partly irreversible work, so it holds the config lock for its whole run.
+  static mutatesConfig = true;
+
   static description = 'Reset node data';
 
   static flags = {
diff --git a/packages/dashmate/src/commands/setup.js b/packages/dashmate/src/commands/setup.js
index f3ca8217c83..bb79bf928bc 100644
--- a/packages/dashmate/src/commands/setup.js
+++ b/packages/dashmate/src/commands/setup.js
@@ -13,6 +13,10 @@ import {
 } from '../constants.js';
 
 export default class SetupCommand extends BaseCommand {
+  // Reconfigures the node: changes configuration repeatedly while doing long,
+  // partly irreversible work, so it holds the config lock for its whole run.
+  static mutatesConfig = true;
+
   static description = 'Set up a new Dash node';
 
   static args = {
diff --git a/packages/dashmate/src/commands/ssl/obtain.js b/packages/dashmate/src/commands/ssl/obtain.js
index 754b6d1e6bc..4223b102dbd 100644
--- a/packages/dashmate/src/commands/ssl/obtain.js
+++ b/packages/dashmate/src/commands/ssl/obtain.js
@@ -7,6 +7,10 @@ import LegoCertificate from '../../ssl/letsencrypt/LegoCertificate.js';
 import { SSL_PROVIDERS } from '../../constants.js';
 
 export default class ObtainCommand extends ConfigBaseCommand {
+  // Reconfigures the node: changes configuration repeatedly while doing long,
+  // partly irreversible work, so it holds the config lock for its whole run.
+  static mutatesConfig = true;
+
   static description = `Obtain SSL certificate
 
 Create a new SSL certificate or download an already existing one using ZeroSSL or Let's Encrypt as provider
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index 4f505b43207..406b28c0d2d 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -12,18 +12,24 @@ import ConfigFile from './ConfigFile.js';
 
 /**
  * How long a lock may go un-refreshed before another process may break it.
- * Comfortably longer than the milliseconds the lock is actually held, so a busy
- * event loop cannot get its live lock stolen, but short enough that a process
- * killed while holding it does not block the next command for long.
+ *
+ * A command that reconfigures a node holds this across its whole run, and the
+ * refresh that keeps it alive cannot happen while the event loop is busy - so
+ * this has to comfortably outlast the longest synchronous stretch such a command
+ * has, or its live lock gets stolen and two processes write. The cost of the
+ * generous value is that a process killed while holding the lock blocks the next
+ * writer for this long.
  */
-const LOCK_STALE_MS = 10000;
+const LOCK_STALE_MS = 60000;
 
 /**
- * Waiting is synchronous, which means signal handlers do not run while it is in
- * progress. Kept just above the stale threshold - long enough to outlast a dead
- * holder's lock, short enough that Ctrl-C is never ignored for long.
+ * How long to wait for someone else's lock before giving up.
+ *
+ * Deliberately much shorter than the stale threshold: waiting is synchronous, so
+ * signal handlers do not run meanwhile, and an operator is better served by a
+ * quick "something else is changing configuration" than by a long silent stall.
  */
-const LOCK_ACQUIRE_TIMEOUT_MS = LOCK_STALE_MS + 2000;
+const LOCK_ACQUIRE_TIMEOUT_MS = 15000;
 
 const LOCK_RETRY_INTERVAL_MS = 50;
 
@@ -38,6 +44,23 @@ function sleepSync(ms) {
 }
 
 export default class ConfigFileJsonRepository {
+  /**
+   * Release function for a lock held across a whole command, or null when this
+   * process is not holding one.
+   *
+   * @type {function|null}
+   */
+  #heldRelease = null;
+
+  /**
+   * Set when the lock was lost while we believed we still held it. Continuing
+   * would mean writing without exclusivity, which is the lost update this exists
+   * to prevent, so the next save refuses instead.
+   *
+   * @type {boolean}
+   */
+  #compromised = false;
+
   /**
    * @param {migrateConfigFile} migrateConfigFile
    * @param {HomeDir} homeDir
@@ -133,9 +156,7 @@ export default class ConfigFileJsonRepository {
    * @returns {ConfigFile} the state that was saved
    */
   update(mutate, options = {}) {
-    const release = this.#acquireLock();
-
-    try {
+    return this.#locked(() => {
       const configFile = this.read(options);
 
       mutate(configFile);
@@ -143,6 +164,65 @@ export default class ConfigFileJsonRepository {
       this.#save(configFile);
 
       return configFile;
+    });
+  }
+
+  /**
+   * Hold the lock for as long as this process is changing configuration.
+   *
+   * For a command that reconfigures a node over minutes, taking the lock before
+   * it reads is what makes its state current: there is no window between reading
+   * and saving for another process to write into. Short changes should use
+   * update() instead - this blocks every other writer until release() is called.
+   *
+   * Calling it again while already held does nothing, so a command holding the
+   * lock can still call update() and write() normally.
+   *
+   * @returns {void}
+   */
+  acquire() {
+    if (this.#heldRelease !== null) {
+      return;
+    }
+
+    this.#compromised = false;
+    this.#heldRelease = this.#acquireLock();
+  }
+
+  /**
+   * Give up a lock taken with acquire(). Safe to call when not holding one, so
+   * it can be used from every exit path without checking first.
+   *
+   * @returns {void}
+   */
+  release() {
+    if (this.#heldRelease === null) {
+      return;
+    }
+
+    const release = this.#heldRelease;
+
+    this.#heldRelease = null;
+
+    this.#release(release);
+  }
+
+  /**
+   * Run fn with the lock held, taking it only if this process is not already
+   * holding one across a command.
+   *
+   * @param {function(): *} fn
+   * @returns {*}
+   */
+  #locked(fn) {
+    if (this.#heldRelease !== null) {
+      return fn();
+    }
+
+    const release = this.#acquireLock();
+
+    try {
+      return fn();
     } finally {
       this.#release(release);
     }
@@ -160,13 +240,7 @@ export default class ConfigFileJsonRepository {
    * @returns {void}
    */
   write(configFile) {
-    const release = this.#acquireLock();
-
-    try {
-      this.#save(configFile);
-    } finally {
-      this.#release(release);
-    }
+    this.#locked(() => this.#save(configFile));
   }
 
   /**
@@ -177,6 +251,12 @@ export default class ConfigFileJsonRepository {
    * @param {ConfigFile} configFile
    */
   #save(configFile) {
+    if (this.#compromised) {
+      throw new Error(`Lost the lock on '${this.configFilePath}' while changing it,`
+        + ' so saving now could overwrite another process. Nothing was written -'
+        + ' re-run the command.');
+    }
+
     const configFileJSON = `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`;
 
     writeFileAtomic.sync(this.configFilePath, configFileJSON, 'utf8');
@@ -223,12 +303,13 @@ export default class ConfigFileJsonRepository {
           // realpath resolution would fail on it.
           realpath: false,
           stale: LOCK_STALE_MS,
-          // The library's default handler rethrows from a refresh timer rather
-          // than this call stack, which would take the whole process down. The
-          // critical section is a read, a mutation and a rename, so it finishes
-          // well inside the stale threshold and a compromised lock is not a
-          // condition this can act on.
-          onCompromised: () => {},
+          // Rethrowing here would kill the process - the handler runs from a
+          // refresh timer, not this call stack. Recording it instead lets the
+          // next save refuse, which matters because a command holding the lock
+          // across its run relies on it for exclusivity.
+          onCompromised: () => {
+            this.#compromised = true;
+          },
         });
       } catch (e) {
         if (e.code !== 'ELOCKED' || Date.now() >= deadline) {
diff --git a/packages/dashmate/src/oclif/command/BaseCommand.js b/packages/dashmate/src/oclif/command/BaseCommand.js
index 2390d75d696..1cc3aa6d063 100644
--- a/packages/dashmate/src/oclif/command/BaseCommand.js
+++ b/packages/dashmate/src/oclif/command/BaseCommand.js
@@ -38,6 +38,15 @@ export default class BaseCommand extends Command {
      */
     const configFileRepository = this.container.resolve('configFileRepository');
 
+    // A command that reconfigures a node changes config repeatedly while doing
+    // long work, so it takes the lock before reading: its state is then current
+    // for the whole run and no other writer can get in between. Everything else
+    // changes config through configFileRepository.update() and needs nothing
+    // here.
+    if (this.constructor.mutatesConfig) {
+      configFileRepository.acquire();
+    }
+
     let configFile;
     try {
       // Load config collection from config file
@@ -81,6 +90,12 @@ export default class BaseCommand extends Command {
 
       // stop and remove all started containers
       await stopAllContainers(startedContainers.getContainers());
+
+      // A lock held across this command would otherwise survive until it goes
+      // stale, blocking the next writer for no reason.
+      if (this.constructor.mutatesConfig) {
+        this.container.resolve('configFileRepository').release();
+      }
     });
   }
 
@@ -97,6 +112,23 @@ export default class BaseCommand extends Command {
   }
 
   async finally(err) {
+    try {
+      await this.saveConfigAndStopContainers(err);
+    } finally {
+      // Whether the command succeeded, failed, or failed before it started, the
+      // lock must not outlive it.
+      if (this.container && this.constructor.mutatesConfig) {
+        this.container.resolve('configFileRepository').release();
+      }
+    }
+
+    return super.finally(err);
+  }
+
+  /**
+   * @param {Error|undefined} err
+   */
+  async saveConfigAndStopContainers(err) {
     // Save configs collection
     if (this.container) {
       /**
@@ -142,7 +174,5 @@ export default class BaseCommand extends Command {
         },
       );
     }
-
-    return super.finally(err);
   }
 }
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index 3a1dc1641e3..4b9c16324a6 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -245,6 +245,65 @@ describe('ConfigFileJsonRepository', () => {
       expect(fs.existsSync(homeDir.joinPath('config.json.lock'))).to.be.false();
     });
 
+    // A command that reconfigures a node holds the lock for its whole run and
+    // still saves through the ordinary paths. Taking the lock again for each of
+    // those saves would leave it waiting on itself until the acquire timeout.
+    it('should let a held lock be used by update() and write() without deadlocking', function it1() {
+      this.timeout(10000);
+
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+
+      repository.acquire();
+
+      try {
+        repository.update((configFile) => {
+          configFile.getConfig('base').set('description', 'via-update');
+        });
+
+        const configFile = repository.read();
+        configFile.getConfig('base').set('description', 'via-write');
+        repository.write(configFile);
+      } finally {
+        repository.release();
+      }
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('via-write');
+    });
+
+    it('should hold the lock between acquire and release, and free it after', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const lockPath = homeDir.joinPath('config.json.lock');
+
+      repository.acquire();
+
+      expect(fs.existsSync(lockPath)).to.be.true();
+
+      repository.release();
+
+      expect(fs.existsSync(lockPath)).to.be.false();
+    });
+
+    // Release runs from several exit paths - normal finish, command failure and
+    // graceful shutdown - so calling it when nothing is held has to be harmless.
+    it('should tolerate release without acquire, and repeated release', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+
+      expect(() => repository.release()).to.not.throw();
+
+      repository.acquire();
+      repository.release();
+
+      expect(() => repository.release()).to.not.throw();
+    });
+
     // Reading fresh inside the lock is only sound if the lock is actually
     // honoured across processes. proper-lockfile represents a held lock as a
     // directory, so another process needs nothing but `fs` to hold it.

From 7514eff1f2db3002dc0abf36625b0343eca60fb2 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Thu, 30 Jul 2026 21:30:15 +0700
Subject: [PATCH 08/11] test(dashmate): cover the config lock paths that only
 happen after a wait
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Losing a held lock and giving up waiting for someone else's were both reachable
only after seconds of real time, so neither was tested — the compromise handling
in particular rested on reading the code.

Lock timings are now injectable, which lets both run in about a second. They are
real regression tests: with the previous no-op compromise handler, saving after
losing the lock succeeds and the test fails.

Waiting too long now reports in dashmate's terms — which command is holding
configuration and what to do — instead of surfacing the locking library's "Lock
file is already being held".

Worth recording, since it is not obvious and it sets the floor on how fast a lost
lock can possibly be noticed: proper-lockfile clamps `stale` to at least 2s and
the refresh that detects loss to at least 1s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../configFile/ConfigFileJsonRepository.js    | 20 +++++--
 packages/dashmate/src/createDIContainer.js    |  1 +
 .../ConfigFileJsonRepository.spec.js          | 57 +++++++++++++++++++
 3 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index 406b28c0d2d..b8c97064dce 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -64,10 +64,16 @@ export default class ConfigFileJsonRepository {
   /**
    * @param {migrateConfigFile} migrateConfigFile
    * @param {HomeDir} homeDir
+   * @param {Object} [configFileLockOptions={}] - overrides for the lock timings,
+   *   so the paths that only happen after seconds of waiting can be exercised
+   * @param {number} [configFileLockOptions.stale]
+   * @param {number} [configFileLockOptions.acquireTimeout]
    */
-  constructor(migrateConfigFile, homeDir) {
+  constructor(migrateConfigFile, homeDir, configFileLockOptions = {}) {
     this.migrateConfigFile = migrateConfigFile;
     this.ajv = new Ajv();
+    this.lockStaleMs = configFileLockOptions.stale ?? LOCK_STALE_MS;
+    this.lockAcquireTimeoutMs = configFileLockOptions.acquireTimeout ?? LOCK_ACQUIRE_TIMEOUT_MS;
     this.configFilePath = homeDir.joinPath('config.json');
     // Locking a sibling rather than the config file itself keeps first run
     // working, where there is no config file to lock yet.
@@ -293,7 +299,7 @@ export default class ConfigFileJsonRepository {
    * @returns {function} release
    */
   #acquireLock() {
-    const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS;
+    const deadline = Date.now() + this.lockAcquireTimeoutMs;
 
     for (;;) {
       try {
@@ -302,7 +308,7 @@ export default class ConfigFileJsonRepository {
           // The config file legitimately does not exist on first run, and
           // realpath resolution would fail on it.
           realpath: false,
-          stale: LOCK_STALE_MS,
+          stale: this.lockStaleMs,
           // Rethrowing here would kill the process - the handler runs from a
           // refresh timer, not this call stack. Recording it instead lets the
           // next save refuse, which matters because a command holding the lock
@@ -312,10 +318,16 @@ export default class ConfigFileJsonRepository {
           },
         });
       } catch (e) {
-        if (e.code !== 'ELOCKED' || Date.now() >= deadline) {
+        if (e.code !== 'ELOCKED') {
           throw e;
         }
 
+        if (Date.now() >= deadline) {
+          throw new Error(`Timed out waiting to change '${this.configFilePath}'.`
+            + ' Another dashmate command is modifying configuration - wait for it'
+            + ' to finish and run this again.');
+        }
+
         sleepSync(LOCK_RETRY_INTERVAL_MS);
       }
     }
diff --git a/packages/dashmate/src/createDIContainer.js b/packages/dashmate/src/createDIContainer.js
index 876a2c00d4b..1ba03ae1b43 100644
--- a/packages/dashmate/src/createDIContainer.js
+++ b/packages/dashmate/src/createDIContainer.js
@@ -149,6 +149,7 @@ export default async function createDIContainer(options = {}) {
       HomeDir.createWithPathOrDefault(options.DASHMATE_HOME_DIR)
     )).singleton(),
     getServiceList: asFunction(getServiceListFactory).singleton(),
+    configFileLockOptions: asValue({}),
     configFileRepository: asClass(ConfigFileJsonRepository).singleton(),
     getBaseConfig: asFunction(getBaseConfigFactory).singleton(),
     getLocalConfig: asFunction(getLocalConfigFactory).singleton(),
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index 4b9c16324a6..328a31f6c5b 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -304,6 +304,63 @@ describe('ConfigFileJsonRepository', () => {
       expect(() => repository.release()).to.not.throw();
     });
 
+    // Exclusivity is the whole guarantee for a command that holds the lock across
+    // its run, so losing it has to stop the save rather than pass unnoticed.
+    // Reproduced by removing the lock directory out from under a live holder and
+    // letting its refresh discover that, which is what a stolen lock looks like.
+    it('should refuse to save after losing a lock it believed it held', async function it2() {
+      this.timeout(10000);
+
+      seedConfigFile();
+
+      // proper-lockfile floors `stale` at 2s and the refresh that detects loss at
+      // 1s, so this is as fast as the path can be made to happen.
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, {
+        stale: 2000,
+      });
+
+      repository.acquire();
+
+      try {
+        fs.rmdirSync(homeDir.joinPath('config.json.lock'));
+
+        await new Promise((resolve) => { setTimeout(resolve, 1500); });
+
+        expect(() => repository.update((configFile) => {
+          configFile.getConfig('base').set('description', 'must-not-be-saved');
+        })).to.throw('Lost the lock');
+      } finally {
+        repository.release();
+      }
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+
+      expect(reread.getConfig('base').get('description')).to.not.equal('must-not-be-saved');
+    });
+
+    // A waiter should be told what is happening in dashmate's terms, and only
+    // after actually waiting - not handed the locking library's wording.
+    it('should give up waiting for another holder with an actionable error', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, {
+        acquireTimeout: 700,
+      });
+
+      // Someone else holds it, exactly as proper-lockfile represents it
+      fs.mkdirSync(homeDir.joinPath('config.json.lock'));
+
+      const startedAt = Date.now();
+
+      expect(() => repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'never-applied');
+      })).to.throw('Another dashmate command is modifying configuration');
+
+      expect(Date.now() - startedAt).to.be.at.least(600);
+
+      fs.rmdirSync(homeDir.joinPath('config.json.lock'));
+    });
+
     // Reading fresh inside the lock is only sound if the lock is actually
     // honoured across processes. proper-lockfile represents a held lock as a
     // directory, so another process needs nothing but `fs` to hold it.

From aae33085843aabd6107aa226126cca333dc23ad6 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Thu, 30 Jul 2026 22:18:33 +0700
Subject: [PATCH 09/11] fix(dashmate): make one locked step the only way config
 reaches disk
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Converting the config commands left two mechanisms writing configuration, and
the older one could still overwrite the newer. A cross-model review found five
ways that showed up; all of them come from the generic save-on-exit persisting a
copy loaded before the command ran.

- `BaseCommand.finally()` now saves only for commands that hold the lock for
  their whole run. They read inside the lock, so their copy is current. Every
  other command changes configuration through `update()`, and saving its startup
  copy afterwards would revert whatever that produced — most visibly on a config
  file needing migration, where `config set` would have reverted its own change.
- Migrating is saved where it happens, at startup, instead of being carried to
  the end of the command as a pending change.
- `update()` creates the config file when there is none, so `config create` and
  friends work on first run. They previously threw `ConfigFileNotFoundError`
  after `BaseCommand` had built defaults that only the old save-on-exit knew
  about.
- Rendering service files and removing a config's directory happen inside the
  lock, so two commands cannot save in one order and take effect in the other,
  and a removal cannot delete files a concurrent re-creation just wrote.
- `ssl obtain` renders its own templates. Saving marks the configs clean, so
  nothing later knew the new certificate had to reach the gateway config.
- Local group start and restart save the generated miner address as its own
  locked step rather than leaving it for exit, which would have written a copy
  from before a start that runs for tens of minutes.
- Helper certificate renewal re-applies its result onto current state. It holds
  its copy for the life of the process — months — so saving that copy reverted
  everything changed on the node since it started.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/dashmate/scripts/helper.js           |  6 +-
 .../dashmate/src/commands/config/create.js    | 10 +--
 .../dashmate/src/commands/config/remove.js    | 13 ++-
 packages/dashmate/src/commands/config/set.js  |  8 +-
 .../configFile/ConfigFileJsonRepository.js    | 20 ++++-
 ...eduleRenewLetsEncryptCertificateFactory.js | 17 +++-
 .../scheduleRenewZeroSslCertificateFactory.js | 17 +++-
 ...obtainLetsEncryptCertificateTaskFactory.js |  7 +-
 .../obtainZeroSSLCertificateTaskFactory.js    |  7 +-
 .../listr/tasks/startGroupNodesTaskFactory.js |  8 ++
 .../dashmate/src/oclif/command/BaseCommand.js | 21 ++++-
 .../commands/config/mutatingCommands.spec.js  |  4 +-
 .../test/unit/commands/config/set.spec.js     |  4 +-
 .../ConfigFileJsonRepository.spec.js          | 80 +++++++++++++------
 14 files changed, 165 insertions(+), 57 deletions(-)

diff --git a/packages/dashmate/scripts/helper.js b/packages/dashmate/scripts/helper.js
index 4fa8bdf7d64..800b3941e32 100644
--- a/packages/dashmate/scripts/helper.js
+++ b/packages/dashmate/scripts/helper.js
@@ -92,10 +92,10 @@ async function removeOrphanedSslContainers(docker) {
 
   const configFile = await configFileRepository.read();
 
-  // Persist config if it was migrated
+  // Persist config if it was migrated. Nothing else here ever saves this copy -
+  // it lives for the life of the process, so it goes stale, and the renewal
+  // re-applies its result onto current state instead.
   if (configFile.isChanged()) {
-    // Captured before the write, which clears these flags once the new state is
-    // on disk.
     const changedConfigs = configFile.getAllConfigs()
       .filter((config) => config.isChanged());
 
diff --git a/packages/dashmate/src/commands/config/create.js b/packages/dashmate/src/commands/config/create.js
index 26edeaaffb3..04f26293bde 100644
--- a/packages/dashmate/src/commands/config/create.js
+++ b/packages/dashmate/src/commands/config/create.js
@@ -36,14 +36,14 @@ export default class ConfigCreateCommand extends BaseCommand {
   ) {
     // Read, change and save in one locked step, so a config created here cannot
     // revert a change another command saved in the meantime.
-    const freshConfigFile = configFileRepository.update((updatedConfigFile) => {
+    configFileRepository.update((updatedConfigFile) => {
       updatedConfigFile.createConfig(configName, fromConfigName);
+    }, {
+      // The new config needs its service files, and rendering them inside the
+      // lock keeps them consistent with what was saved.
+      onSaved: (savedConfigFile) => writeConfigTemplates(savedConfigFile.getConfig(configName)),
     });
 
-    // The new config needs its service files rendered, and the config file this
-    // command was handed at startup is deliberately not the one that changed.
-    writeConfigTemplates(freshConfigFile.getConfig(configName));
-
     // eslint-disable-next-line no-console
     console.log(`${configName} created`);
   }
diff --git a/packages/dashmate/src/commands/config/remove.js b/packages/dashmate/src/commands/config/remove.js
index a694355ed2d..02acbad260c 100644
--- a/packages/dashmate/src/commands/config/remove.js
+++ b/packages/dashmate/src/commands/config/remove.js
@@ -46,13 +46,12 @@ export default class ConfigRemoveCommand extends BaseCommand {
     // instead of writing.
     configFileRepository.update((freshConfigFile) => {
       freshConfigFile.removeConfig(configName);
-    });
-
-    // Only once the removal is saved. Deleting first would leave the service
-    // files gone while config.json still listed the config if saving failed.
-    fs.rmSync(serviceConfigsPath, {
-      recursive: true,
-      force: true,
+    }, {
+      // Only once the removal is saved, and while the lock is still held:
+      // deleting first would leave the service files gone while config.json
+      // still listed the config if saving failed, and deleting after releasing
+      // could remove files a concurrent re-creation had just written.
+      onSaved: () => fs.rmSync(serviceConfigsPath, { recursive: true, force: true }),
     });
 
     // eslint-disable-next-line no-console
diff --git a/packages/dashmate/src/commands/config/set.js b/packages/dashmate/src/commands/config/set.js
index 2dd21090c6c..f4249360e64 100644
--- a/packages/dashmate/src/commands/config/set.js
+++ b/packages/dashmate/src/commands/config/set.js
@@ -68,12 +68,14 @@ Sets a configuration option in the default config
     // anything saved in between.
     const configName = config.getName();
 
-    const configFile = configFileRepository.update((freshConfigFile) => {
+    configFileRepository.update((freshConfigFile) => {
       freshConfigFile.getConfig(configName).set(optionPath, value);
+    }, {
+      // Rendered inside the lock, so two commands changing the same config
+      // cannot save in one order and render in the other.
+      onSaved: (savedConfigFile) => writeConfigTemplates(savedConfigFile.getConfig(configName)),
     });
 
-    writeConfigTemplates(configFile.getConfig(configName));
-
     // eslint-disable-next-line no-console
     console.log(`${optionPath} set to ${optionValue}`);
   }
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index b8c97064dce..74646518b44 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -64,13 +64,15 @@ export default class ConfigFileJsonRepository {
   /**
    * @param {migrateConfigFile} migrateConfigFile
    * @param {HomeDir} homeDir
+   * @param {createConfigFile} createConfigFile
    * @param {Object} [configFileLockOptions={}] - overrides for the lock timings,
    *   so the paths that only happen after seconds of waiting can be exercised
    * @param {number} [configFileLockOptions.stale]
    * @param {number} [configFileLockOptions.acquireTimeout]
    */
-  constructor(migrateConfigFile, homeDir, configFileLockOptions = {}) {
+  constructor(migrateConfigFile, homeDir, createConfigFile, configFileLockOptions = {}) {
     this.migrateConfigFile = migrateConfigFile;
+    this.createConfigFile = createConfigFile;
     this.ajv = new Ajv();
     this.lockStaleMs = configFileLockOptions.stale ?? LOCK_STALE_MS;
     this.lockAcquireTimeoutMs = configFileLockOptions.acquireTimeout ?? LOCK_ACQUIRE_TIMEOUT_MS;
@@ -159,16 +161,30 @@ export default class ConfigFileJsonRepository {
    *
    * @param {function(ConfigFile): void} mutate
    * @param {Object} [options={}] - passed through to read()
+   * @param {function(ConfigFile): void} [options.onSaved] - runs after the save
+   *   and before the lock is released, for effects that must not be reordered
+   *   against it: rendering service files, removing a config's directory
    * @returns {ConfigFile} the state that was saved
    */
   update(mutate, options = {}) {
+    const { onSaved, ...readOptions } = options;
+
     return this.#locked(() => {
-      const configFile = this.read(options);
+      // First run has nothing to read yet, and creating the defaults here rather
+      // than separately keeps that on the same locked path as every other change
+      // - two nodes being set up at once cannot both create the file.
+      const configFile = fs.existsSync(this.configFilePath)
+        ? this.read(readOptions)
+        : this.createConfigFile();
 
       mutate(configFile);
 
       this.#save(configFile);
 
+      if (onSaved) {
+        onSaved(configFile);
+      }
+
       return configFile;
     });
   }
diff --git a/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js b/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js
index f14f1c937a2..d47485994e7 100644
--- a/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js
+++ b/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js
@@ -75,9 +75,20 @@ export default function scheduleRenewLetsEncryptCertificateFactory(
           noRetry: true,
         });
 
-        // Write config files
-        configFileRepository.write(configFile);
-        writeConfigTemplates(config);
+        // This process has held its copy of the config file since it started,
+        // possibly for months, so saving that copy would revert everything
+        // changed on the node since. Re-apply just what the renewal produced
+        // onto the current state instead.
+        const renewedOptions = config.get('platform.gateway.ssl');
+
+        configFileRepository.update((freshConfigFile) => {
+          freshConfigFile.getConfig(config.getName())
+            .set('platform.gateway.ssl', renewedOptions);
+        }, {
+          onSaved: (savedConfigFile) => writeConfigTemplates(
+            savedConfigFile.getConfig(config.getName()),
+          ),
+        });
 
         // Restart Gateway to catch up new SSL certificates
         await dockerCompose.execCommand(config, 'gateway', 'kill -SIGHUP 1');
diff --git a/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js b/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js
index 0526bcc1f97..216b361b4ce 100644
--- a/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js
+++ b/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js
@@ -79,9 +79,20 @@ export default function scheduleRenewZeroSslCertificateFactory(
           noRetry: true,
         });
 
-        // Write config files
-        configFileRepository.write(configFile);
-        writeConfigTemplates(config);
+        // This process has held its copy of the config file since it started,
+        // possibly for months, so saving that copy would revert everything
+        // changed on the node since. Re-apply just what the renewal produced
+        // onto the current state instead.
+        const renewedOptions = config.get('platform.gateway.ssl');
+
+        configFileRepository.update((freshConfigFile) => {
+          freshConfigFile.getConfig(config.getName())
+            .set('platform.gateway.ssl', renewedOptions);
+        }, {
+          onSaved: (savedConfigFile) => writeConfigTemplates(
+            savedConfigFile.getConfig(config.getName()),
+          ),
+        });
 
         // TODO: We can use https://www.envoyproxy.io/docs/envoy/v1.30.1/start/quick-start/configuration-dynamic-filesystem.html#start-quick-start-dynamic-fs-dynamic-lds
         //  to dynamically update envoy configuration without restarting it
diff --git a/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js b/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js
index 0e33318edd7..6f6c8180707 100644
--- a/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js
@@ -16,6 +16,7 @@ const LEGO_IMAGE = 'goacme/lego:v4.31.0';
  * @param {validateLetsEncryptCertificate} validateLetsEncryptCertificate
  * @param {saveCertificateTask} saveCertificateTask
  * @param {ConfigFileJsonRepository} configFileRepository
+ * @param {writeConfigTemplates} writeConfigTemplates
  * @param {ConfigFile} configFile
  * @return {obtainLetsEncryptCertificateTask}
  */
@@ -27,6 +28,7 @@ export default function obtainLetsEncryptCertificateTaskFactory(
   validateLetsEncryptCertificate,
   saveCertificateTask,
   configFileRepository,
+  writeConfigTemplates,
   configFile,
 ) {
   /**
@@ -252,8 +254,11 @@ export default function obtainLetsEncryptCertificateTaskFactory(
           config.set('platform.gateway.ssl.enabled', true);
           config.set('platform.gateway.ssl.provider', 'letsencrypt');
 
-          // Save config file
+          // Save config file. Templates are rendered here too: this command
+          // holds the config lock for its run, and saving marks the configs
+          // clean, so nothing later would know they need re-rendering.
           configFileRepository.write(configFile);
+          writeConfigTemplates(config);
 
           // Save to gateway SSL directory
           return saveCertificateTask(config);
diff --git a/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js b/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js
index a08e7ab7d02..2ef8965b8c2 100644
--- a/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js
@@ -19,6 +19,7 @@ import { ERRORS } from '../../../../ssl/zerossl/validateZeroSslCertificateFactor
  * @param {HomeDir} homeDir
  * @param {validateZeroSslCertificate} validateZeroSslCertificate
  * @param {ConfigFileJsonRepository} configFileRepository
+ * @param {writeConfigTemplates} writeConfigTemplates
  * @param {ConfigFile} configFile
  * @return {obtainZeroSSLCertificateTask}
  */
@@ -35,6 +36,7 @@ export default function obtainZeroSSLCertificateTaskFactory(
   homeDir,
   validateZeroSslCertificate,
   configFileRepository,
+  writeConfigTemplates,
   configFile,
 ) {
   /**
@@ -146,8 +148,11 @@ export default function obtainZeroSSLCertificateTaskFactory(
           config.set('platform.gateway.ssl.provider', 'zerossl');
           config.set('platform.gateway.ssl.providerConfigs.zerossl.id', ctx.certificate.id);
 
-          // Save config file
+          // Save config file. Templates are rendered here too: this command
+          // holds the config lock for its run, and saving marks the configs
+          // clean, so nothing later would know they need re-rendering.
           configFileRepository.write(configFile);
+          writeConfigTemplates(config);
         },
       },
       {
diff --git a/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js b/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
index 53b6762ee1e..60fb8a864b5 100644
--- a/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
@@ -28,6 +28,7 @@ export default function startGroupNodesTaskFactory(
   waitForNodeToBeReadyTask,
   buildServicesTask,
   getConnectionHost,
+  configFileRepository,
 ) {
   /**
    * @typedef {startGroupNodesTask}
@@ -92,6 +93,13 @@ export default function startGroupNodesTaskFactory(
             const privateKey = new PrivateKey();
             minerAddress = privateKey.toAddress('regtest').toString();
 
+            // Saved as its own locked step rather than carried to the end of the
+            // command: starting a group runs for many minutes, and the address is
+            // needed by the miner right now.
+            configFileRepository.update((configFile) => {
+              configFile.getConfig(minerConfig.getName()).set('core.miner.address', minerAddress);
+            });
+
             minerConfig.set('core.miner.address', minerAddress);
           }
 
diff --git a/packages/dashmate/src/oclif/command/BaseCommand.js b/packages/dashmate/src/oclif/command/BaseCommand.js
index 1cc3aa6d063..5f3aab4e121 100644
--- a/packages/dashmate/src/oclif/command/BaseCommand.js
+++ b/packages/dashmate/src/oclif/command/BaseCommand.js
@@ -70,6 +70,20 @@ export default class BaseCommand extends Command {
       configFile = createConfigFile();
     }
 
+    // Migrating produced a new shape that has to reach disk. Saving it here,
+    // rather than carrying it to the end of the command, is what keeps the
+    // registered config file clean - anything still dirty at exit would be a
+    // snapshot from before the command ran.
+    if (configFile.isChanged()) {
+      const changedConfigs = configFile.getAllConfigs().filter((config) => config.isChanged());
+
+      configFileRepository.write(configFile);
+
+      const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
+
+      changedConfigs.forEach(writeConfigTemplates);
+    }
+
     // Register config collection in the container
     this.container.register({
       configFile: asValue(configFile),
@@ -136,7 +150,12 @@ export default class BaseCommand extends Command {
        */
       const configFileRepository = this.container.resolve('configFileRepository');
 
-      if (this.container.has('configFile') && err === undefined) {
+      // Only a command that held the lock for its whole run may save the config
+      // file it loaded - it read inside the lock, so its state is current. Any
+      // other command changes configuration through update(), and saving its
+      // startup copy here would write a snapshot from before the command ran.
+      if (this.constructor.mutatesConfig
+        && this.container.has('configFile') && err === undefined) {
         /**
          * @var {ConfigFile} configFile
          */
diff --git a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
index bba4f2b73a2..d38f942fbad 100644
--- a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
+++ b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
@@ -23,7 +23,7 @@ describe('Config mutating commands', () => {
   let configFileRepository;
 
   function reread() {
-    return new ConfigFileJsonRepository((data) => data, homeDir).read();
+    return new ConfigFileJsonRepository((data) => data, homeDir, () => null).read();
   }
 
   beforeEach(() => {
@@ -43,7 +43,7 @@ describe('Config mutating commands', () => {
       'utf8',
     );
 
-    configFileRepository = new ConfigFileJsonRepository((data) => data, homeDir);
+    configFileRepository = new ConfigFileJsonRepository((data) => data, homeDir, () => null);
     loadedConfigFile = configFileRepository.read();
   });
 
diff --git a/packages/dashmate/test/unit/commands/config/set.spec.js b/packages/dashmate/test/unit/commands/config/set.spec.js
index 30725e5637b..6f6d66c055e 100644
--- a/packages/dashmate/test/unit/commands/config/set.spec.js
+++ b/packages/dashmate/test/unit/commands/config/set.spec.js
@@ -23,7 +23,7 @@ describe('Config set command', () => {
    * @return {*}
    */
   function persisted(path) {
-    return new ConfigFileJsonRepository((data) => data, homeDir)
+    return new ConfigFileJsonRepository((data) => data, homeDir, () => null)
       .read()
       .getConfig('base')
       .get(path);
@@ -42,7 +42,7 @@ describe('Config set command', () => {
       'utf8',
     );
 
-    configFileRepository = new ConfigFileJsonRepository((data) => data, homeDir);
+    configFileRepository = new ConfigFileJsonRepository((data) => data, homeDir, () => null);
     writeConfigTemplates = () => {};
     command = new ConfigSetCommand();
   });
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index 328a31f6c5b..f0d5f2cf366 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -12,6 +12,7 @@ describe('ConfigFileJsonRepository', () => {
   let homeDir;
   let configFilePath;
   let identityMigration;
+  let createDefaults;
   // Tracked so a failed assertion cannot leave a spawned lock holder behind
   // still owning the lock directory after the test that created it is gone.
   let lockHolder;
@@ -43,6 +44,19 @@ describe('ConfigFileJsonRepository', () => {
     homeDir = HomeDir.createTemp();
     configFilePath = homeDir.joinPath('config.json');
     identityMigration = (data) => data;
+    createDefaults = () => {
+      const configFile = new ConfigFile(
+        [getBaseConfigFactory(homeDir)()],
+        CURRENT_FORMAT_VERSION,
+        'abcdef12',
+        'base',
+        null,
+      );
+
+      configFile.markAsChanged();
+
+      return configFile;
+    };
   });
 
   afterEach(() => {
@@ -62,7 +76,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should return a clean config file when nothing was migrated', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       const configFile = repository.read();
 
@@ -75,7 +89,7 @@ describe('ConfigFileJsonRepository', () => {
 
       const migration = (data) => ({ ...data, configFormatVersion: '9.9.9' });
 
-      const repository = new ConfigFileJsonRepository(migration, homeDir);
+      const repository = new ConfigFileJsonRepository(migration, homeDir, createDefaults);
 
       const configFile = repository.read();
 
@@ -90,7 +104,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should leave the file untouched when a read-only command exits', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
       const { mtimeMs, ino } = fs.statSync(configFilePath);
 
       const configFile = repository.read();
@@ -111,7 +125,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should persist changes and mark the config file and its configs saved', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
       const configFile = repository.read();
 
       configFile.getConfig('base').set('description', 'changed');
@@ -121,7 +135,7 @@ describe('ConfigFileJsonRepository', () => {
       expect(configFile.isChanged()).to.be.false();
       expect(configFile.getAllConfigs().filter((config) => config.isChanged())).to.be.empty();
 
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.equal('changed');
     });
@@ -130,7 +144,7 @@ describe('ConfigFileJsonRepository', () => {
       seedConfigFile();
       fs.chmodSync(configFilePath, 0o600);
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
       const configFile = repository.read();
 
       configFile.getConfig('base').set('description', 'changed');
@@ -152,7 +166,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should allow repeated writes from one long-lived instance', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
       const configFile = repository.read();
 
       configFile.getConfig('base').set('description', 'first');
@@ -162,13 +176,31 @@ describe('ConfigFileJsonRepository', () => {
 
       expect(() => repository.write(configFile)).to.not.throw();
 
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.equal('second');
     });
   });
 
   describe('#update', () => {
+    // On a machine with no config file yet, the change still has to land -
+    // reading first and failing would break `config create` on first run.
+    it('should create the config file when there is none yet', () => {
+      expect(fs.existsSync(configFilePath)).to.be.false();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
+
+      repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'created-on-first-run');
+      });
+
+      expect(fs.existsSync(configFilePath)).to.be.true();
+
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('created-on-first-run');
+    });
+
     // The reported bug, stated as the outcome operators want rather than as a
     // failure they have to recover from: one process loads the config, another
     // changes and saves a different option, and both edits survive. Mutating a
@@ -176,8 +208,8 @@ describe('ConfigFileJsonRepository', () => {
     it('should keep concurrent edits to different options', () => {
       seedConfigFile();
 
-      const slowCommand = new ConfigFileJsonRepository(identityMigration, homeDir);
-      const otherCommand = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const slowCommand = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
+      const otherCommand = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       // Both load the same starting state, as two overlapping commands would
       slowCommand.read();
@@ -191,7 +223,7 @@ describe('ConfigFileJsonRepository', () => {
         configFile.getConfig('base').set('core.rpc.port', 30000);
       });
 
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.equal('set-by-other-command');
       expect(reread.getConfig('base').get('core.rpc.port')).to.equal(30000);
@@ -202,11 +234,11 @@ describe('ConfigFileJsonRepository', () => {
     it('should hand the mutator state written since this instance last read', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       repository.read();
 
-      new ConfigFileJsonRepository(identityMigration, homeDir)
+      new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults)
         .update((configFile) => {
           configFile.getConfig('base').set('description', 'written-by-someone-else');
         });
@@ -222,7 +254,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should return the state it saved', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       const configFile = repository.update((freshConfigFile) => {
         freshConfigFile.getConfig('base').set('description', 'returned');
@@ -235,7 +267,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should not write when the mutator throws', () => {
       const before = seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       expect(() => repository.update(() => {
         throw new Error('mutator failed');
@@ -253,7 +285,7 @@ describe('ConfigFileJsonRepository', () => {
 
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       repository.acquire();
 
@@ -269,7 +301,7 @@ describe('ConfigFileJsonRepository', () => {
         repository.release();
       }
 
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.equal('via-write');
     });
@@ -277,7 +309,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should hold the lock between acquire and release, and free it after', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
       const lockPath = homeDir.joinPath('config.json.lock');
 
       repository.acquire();
@@ -294,7 +326,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should tolerate release without acquire, and repeated release', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
 
       expect(() => repository.release()).to.not.throw();
 
@@ -315,7 +347,7 @@ describe('ConfigFileJsonRepository', () => {
 
       // proper-lockfile floors `stale` at 2s and the refresh that detects loss at
       // 1s, so this is as fast as the path can be made to happen.
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, {
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults, {
         stale: 2000,
       });
 
@@ -333,7 +365,7 @@ describe('ConfigFileJsonRepository', () => {
         repository.release();
       }
 
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.not.equal('must-not-be-saved');
     });
@@ -343,7 +375,7 @@ describe('ConfigFileJsonRepository', () => {
     it('should give up waiting for another holder with an actionable error', () => {
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, {
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults, {
         acquireTimeout: 700,
       });
 
@@ -369,7 +401,7 @@ describe('ConfigFileJsonRepository', () => {
 
       seedConfigFile();
 
-      const repository = new ConfigFileJsonRepository(identityMigration, homeDir);
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
       const lockPath = homeDir.joinPath('config.json.lock');
       const holdMs = 700;
 
@@ -397,7 +429,7 @@ describe('ConfigFileJsonRepository', () => {
 
       expect(Date.now() - startedAt).to.be.at.least(holdMs / 2);
 
-      const reread = new ConfigFileJsonRepository(identityMigration, homeDir).read();
+      const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.equal('written-after-waiting');
 

From c907b93b187035746a9f737d039bedbdf3f3123a Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Thu, 30 Jul 2026 22:39:05 +0700
Subject: [PATCH 10/11] fix(dashmate): narrow to the config paths this change
 can carry

The previous commit extended the locked read-change-save to SSL issuance, the
helper's certificate renewal and local group start. Review found each of those
introduced a new defect: templates rendered before a certificate was actually
usable, a renewal that reverted a provider change made since the helper started,
and a miner address chosen from stale state then written over fresh state.

None of them is needed to fix the reported bug, and they touch certificate
issuance, where being wrong costs an operator a working gateway. They are
reverted to their previous behaviour and left for separate changes with their
own tests.

Migration is now read and saved under one lock rather than read unlocked and
saved after. Splitting them left the same window this change exists to remove: a
change saved in between would have been reverted by the migrated copy. Service
files are re-rendered for whatever the migration changed, which the config file's
own save no longer implies.

Also fixes a test that passed for the wrong reason: `config default` set the
config that was already the default, so it would have passed with the save
deleted. It now points at a different config.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/dashmate/scripts/helper.js           |  6 +--
 .../configFile/ConfigFileJsonRepository.js    | 25 +++++++++
 ...eduleRenewLetsEncryptCertificateFactory.js | 17 ++----
 .../scheduleRenewZeroSslCertificateFactory.js | 17 ++----
 ...obtainLetsEncryptCertificateTaskFactory.js |  7 +--
 .../obtainZeroSSLCertificateTaskFactory.js    |  7 +--
 .../listr/tasks/startGroupNodesTaskFactory.js |  8 ---
 .../dashmate/src/oclif/command/BaseCommand.js | 23 ++++----
 .../commands/config/mutatingCommands.spec.js  | 17 +++++-
 .../ConfigFileJsonRepository.spec.js          | 53 +++++++++++++++++++
 10 files changed, 114 insertions(+), 66 deletions(-)

diff --git a/packages/dashmate/scripts/helper.js b/packages/dashmate/scripts/helper.js
index 800b3941e32..4fa8bdf7d64 100644
--- a/packages/dashmate/scripts/helper.js
+++ b/packages/dashmate/scripts/helper.js
@@ -92,10 +92,10 @@ async function removeOrphanedSslContainers(docker) {
 
   const configFile = await configFileRepository.read();
 
-  // Persist config if it was migrated. Nothing else here ever saves this copy -
-  // it lives for the life of the process, so it goes stale, and the renewal
-  // re-applies its result onto current state instead.
+  // Persist config if it was migrated
   if (configFile.isChanged()) {
+    // Captured before the write, which clears these flags once the new state is
+    // on disk.
     const changedConfigs = configFile.getAllConfigs()
       .filter((config) => config.isChanged());
 
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index 74646518b44..2ccb2b735d9 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -189,6 +189,31 @@ export default class ConfigFileJsonRepository {
     });
   }
 
+  /**
+   * Read the config file, saving the result when reading migrated it.
+   *
+   * Migrating produces a new shape that has to reach disk. Doing both under one
+   * lock is what keeps it from reverting anything saved between the read and the
+   * save - the same split that made a command's startup copy dangerous.
+   *
+   * @param {Object} [options={}] - passed through to read()
+   * @returns {{configFile: ConfigFile, migrated: Config[]}} migrated is the
+   *   configs whose shape changed, so their service files can be re-rendered
+   */
+  readAndMigrate(options = {}) {
+    return this.#locked(() => {
+      const configFile = this.read(options);
+
+      const migrated = configFile.getAllConfigs().filter((config) => config.isChanged());
+
+      if (configFile.isChanged()) {
+        this.#save(configFile);
+      }
+
+      return { configFile, migrated };
+    });
+  }
+
   /**
    * Hold the lock for as long as this process is changing configuration.
    *
diff --git a/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js b/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js
index d47485994e7..f14f1c937a2 100644
--- a/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js
+++ b/packages/dashmate/src/helper/scheduleRenewLetsEncryptCertificateFactory.js
@@ -75,20 +75,9 @@ export default function scheduleRenewLetsEncryptCertificateFactory(
           noRetry: true,
         });
 
-        // This process has held its copy of the config file since it started,
-        // possibly for months, so saving that copy would revert everything
-        // changed on the node since. Re-apply just what the renewal produced
-        // onto the current state instead.
-        const renewedOptions = config.get('platform.gateway.ssl');
-
-        configFileRepository.update((freshConfigFile) => {
-          freshConfigFile.getConfig(config.getName())
-            .set('platform.gateway.ssl', renewedOptions);
-        }, {
-          onSaved: (savedConfigFile) => writeConfigTemplates(
-            savedConfigFile.getConfig(config.getName()),
-          ),
-        });
+        // Write config files
+        configFileRepository.write(configFile);
+        writeConfigTemplates(config);
 
         // Restart Gateway to catch up new SSL certificates
         await dockerCompose.execCommand(config, 'gateway', 'kill -SIGHUP 1');
diff --git a/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js b/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js
index 216b361b4ce..0526bcc1f97 100644
--- a/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js
+++ b/packages/dashmate/src/helper/scheduleRenewZeroSslCertificateFactory.js
@@ -79,20 +79,9 @@ export default function scheduleRenewZeroSslCertificateFactory(
           noRetry: true,
         });
 
-        // This process has held its copy of the config file since it started,
-        // possibly for months, so saving that copy would revert everything
-        // changed on the node since. Re-apply just what the renewal produced
-        // onto the current state instead.
-        const renewedOptions = config.get('platform.gateway.ssl');
-
-        configFileRepository.update((freshConfigFile) => {
-          freshConfigFile.getConfig(config.getName())
-            .set('platform.gateway.ssl', renewedOptions);
-        }, {
-          onSaved: (savedConfigFile) => writeConfigTemplates(
-            savedConfigFile.getConfig(config.getName()),
-          ),
-        });
+        // Write config files
+        configFileRepository.write(configFile);
+        writeConfigTemplates(config);
 
         // TODO: We can use https://www.envoyproxy.io/docs/envoy/v1.30.1/start/quick-start/configuration-dynamic-filesystem.html#start-quick-start-dynamic-fs-dynamic-lds
         //  to dynamically update envoy configuration without restarting it
diff --git a/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js b/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js
index 6f6c8180707..0e33318edd7 100644
--- a/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/ssl/letsencrypt/obtainLetsEncryptCertificateTaskFactory.js
@@ -16,7 +16,6 @@ const LEGO_IMAGE = 'goacme/lego:v4.31.0';
  * @param {validateLetsEncryptCertificate} validateLetsEncryptCertificate
  * @param {saveCertificateTask} saveCertificateTask
  * @param {ConfigFileJsonRepository} configFileRepository
- * @param {writeConfigTemplates} writeConfigTemplates
  * @param {ConfigFile} configFile
  * @return {obtainLetsEncryptCertificateTask}
  */
@@ -28,7 +27,6 @@ export default function obtainLetsEncryptCertificateTaskFactory(
   validateLetsEncryptCertificate,
   saveCertificateTask,
   configFileRepository,
-  writeConfigTemplates,
   configFile,
 ) {
   /**
@@ -254,11 +252,8 @@ export default function obtainLetsEncryptCertificateTaskFactory(
           config.set('platform.gateway.ssl.enabled', true);
           config.set('platform.gateway.ssl.provider', 'letsencrypt');
 
-          // Save config file. Templates are rendered here too: this command
-          // holds the config lock for its run, and saving marks the configs
-          // clean, so nothing later would know they need re-rendering.
+          // Save config file
           configFileRepository.write(configFile);
-          writeConfigTemplates(config);
 
           // Save to gateway SSL directory
           return saveCertificateTask(config);
diff --git a/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js b/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js
index 2ef8965b8c2..a08e7ab7d02 100644
--- a/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js
@@ -19,7 +19,6 @@ import { ERRORS } from '../../../../ssl/zerossl/validateZeroSslCertificateFactor
  * @param {HomeDir} homeDir
  * @param {validateZeroSslCertificate} validateZeroSslCertificate
  * @param {ConfigFileJsonRepository} configFileRepository
- * @param {writeConfigTemplates} writeConfigTemplates
  * @param {ConfigFile} configFile
  * @return {obtainZeroSSLCertificateTask}
  */
@@ -36,7 +35,6 @@ export default function obtainZeroSSLCertificateTaskFactory(
   homeDir,
   validateZeroSslCertificate,
   configFileRepository,
-  writeConfigTemplates,
   configFile,
 ) {
   /**
@@ -148,11 +146,8 @@ export default function obtainZeroSSLCertificateTaskFactory(
           config.set('platform.gateway.ssl.provider', 'zerossl');
           config.set('platform.gateway.ssl.providerConfigs.zerossl.id', ctx.certificate.id);
 
-          // Save config file. Templates are rendered here too: this command
-          // holds the config lock for its run, and saving marks the configs
-          // clean, so nothing later would know they need re-rendering.
+          // Save config file
           configFileRepository.write(configFile);
-          writeConfigTemplates(config);
         },
       },
       {
diff --git a/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js b/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
index 60fb8a864b5..53b6762ee1e 100644
--- a/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
@@ -28,7 +28,6 @@ export default function startGroupNodesTaskFactory(
   waitForNodeToBeReadyTask,
   buildServicesTask,
   getConnectionHost,
-  configFileRepository,
 ) {
   /**
    * @typedef {startGroupNodesTask}
@@ -93,13 +92,6 @@ export default function startGroupNodesTaskFactory(
             const privateKey = new PrivateKey();
             minerAddress = privateKey.toAddress('regtest').toString();
 
-            // Saved as its own locked step rather than carried to the end of the
-            // command: starting a group runs for many minutes, and the address is
-            // needed by the miner right now.
-            configFileRepository.update((configFile) => {
-              configFile.getConfig(minerConfig.getName()).set('core.miner.address', minerAddress);
-            });
-
             minerConfig.set('core.miner.address', minerAddress);
           }
 
diff --git a/packages/dashmate/src/oclif/command/BaseCommand.js b/packages/dashmate/src/oclif/command/BaseCommand.js
index 5f3aab4e121..d2a3a9caf30 100644
--- a/packages/dashmate/src/oclif/command/BaseCommand.js
+++ b/packages/dashmate/src/oclif/command/BaseCommand.js
@@ -48,12 +48,15 @@ export default class BaseCommand extends Command {
     }
 
     let configFile;
+    let migratedConfigs = [];
     try {
-      // Load config collection from config file
+      // Load config collection from config file, saving it again if loading
+      // migrated it - under one lock, so the migrated shape cannot revert a
+      // change saved in between.
       // Skip per-config validation when --force flag is passed (e.g., for reset command)
-      configFile = configFileRepository.read({
+      ({ configFile, migrated: migratedConfigs } = configFileRepository.readAndMigrate({
         skipValidation: Boolean(this.parsedFlags.force),
-      });
+      }));
     } catch (e) {
       // Create default config collection if config file is not present
       // on the first start for example
@@ -70,18 +73,12 @@ export default class BaseCommand extends Command {
       configFile = createConfigFile();
     }
 
-    // Migrating produced a new shape that has to reach disk. Saving it here,
-    // rather than carrying it to the end of the command, is what keeps the
-    // registered config file clean - anything still dirty at exit would be a
-    // snapshot from before the command ran.
-    if (configFile.isChanged()) {
-      const changedConfigs = configFile.getAllConfigs().filter((config) => config.isChanged());
-
-      configFileRepository.write(configFile);
-
+    // A migration changes what the services should be running with, so their
+    // files are re-rendered. The config file itself was already saved with it.
+    if (migratedConfigs.length > 0) {
       const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
 
-      changedConfigs.forEach(writeConfigTemplates);
+      migratedConfigs.forEach(writeConfigTemplates);
     }
 
     // Register config collection in the container
diff --git a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
index d38f942fbad..85945b974f4 100644
--- a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
+++ b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
@@ -68,15 +68,28 @@ describe('Config mutating commands', () => {
   });
 
   describe('config default', () => {
+    // Pointed at a config that is NOT already the default, so deleting the save
+    // would fail this rather than passing on the starting state.
     it('should save the new default without touching the config file loaded at startup', async () => {
-      await new ConfigDefaultCommand().runWithDependencies(
-        { config: 'base' },
+      await new ConfigCreateCommand().runWithDependencies(
+        { config: 'node1', from: 'base' },
         flags,
         loadedConfigFile,
         configFileRepository,
+        noTemplates,
       );
 
       expect(reread().getDefaultConfigName()).to.equal('base');
+
+      await new ConfigDefaultCommand().runWithDependencies(
+        { config: 'node1' },
+        flags,
+        loadedConfigFile,
+        configFileRepository,
+      );
+
+      expect(reread().getDefaultConfigName()).to.equal('node1');
+      expect(loadedConfigFile.getDefaultConfigName()).to.equal('base');
       expect(loadedConfigFile.isChanged()).to.be.false();
     });
   });
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index f0d5f2cf366..3505a378d90 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -183,6 +183,59 @@ describe('ConfigFileJsonRepository', () => {
   });
 
   describe('#update', () => {
+    // The generic save-on-exit used to persist migration, and a migrated startup
+    // copy saved afterwards would revert whatever the command itself changed.
+    // Migration is now saved where it happens, so the two cannot fight.
+    it('should not let a migrated startup copy overwrite a later change', () => {
+      seedConfigFile();
+
+      const migration = (data) => ({ ...data, configFormatVersion: '9.9.9' });
+      const repository = new ConfigFileJsonRepository(migration, homeDir, createDefaults);
+
+      // What BaseCommand.init() does: migration reached disk, nothing left pending
+      const migrated = repository.read();
+
+      expect(migrated.isChanged()).to.be.true();
+
+      repository.write(migrated);
+
+      expect(migrated.isChanged()).to.be.false();
+      expect(migrated.getAllConfigs().filter((config) => config.isChanged())).to.be.empty();
+
+      // and the command's own change lands on top of it
+      repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'changed-by-command');
+      });
+
+      const reread = new ConfigFileJsonRepository(migration, homeDir, createDefaults).read();
+
+      expect(reread.getConfig('base').get('description')).to.equal('changed-by-command');
+    });
+
+    // Effects registered by the caller run before the lock is released, so a
+    // concurrent command cannot slip between the save and them.
+    it('should run onSaved after saving and while still holding the lock', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
+
+      let sawOnDisk;
+      let heldLock;
+
+      repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'saved-then-observed');
+      }, {
+        onSaved: () => {
+          sawOnDisk = JSON.parse(fs.readFileSync(configFilePath, 'utf8'))
+            .configs.base.description;
+          heldLock = fs.existsSync(homeDir.joinPath('config.json.lock'));
+        },
+      });
+
+      expect(sawOnDisk).to.equal('saved-then-observed');
+      expect(heldLock, 'lock should still be held while onSaved runs').to.be.true();
+    });
+
     // On a machine with no config file yet, the change still has to land -
     // reading first and failing would break `config create` on first run.
     it('should create the config file when there is none yet', () => {

From 949428bab69316d4883a41416b77d0b85672fa71 Mon Sep 17 00:00:00 2001
From: Ivan Shumkov <ivanshumkov@gmail.com>
Date: Fri, 31 Jul 2026 09:58:24 +0700
Subject: [PATCH 11/11] fix(dashmate): keep reads lock-free and every config
 mutation under the lock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Making migration atomic had made *every* command take the lock to load, so
`status`, `config get` and `core cli` blocked behind a running `setup` and then
failed — the opposite of the contract, since reading is exactly what has to stay
available while a node is being reconfigured. A load only takes the lock when it
actually has something to migrate.

Gating the save on commands that hold the lock also revealed commands doing it
that were never marked: `config render`, `core reindex` and `group core reindex`
all change configuration, so their changes were being dropped. Found by sweeping
for the pattern rather than listing commands by hand.

The generated local miner address is now chosen from freshly read state inside
the lock rather than from the copy loaded at startup, so an address written while
a group start is running is no longer replaced by one generated from stale state.

Saving no longer marks configs as having current service files - that is what
rendering means, and conflating them left `ssl obtain` believing its new
certificate had already reached the gateway config.

Verified: readers load in 10ms while another command holds the lock, writers
still wait and then report; 206 unit tests; local E2E 5/5 with setup generating
and persisting real keys through the changed path.

Deliberately unchanged: `--force` can persist a migration before the command
succeeds, and rendering after the save is committed means a rendering failure
needs `dashmate config render` to recover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../dashmate/src/commands/config/render.js    |   4 +
 .../dashmate/src/commands/core/reindex.js     |   4 +
 .../src/commands/group/core/reindex.js        |   4 +
 .../configFile/ConfigFileJsonRepository.js    |  48 ++++++--
 .../listr/tasks/startGroupNodesTaskFactory.js |  24 +++-
 .../dashmate/src/oclif/command/BaseCommand.js |  26 ++--
 .../templates/writeConfigTemplatesFactory.js  |   2 +
 .../commands/config/mutatingCommands.spec.js  |  34 ++++--
 .../configurationLockCoverage.spec.js         |  15 +++
 .../ConfigFileJsonRepository.spec.js          | 103 ++++++++++++----
 ...btainZeroSSLCertificateTaskFactory.spec.js |  78 ++++++++++++
 .../tasks/startGroupNodesTaskFactory.spec.js  | 115 ++++++++++++++++++
 .../writeConfigTemplatesFactory.spec.js       |  23 ++++
 13 files changed, 418 insertions(+), 62 deletions(-)
 create mode 100644 packages/dashmate/test/unit/commands/configurationLockCoverage.spec.js
 create mode 100644 packages/dashmate/test/unit/tasks/startGroupNodesTaskFactory.spec.js
 create mode 100644 packages/dashmate/test/unit/templates/writeConfigTemplatesFactory.spec.js

diff --git a/packages/dashmate/src/commands/config/render.js b/packages/dashmate/src/commands/config/render.js
index 0e9c58ae0bb..3a4536366e9 100644
--- a/packages/dashmate/src/commands/config/render.js
+++ b/packages/dashmate/src/commands/config/render.js
@@ -3,6 +3,10 @@ import { OUTPUT_FORMATS } from '../../constants.js';
 import ConfigBaseCommand from '../../oclif/command/ConfigBaseCommand.js';
 
 export default class ConfigRenderCommand extends ConfigBaseCommand {
+  // Rendering replaces the service configuration files, so serialize it with
+  // commands that save and render config.json.
+  static mutatesConfig = true;
+
   static description = `Render config's service configs
 
 Force dashmate to render all config's service configs
diff --git a/packages/dashmate/src/commands/core/reindex.js b/packages/dashmate/src/commands/core/reindex.js
index 4f71988194d..252100c9c63 100644
--- a/packages/dashmate/src/commands/core/reindex.js
+++ b/packages/dashmate/src/commands/core/reindex.js
@@ -5,6 +5,10 @@ import ConfigBaseCommand from '../../oclif/command/ConfigBaseCommand.js';
 import MuteOneLineError from '../../oclif/errors/MuteOneLineError.js';
 
 export default class ReindexCommand extends ConfigBaseCommand {
+  // Reindex temporarily replaces the Core service configuration, so other
+  // configuration renderers must wait until it restores the ordinary files.
+  static mutatesConfig = true;
+
   static description = 'Reindex Core data';
 
   static flags = {
diff --git a/packages/dashmate/src/commands/group/core/reindex.js b/packages/dashmate/src/commands/group/core/reindex.js
index 1664f88668f..dfc26af475a 100644
--- a/packages/dashmate/src/commands/group/core/reindex.js
+++ b/packages/dashmate/src/commands/group/core/reindex.js
@@ -5,6 +5,10 @@ import GroupBaseCommand from '../../../oclif/command/GroupBaseCommand.js';
 import MuteOneLineError from '../../../oclif/errors/MuteOneLineError.js';
 
 export default class GroupReindexCommand extends GroupBaseCommand {
+  // Reindex temporarily replaces each Core service configuration, so other
+  // configuration renderers must wait until it restores the ordinary files.
+  static mutatesConfig = true;
+
   static description = 'Reindex group Core data';
 
   static flags = {
diff --git a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
index 2ccb2b735d9..907de04c74f 100644
--- a/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
+++ b/packages/dashmate/src/config/configFile/ConfigFileJsonRepository.js
@@ -196,21 +196,48 @@ export default class ConfigFileJsonRepository {
    * lock is what keeps it from reverting anything saved between the read and the
    * save - the same split that made a command's startup copy dangerous.
    *
+   * Clean reads do not acquire the lock. When the first read discovers a
+   * migration, the file is read again and migrated under the lock before it is
+   * saved. This keeps ordinary read-only commands available during long-running
+   * configuration changes without letting a migrated snapshot overwrite a newer
+   * write.
+   *
    * @param {Object} [options={}] - passed through to read()
+   * @param {function(Config[]): void} [onMigrated] - runs after the migrated
+   *   config file is saved and before the lock is released
    * @returns {{configFile: ConfigFile, migrated: Config[]}} migrated is the
    *   configs whose shape changed, so their service files can be re-rendered
    */
-  readAndMigrate(options = {}) {
-    return this.#locked(() => {
+  readAndMigrate(options = {}, onMigrated = undefined) {
+    const readResult = () => {
       const configFile = this.read(options);
-
       const migrated = configFile.getAllConfigs().filter((config) => config.isChanged());
 
+      return { configFile, migrated };
+    };
+
+    const initialResult = readResult();
+
+    if (!initialResult.configFile.isChanged()) {
+      return initialResult;
+    }
+
+    return this.#locked(() => {
+      // Another process may have migrated or changed the file while this
+      // process waited, so never save the result of the unlocked probe.
+      const result = readResult();
+
+      const { configFile, migrated } = result;
+
       if (configFile.isChanged()) {
         this.#save(configFile);
+
+        if (onMigrated) {
+          onMigrated(migrated);
+        }
       }
 
-      return { configFile, migrated };
+      return result;
     });
   }
 
@@ -266,6 +293,9 @@ export default class ConfigFileJsonRepository {
       return fn();
     }
 
+    // A compromise belongs to the lock that was lost. A later independent
+    // acquisition restores exclusivity and must not inherit that failure.
+    this.#compromised = false;
     const release = this.#acquireLock();
 
     try {
@@ -291,7 +321,12 @@ export default class ConfigFileJsonRepository {
   }
 
   /**
-   * Serialize and replace the file, then mark the state clean.
+   * Serialize and replace the file, then mark the config collection saved.
+   *
+   * Individual configs remain changed until their service templates are
+   * rendered. A mid-command save may persist JSON before those files should take
+   * effect, so clearing their flags here would make successful command
+   * finalization skip the render.
    *
    * Caller must hold the lock.
    *
@@ -309,9 +344,8 @@ export default class ConfigFileJsonRepository {
     writeFileAtomic.sync(this.configFilePath, configFileJSON, 'utf8');
 
     // Only now is the state actually on disk. Clearing these beforehand would
-    // leave the configs claiming to be saved after a failed write.
+    // leave the config file claiming to be saved after a failed write.
     configFile.markAsSaved();
-    configFile.getAllConfigs().forEach((config) => config.markAsSaved());
   }
 
   /**
diff --git a/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js b/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
index 53b6762ee1e..bdd27a76b67 100644
--- a/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
+++ b/packages/dashmate/src/listr/tasks/startGroupNodesTaskFactory.js
@@ -16,6 +16,8 @@ const { PrivateKey } = DashCoreLib;
  * @param {waitForNodeToBeReadyTask} waitForNodeToBeReadyTask
  * @param {buildServicesTask} buildServicesTask
  * @param {getConnectionHost} getConnectionHost
+ * @param {ConfigFileJsonRepository} configFileRepository
+ * @param {writeConfigTemplates} writeConfigTemplates
  * @return {startGroupNodesTask}
  */
 export default function startGroupNodesTaskFactory(
@@ -28,6 +30,8 @@ export default function startGroupNodesTaskFactory(
   waitForNodeToBeReadyTask,
   buildServicesTask,
   getConnectionHost,
+  configFileRepository,
+  writeConfigTemplates,
 ) {
   /**
    * @typedef {startGroupNodesTask}
@@ -89,9 +93,25 @@ export default function startGroupNodesTaskFactory(
           let minerAddress = minerConfig.get('core.miner.address');
 
           if (minerAddress === null) {
-            const privateKey = new PrivateKey();
-            minerAddress = privateKey.toAddress('regtest').toString();
+            configFileRepository.update((configFile) => {
+              const freshMinerConfig = configFile.getConfig(minerConfig.getName());
 
+              minerAddress = freshMinerConfig.get('core.miner.address');
+
+              if (minerAddress === null) {
+                const privateKey = new PrivateKey();
+                minerAddress = privateKey.toAddress('regtest').toString();
+
+                freshMinerConfig.set('core.miner.address', minerAddress);
+              }
+            }, {
+              onSaved: (configFile) => writeConfigTemplates(
+                configFile.getConfig(minerConfig.getName()),
+              ),
+            });
+
+            // The running task keeps the object loaded at command startup, so
+            // copy the value selected from fresh state back into it.
             minerConfig.set('core.miner.address', minerAddress);
           }
 
diff --git a/packages/dashmate/src/oclif/command/BaseCommand.js b/packages/dashmate/src/oclif/command/BaseCommand.js
index d2a3a9caf30..bb6b710eee2 100644
--- a/packages/dashmate/src/oclif/command/BaseCommand.js
+++ b/packages/dashmate/src/oclif/command/BaseCommand.js
@@ -48,15 +48,21 @@ export default class BaseCommand extends Command {
     }
 
     let configFile;
-    let migratedConfigs = [];
     try {
       // Load config collection from config file, saving it again if loading
       // migrated it - under one lock, so the migrated shape cannot revert a
       // change saved in between.
       // Skip per-config validation when --force flag is passed (e.g., for reset command)
-      ({ configFile, migrated: migratedConfigs } = configFileRepository.readAndMigrate({
-        skipValidation: Boolean(this.parsedFlags.force),
-      }));
+      ({ configFile } = configFileRepository.readAndMigrate(
+        {
+          skipValidation: Boolean(this.parsedFlags.force),
+        },
+        (migratedConfigs) => {
+          const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
+
+          migratedConfigs.forEach(writeConfigTemplates);
+        },
+      ));
     } catch (e) {
       // Create default config collection if config file is not present
       // on the first start for example
@@ -73,14 +79,6 @@ export default class BaseCommand extends Command {
       configFile = createConfigFile();
     }
 
-    // A migration changes what the services should be running with, so their
-    // files are re-rendered. The config file itself was already saved with it.
-    if (migratedConfigs.length > 0) {
-      const writeConfigTemplates = this.container.resolve('writeConfigTemplates');
-
-      migratedConfigs.forEach(writeConfigTemplates);
-    }
-
     // Register config collection in the container
     this.container.register({
       configFile: asValue(configFile),
@@ -159,8 +157,8 @@ export default class BaseCommand extends Command {
         const configFile = this.container.resolve('configFile');
 
         if (configFile.isChanged()) {
-          // Captured before the write, which clears these flags once the new
-          // state is on disk.
+          // Captured before rendering, which clears each flag only after its
+          // service files have been written successfully.
           const changedConfigs = configFile.getAllConfigs()
             .filter((config) => config.isChanged());
 
diff --git a/packages/dashmate/src/templates/writeConfigTemplatesFactory.js b/packages/dashmate/src/templates/writeConfigTemplatesFactory.js
index c1b33df6cce..1684e61f2fb 100644
--- a/packages/dashmate/src/templates/writeConfigTemplatesFactory.js
+++ b/packages/dashmate/src/templates/writeConfigTemplatesFactory.js
@@ -9,6 +9,8 @@ export default function writeConfigTemplatesFactory(renderServiceTemplates, writ
   function writeConfigTemplates(config) {
     const serviceConfigs = renderServiceTemplates(config);
     writeServiceConfigs(config.getName(), serviceConfigs);
+
+    config.markAsSaved();
   }
 
   return writeConfigTemplates;
diff --git a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
index 85945b974f4..6fcb751294e 100644
--- a/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
+++ b/packages/dashmate/test/unit/commands/config/mutatingCommands.spec.js
@@ -121,19 +121,29 @@ describe('Config mutating commands', () => {
       expect(fs.existsSync(homeDir.joinPath('node1'))).to.be.false();
     });
 
-    // The service files are what a node actually runs from. Deleting them before
-    // the removal is saved would leave a config listed in config.json with
-    // nothing on disk behind it.
     it('should leave the service directory alone when the removal cannot be saved', async () => {
-      await new ConfigRemoveCommand().runWithDependencies(
-        { config: 'does-not-exist' },
-        flags,
-        loadedConfigFile,
-        { has: () => false },
-        homeDir,
-        configFileRepository,
-      ).catch(() => {});
-
+      const failingRepository = {
+        update: () => {
+          throw new Error('write failed');
+        },
+      };
+      let thrownError;
+
+      try {
+        await new ConfigRemoveCommand().runWithDependencies(
+          { config: 'node1' },
+          flags,
+          loadedConfigFile,
+          { has: () => false },
+          homeDir,
+          failingRepository,
+        );
+      } catch (e) {
+        thrownError = e;
+      }
+
+      expect(thrownError).to.be.an('error');
+      expect(thrownError.message).to.equal('write failed');
       expect(fs.existsSync(homeDir.joinPath('node1'))).to.be.true();
       expect(reread().isConfigExists('node1')).to.be.true();
     });
diff --git a/packages/dashmate/test/unit/commands/configurationLockCoverage.spec.js b/packages/dashmate/test/unit/commands/configurationLockCoverage.spec.js
new file mode 100644
index 00000000000..dfa807c2506
--- /dev/null
+++ b/packages/dashmate/test/unit/commands/configurationLockCoverage.spec.js
@@ -0,0 +1,15 @@
+import ConfigRenderCommand from '../../../src/commands/config/render.js';
+import ReindexCommand from '../../../src/commands/core/reindex.js';
+import GroupReindexCommand from '../../../src/commands/group/core/reindex.js';
+
+describe('Commands that write rendered configuration', () => {
+  [
+    ['config render', ConfigRenderCommand],
+    ['core reindex', ReindexCommand],
+    ['group core reindex', GroupReindexCommand],
+  ].forEach(([name, Command]) => {
+    it(`should hold the configuration lock for ${name}`, () => {
+      expect(Command.mutatesConfig).to.be.true();
+    });
+  });
+});
diff --git a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
index 3505a378d90..b29ce4f1419 100644
--- a/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
+++ b/packages/dashmate/test/unit/config/configFile/ConfigFileJsonRepository.spec.js
@@ -97,11 +97,7 @@ describe('ConfigFileJsonRepository', () => {
       expect(configFile.getAllConfigs().every((config) => config.isChanged())).to.be.true();
     });
 
-    // The symptom operators reported. Asserting on file CONTENT would pass
-    // against the buggy code, because re-serializing an unchanged config is
-    // byte-identical - the defect is that the write happens at all, carrying a
-    // stale snapshot.
-    it('should leave the file untouched when a read-only command exits', () => {
+    it('should not require a write after an unchanged read', () => {
       seedConfigFile();
 
       const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
@@ -109,7 +105,6 @@ describe('ConfigFileJsonRepository', () => {
 
       const configFile = repository.read();
 
-      // What BaseCommand.finally() does
       if (configFile.isChanged()) {
         repository.write(configFile);
       }
@@ -122,7 +117,7 @@ describe('ConfigFileJsonRepository', () => {
   });
 
   describe('#write', () => {
-    it('should persist changes and mark the config file and its configs saved', () => {
+    it('should persist changes while keeping configs dirty until templates are rendered', () => {
       seedConfigFile();
 
       const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
@@ -132,8 +127,8 @@ describe('ConfigFileJsonRepository', () => {
 
       repository.write(configFile);
 
-      expect(configFile.isChanged()).to.be.false();
-      expect(configFile.getAllConfigs().filter((config) => config.isChanged())).to.be.empty();
+      expect(configFile.changed).to.be.false();
+      expect(configFile.getConfig('base').isChanged()).to.be.true();
 
       const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
@@ -183,33 +178,61 @@ describe('ConfigFileJsonRepository', () => {
   });
 
   describe('#update', () => {
-    // The generic save-on-exit used to persist migration, and a migrated startup
-    // copy saved afterwards would revert whatever the command itself changed.
-    // Migration is now saved where it happens, so the two cannot fight.
-    it('should not let a migrated startup copy overwrite a later change', () => {
+    it('should save and render a migration while holding the lock', () => {
       seedConfigFile();
 
       const migration = (data) => ({ ...data, configFormatVersion: '9.9.9' });
       const repository = new ConfigFileJsonRepository(migration, homeDir, createDefaults);
+      let renderedWhileLocked = false;
 
-      // What BaseCommand.init() does: migration reached disk, nothing left pending
-      const migrated = repository.read();
-
-      expect(migrated.isChanged()).to.be.true();
+      const { configFile, migrated } = repository.readAndMigrate({}, () => {
+        renderedWhileLocked = fs.existsSync(homeDir.joinPath('config.json.lock'));
+        expect(JSON.parse(fs.readFileSync(configFilePath, 'utf8')).configFormatVersion)
+          .to.equal('9.9.9');
+      });
 
-      repository.write(migrated);
+      expect(configFile.getConfigFormatVersion()).to.equal('9.9.9');
+      expect(migrated).to.have.length(1);
+      expect(renderedWhileLocked).to.be.true();
+      expect(JSON.parse(fs.readFileSync(configFilePath, 'utf8')).configFormatVersion)
+        .to.equal('9.9.9');
+    });
 
-      expect(migrated.isChanged()).to.be.false();
-      expect(migrated.getAllConfigs().filter((config) => config.isChanged())).to.be.empty();
+    it('should not wait for a lock when reading does not migrate', () => {
+      seedConfigFile();
 
-      // and the command's own change lands on top of it
-      repository.update((configFile) => {
-        configFile.getConfig('base').set('description', 'changed-by-command');
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults, {
+        acquireTimeout: 50,
       });
+      const lockPath = homeDir.joinPath('config.json.lock');
+
+      fs.mkdirSync(lockPath);
+
+      try {
+        expect(() => repository.readAndMigrate()).to.not.throw();
+      } finally {
+        fs.rmdirSync(lockPath);
+      }
+    });
+
+    it('should reuse a command-held lock when reading and saving a migration', () => {
+      seedConfigFile();
+
+      const migration = (data) => ({ ...data, configFormatVersion: '9.9.9' });
+      const repository = new ConfigFileJsonRepository(migration, homeDir, createDefaults);
+      let renderedWhileLocked = false;
+
+      repository.acquire();
 
-      const reread = new ConfigFileJsonRepository(migration, homeDir, createDefaults).read();
+      try {
+        repository.readAndMigrate({}, () => {
+          renderedWhileLocked = fs.existsSync(homeDir.joinPath('config.json.lock'));
+        });
+      } finally {
+        repository.release();
+      }
 
-      expect(reread.getConfig('base').get('description')).to.equal('changed-by-command');
+      expect(renderedWhileLocked).to.be.true();
     });
 
     // Effects registered by the caller run before the lock is released, so a
@@ -236,6 +259,24 @@ describe('ConfigFileJsonRepository', () => {
       expect(heldLock, 'lock should still be held while onSaved runs').to.be.true();
     });
 
+    it('should release the lock but keep the saved JSON when onSaved throws', () => {
+      seedConfigFile();
+
+      const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
+
+      expect(() => repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'committed-before-hook');
+      }, {
+        onSaved: () => {
+          throw new Error('template write failed');
+        },
+      })).to.throw('template write failed');
+
+      expect(fs.existsSync(homeDir.joinPath('config.json.lock'))).to.be.false();
+      expect(repository.read().getConfig('base').get('description'))
+        .to.equal('committed-before-hook');
+    });
+
     // On a machine with no config file yet, the change still has to land -
     // reading first and failing would break `config create` on first run.
     it('should create the config file when there is none yet', () => {
@@ -304,7 +345,7 @@ describe('ConfigFileJsonRepository', () => {
       expect(seen).to.equal('written-by-someone-else');
     });
 
-    it('should return the state it saved', () => {
+    it('should return the state it saved with template work still marked pending', () => {
       seedConfigFile();
 
       const repository = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults);
@@ -314,7 +355,8 @@ describe('ConfigFileJsonRepository', () => {
       });
 
       expect(configFile.getConfig('base').get('description')).to.equal('returned');
-      expect(configFile.isChanged()).to.be.false();
+      expect(configFile.changed).to.be.false();
+      expect(configFile.getConfig('base').isChanged()).to.be.true();
     });
 
     it('should not write when the mutator throws', () => {
@@ -421,6 +463,13 @@ describe('ConfigFileJsonRepository', () => {
       const reread = new ConfigFileJsonRepository(identityMigration, homeDir, createDefaults).read();
 
       expect(reread.getConfig('base').get('description')).to.not.equal('must-not-be-saved');
+
+      repository.update((configFile) => {
+        configFile.getConfig('base').set('description', 'saved-after-new-lock');
+      });
+
+      expect(repository.read().getConfig('base').get('description'))
+        .to.equal('saved-after-new-lock');
     });
 
     // A waiter should be told what is happening in dashmate's terms, and only
diff --git a/packages/dashmate/test/unit/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.spec.js b/packages/dashmate/test/unit/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.spec.js
index 12bbb460e05..ec5cf3ac372 100644
--- a/packages/dashmate/test/unit/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.spec.js
+++ b/packages/dashmate/test/unit/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.spec.js
@@ -1,4 +1,10 @@
+import fs from 'fs';
 import obtainZeroSSLCertificateTaskFactory from '../../../../src/listr/tasks/ssl/zerossl/obtainZeroSSLCertificateTaskFactory.js';
+import HomeDir from '../../../../src/config/HomeDir.js';
+import ConfigFile from '../../../../src/config/configFile/ConfigFile.js';
+import ConfigFileJsonRepository from '../../../../src/config/configFile/ConfigFileJsonRepository.js';
+import getBaseConfigFactory from '../../../../configs/defaults/getBaseConfigFactory.js';
+import { ERRORS } from '../../../../src/ssl/zerossl/validateZeroSslCertificateFactory.js';
 
 describe('obtainZeroSSLCertificateTaskFactory', () => {
   let config;
@@ -61,4 +67,76 @@ describe('obtainZeroSSLCertificateTaskFactory', () => {
     expect(verificationServer.stop).to.have.been.called();
     expect(verificationServer.destroy).to.have.been.called();
   });
+
+  it('should leave SSL settings dirty for command finalization after the mid-command save', async function it() {
+    const homeDir = HomeDir.createTemp();
+
+    try {
+      const realConfig = getBaseConfigFactory(homeDir)();
+      const configFile = new ConfigFile(
+        [realConfig],
+        '4.1.0',
+        'abcdef12',
+        realConfig.getName(),
+        null,
+      );
+      const configFilePath = homeDir.joinPath('config.json');
+
+      fs.writeFileSync(
+        configFilePath,
+        `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`,
+        'utf8',
+      );
+
+      const repository = new ConfigFileJsonRepository(
+        (data) => data,
+        homeDir,
+        () => null,
+      );
+      const sslConfigDir = homeDir.joinPath('ssl');
+      const validate = this.sinon.stub().resolves({
+        error: ERRORS.CERTIFICATE_ID_IS_NOT_SET,
+        data: {
+          apiKey: 'api-key',
+          bundleFilePath: homeDir.joinPath('bundle.crt'),
+          certificate: null,
+          csr: 'certificate-request',
+          csrFilePath: homeDir.joinPath('certificate.csr'),
+          externalIp: '127.0.0.1',
+          isBundleFilePresent: true,
+          isCsrFilePresent: true,
+          isPrivateKeyFilePresent: true,
+          privateKeyFilePath: homeDir.joinPath('private.key'),
+          sslConfigDir,
+        },
+      });
+      const createCertificate = this.sinon.stub().resolves({
+        id: 'certificate-id-000000000000000000',
+        status: 'issued',
+      });
+      const task = obtainZeroSSLCertificateTaskFactory(
+        this.sinon.stub(),
+        this.sinon.stub(),
+        createCertificate,
+        this.sinon.stub(),
+        this.sinon.stub(),
+        this.sinon.stub(),
+        this.sinon.stub(),
+        this.sinon.stub(),
+        verificationServer,
+        homeDir,
+        validate,
+        repository,
+        configFile,
+      )(realConfig);
+
+      await task.run({ expirationDays: 30 });
+
+      expect(realConfig.isChanged()).to.be.true();
+      expect(repository.read().getConfig(realConfig.getName())
+        .get('platform.gateway.ssl.provider')).to.equal('zerossl');
+    } finally {
+      homeDir.remove();
+    }
+  });
 });
diff --git a/packages/dashmate/test/unit/tasks/startGroupNodesTaskFactory.spec.js b/packages/dashmate/test/unit/tasks/startGroupNodesTaskFactory.spec.js
new file mode 100644
index 00000000000..2ef88221068
--- /dev/null
+++ b/packages/dashmate/test/unit/tasks/startGroupNodesTaskFactory.spec.js
@@ -0,0 +1,115 @@
+import fs from 'fs';
+import HomeDir from '../../../src/config/HomeDir.js';
+import ConfigFile from '../../../src/config/configFile/ConfigFile.js';
+import ConfigFileJsonRepository from '../../../src/config/configFile/ConfigFileJsonRepository.js';
+import getBaseConfigFactory from '../../../configs/defaults/getBaseConfigFactory.js';
+import startGroupNodesTaskFactory from '../../../src/listr/tasks/startGroupNodesTaskFactory.js';
+import { NETWORK_LOCAL } from '../../../src/constants.js';
+
+describe('startGroupNodesTaskFactory', () => {
+  let homeDir;
+  let configFileRepository;
+  let dockerCompose;
+  let startGroupNodesTask;
+  let writeConfigTemplates;
+  let renderedConfig;
+  let renderedWhileLocked;
+
+  function createMinerConfig(address) {
+    const config = getBaseConfigFactory(homeDir)();
+
+    config.set('network', NETWORK_LOCAL);
+    config.set('group', 'local');
+    config.set('core.miner.enable', true);
+    config.set('core.miner.address', address);
+
+    return config;
+  }
+
+  function seedConfigFile(config) {
+    const configFile = new ConfigFile(
+      [config],
+      '4.1.0',
+      'abcdef12',
+      config.getName(),
+      'local',
+    );
+
+    fs.writeFileSync(
+      homeDir.joinPath('config.json'),
+      `${JSON.stringify(configFile.toObject(), undefined, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  beforeEach(function beforeEach() {
+    homeDir = HomeDir.createTemp();
+    configFileRepository = new ConfigFileJsonRepository(
+      (data) => data,
+      homeDir,
+      () => null,
+    );
+    dockerCompose = {
+      execCommand: this.sinon.stub().resolves(),
+    };
+    renderedConfig = null;
+    renderedWhileLocked = false;
+    writeConfigTemplates = this.sinon.stub().callsFake((config) => {
+      renderedConfig = config;
+      renderedWhileLocked = fs.existsSync(homeDir.joinPath('config.json.lock'));
+    });
+
+    startGroupNodesTask = startGroupNodesTaskFactory(
+      dockerCompose,
+      this.sinon.stub().resolves(),
+      this.sinon.stub().resolves(),
+      this.sinon.stub().returns({}),
+      {},
+      this.sinon.stub().resolves(),
+      this.sinon.stub().resolves(),
+      this.sinon.stub().resolves(),
+      this.sinon.stub().resolves('127.0.0.1'),
+      configFileRepository,
+      writeConfigTemplates,
+    );
+  });
+
+  afterEach(() => {
+    homeDir.remove();
+  });
+
+  it('should persist a generated miner address instead of relying on command finalization', async () => {
+    const minerConfig = createMinerConfig(null);
+    seedConfigFile(minerConfig);
+
+    await startGroupNodesTask([minerConfig]).run({ waitForReadiness: false });
+
+    const persistedAddress = configFileRepository.read()
+      .getConfig(minerConfig.getName())
+      .get('core.miner.address');
+
+    expect(persistedAddress).to.be.a('string').and.not.empty();
+    expect(minerConfig.get('core.miner.address')).to.equal(persistedAddress);
+    expect(dockerCompose.execCommand.firstCall.args[2][2]).to.include(persistedAddress);
+    expect(writeConfigTemplates).to.have.been.calledOnce();
+    expect(renderedConfig.get('core.miner.address')).to.equal(persistedAddress);
+    expect(renderedWhileLocked).to.be.true();
+  });
+
+  it('should use an address set after the command loaded its config', async () => {
+    const minerConfig = createMinerConfig(null);
+    const freshConfig = createMinerConfig('yM6vM3D8R3g7v2YVnN9VqQqxv3ZQGQy2jS');
+    seedConfigFile(freshConfig);
+
+    await startGroupNodesTask([minerConfig]).run({ waitForReadiness: false });
+
+    expect(minerConfig.get('core.miner.address'))
+      .to.equal('yM6vM3D8R3g7v2YVnN9VqQqxv3ZQGQy2jS');
+    expect(dockerCompose.execCommand.firstCall.args[2][2])
+      .to.include('yM6vM3D8R3g7v2YVnN9VqQqxv3ZQGQy2jS');
+    expect(writeConfigTemplates).to.have.been.calledOnce();
+    expect(renderedConfig.get('core.miner.address'))
+      .to.equal('yM6vM3D8R3g7v2YVnN9VqQqxv3ZQGQy2jS');
+    expect(renderedWhileLocked).to.be.true();
+  });
+});
diff --git a/packages/dashmate/test/unit/templates/writeConfigTemplatesFactory.spec.js b/packages/dashmate/test/unit/templates/writeConfigTemplatesFactory.spec.js
new file mode 100644
index 00000000000..28b2bbb80c0
--- /dev/null
+++ b/packages/dashmate/test/unit/templates/writeConfigTemplatesFactory.spec.js
@@ -0,0 +1,23 @@
+import writeConfigTemplatesFactory from '../../../src/templates/writeConfigTemplatesFactory.js';
+
+describe('writeConfigTemplatesFactory', () => {
+  it('should mark the config saved only after writing its service files', function it() {
+    const config = {
+      getName: this.sinon.stub().returns('base'),
+      markAsSaved: this.sinon.stub(),
+    };
+    const serviceConfigs = { core: 'rendered' };
+    const renderServiceTemplates = this.sinon.stub().returns(serviceConfigs);
+    const writeServiceConfigs = this.sinon.stub();
+    const writeConfigTemplates = writeConfigTemplatesFactory(
+      renderServiceTemplates,
+      writeServiceConfigs,
+    );
+
+    writeConfigTemplates(config);
+
+    expect(writeServiceConfigs).to.have.been.calledOnceWithExactly('base', serviceConfigs);
+    expect(config.markAsSaved).to.have.been.calledOnce();
+    expect(writeServiceConfigs).to.have.been.calledBefore(config.markAsSaved);
+  });
+});