@devrouter/cli 0.0.79 → 0.1.0

package/dist/devrouter-lifecycle-worker.js

@@ -2051,7 +2051,10 @@ var import_node_child_process9 = require("child_process");
 var import_node_crypto4 = require("crypto");
 var import_node_fs8 = __toESM(require("fs"));
 var import_node_path9 = __toESM(require("path"));
-var SUPPORTED_DEVSY_VERSION = "1.16.2";
+var PINNED_DEVSY_AGENT_VERSION = "1.16.2";
+var SUPPORTED_DEVSY_MIN_VERSION = "1.16.2";
+var SUPPORTED_DEVSY_MAX_VERSION = "2.0.0";
+var SUPPORTED_DEVSY_RANGE = `>=${SUPPORTED_DEVSY_MIN_VERSION} <${SUPPORTED_DEVSY_MAX_VERSION}`;
 var DEVSY_AGENT_SETUP_COMMAND = "devrouter setup --yes --workspace-runtime devsy";
 var DEVSY_AGENT_ASSETS = [
   {
@@ -2082,19 +2085,90 @@ function parseVersion(output) {
     /\bv?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)\b/
   )?.[1];
 }
-function compareVersionCore(left, right) {
-  const core = (value) => value.split(/[-+]/, 1)[0].split(".").map((part) => Number.parseInt(part, 10));
-  const leftParts = core(left);
-  const rightParts = core(right);
-  for (let index = 0; index < 3; index += 1) {
-    const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
-    if (difference !== 0) return difference > 0 ? 1 : -1;
+function parseSemver(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    value.trim()
+  );
+  if (!match) return void 0;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".") : []
+  };
+}
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) return 0;
+  if (left.length === 0) return 1;
+  if (right.length === 0) return -1;
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const leftPart = left[index];
+    const rightPart = right[index];
+    if (leftPart === void 0) return -1;
+    if (rightPart === void 0) return 1;
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      const difference = Number(leftPart) - Number(rightPart);
+      if (difference !== 0) return difference < 0 ? -1 : 1;
+      continue;
+    }
+    if (leftNumeric) return -1;
+    if (rightNumeric) return 1;
+    if (leftPart !== rightPart) return leftPart < rightPart ? -1 : 1;
   }
   return 0;
 }
+function compareSemver(left, right) {
+  for (const part of ["major", "minor", "patch"]) {
+    if (left[part] !== right[part]) return left[part] < right[part] ? -1 : 1;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+function isSupportedDevsyVersion(version) {
+  const parsed = version === void 0 ? void 0 : parseSemver(version);
+  const minimum = parseSemver(SUPPORTED_DEVSY_MIN_VERSION);
+  const maximum = parseSemver(SUPPORTED_DEVSY_MAX_VERSION);
+  if (!parsed || !minimum || !maximum) return false;
+  if (compareSemver(parsed, minimum) < 0) return false;
+  if (parsed.prerelease.length > 0 && parsed.major === maximum.major && parsed.minor === maximum.minor && parsed.patch === maximum.patch) {
+    return false;
+  }
+  return compareSemver(parsed, maximum) < 0;
+}
+var DEVSY_AGENT_MANIFEST_FILE = "manifest.json";
+function isDevsyAgentAsset(value) {
+  if (!value || typeof value !== "object") return false;
+  const asset = value;
+  return typeof asset.githubAssetId === "number" && Number.isSafeInteger(asset.githubAssetId) && typeof asset.name === "string" && typeof asset.size === "number" && Number.isSafeInteger(asset.size) && asset.size > 0 && typeof asset.sha256 === "string" && /^[0-9a-f]{64}$/.test(asset.sha256) && typeof asset.url === "string" && asset.url.startsWith("https://");
+}
+function devsyAgentManifestPath(cacheRoot, devsyVersion) {
+  return import_node_path9.default.join(cacheRoot, `v${devsyVersion}`, DEVSY_AGENT_MANIFEST_FILE);
+}
+function readManifestRecord(cacheRoot, devsyVersion) {
+  try {
+    const parsed = JSON.parse(
+      import_node_fs8.default.readFileSync(devsyAgentManifestPath(cacheRoot, devsyVersion), "utf-8")
+    );
+    if (parsed.version !== 1 || parsed.devsyVersion !== devsyVersion) return void 0;
+    if (parsed.origin !== "release") return void 0;
+    if (!Array.isArray(parsed.assets) || parsed.assets.length === 0) return void 0;
+    if (!parsed.assets.every(isDevsyAgentAsset)) return void 0;
+    return { version: devsyVersion, origin: "release", assets: parsed.assets };
+  } catch {
+    return void 0;
+  }
+}
+function pinnedManifest(version) {
+  return version === PINNED_DEVSY_AGENT_VERSION ? { version, origin: "pinned", assets: DEVSY_AGENT_ASSETS } : void 0;
+}
+function manifestForVersion(resolved, version) {
+  if (resolved.assets) return { version, origin: "pinned", assets: resolved.assets };
+  return pinnedManifest(version) ?? readManifestRecord(resolved.cacheRoot, version);
+}
 function devsyAgentRepairSuggestion(inspection) {
   if (inspection.state === "stale") {
-    return `Install Devsy ${SUPPORTED_DEVSY_VERSION} for a supported host, then run: ${DEVSY_AGENT_SETUP_COMMAND}`;
+    return `Install a supported Devsy release (${SUPPORTED_DEVSY_RANGE}) for a supported host, then run: ${DEVSY_AGENT_SETUP_COMMAND}`;
   }
   return inspection.source === "explicit" ? `Fix or unset DEVSY_AGENT_BINARY, then run: ${DEVSY_AGENT_SETUP_COMMAND}` : `Run: ${DEVSY_AGENT_SETUP_COMMAND}`;
 }
@@ -2109,8 +2183,8 @@ function nativeAssetName(platform, arch) {
   if (arch === "x64") return "devsy-linux-amd64";
   return void 0;
 }
-function managedBinaryPath(cacheRoot, asset) {
-  return import_node_path9.default.join(cacheRoot, `v${SUPPORTED_DEVSY_VERSION}`, asset.name);
+function managedBinaryPath(cacheRoot, devsyVersion, asset) {
+  return import_node_path9.default.join(cacheRoot, `v${devsyVersion}`, asset.name);
 }
 function hashOpenFile(file) {
   const digest = (0, import_node_crypto4.createHash)("sha256");
@@ -2154,7 +2228,7 @@ function resolvedOptions(options) {
     versionOutput: options.versionOutput ?? installedVersionOutput(),
     cacheRoot: options.cacheRoot ?? import_node_path9.default.join(CACHE_DIR, "devsy", "agents"),
     lockPath: options.lockPath ?? DEVSY_AGENT_CACHE_LOCK,
-    assets: options.assets ?? DEVSY_AGENT_ASSETS,
+    assets: options.assets,
     nativeAssetName: options.nativeAssetName
   };
 }
@@ -2163,54 +2237,75 @@ function inspectDevsyAgent(options = {}) {
   const installedVersion = parseVersion(resolved.versionOutput);
   const explicitPath = resolved.env.DEVSY_AGENT_BINARY?.trim();
   const source = explicitPath ? "explicit" : "managed";
-  if (installedVersion === void 0 || installedVersion !== SUPPORTED_DEVSY_VERSION && compareVersionCore(installedVersion, SUPPORTED_DEVSY_VERSION) <= 0) {
+  if (!installedVersion) {
     return {
       state: "stale",
       source,
-      reason: installedVersion ? `installed Devsy ${installedVersion} is not supported by this Devrouter release` : "the supported Devsy version is not available",
-      installedVersion
+      reason: `the installed Devsy version could not be determined; Devrouter supports ${SUPPORTED_DEVSY_RANGE}`
     };
   }
-  if (explicitPath) {
+  if (!isSupportedDevsyVersion(installedVersion)) {
     return {
-      ...inspectBinary(explicitPath, resolved.assets, "invalid"),
+      state: "stale",
       source,
-      binaryPath: explicitPath,
+      reason: `installed Devsy ${installedVersion} is outside the supported range ${SUPPORTED_DEVSY_RANGE}`,
       installedVersion
     };
   }
-  if (installedVersion !== SUPPORTED_DEVSY_VERSION) {
+  const manifest = manifestForVersion(resolved, installedVersion);
+  if (!manifest) {
+    if (explicitPath) {
+      return {
+        ...inspectBinary(explicitPath, resolved.assets ?? DEVSY_AGENT_ASSETS, "invalid"),
+        source,
+        binaryPath: explicitPath,
+        installedVersion
+      };
+    }
     return {
       state: "ready",
       source: "host",
-      reason: `installed Devsy ${installedVersion} is newer than the verified ${SUPPORTED_DEVSY_VERSION} agent; the host CLI governs its own agent`,
+      reason: `no verified Devsy ${installedVersion} agent manifest is recorded yet; the host CLI governs its own agent`,
       installedVersion,
-      drift: { installed: installedVersion, supported: SUPPORTED_DEVSY_VERSION }
+      drift: { installed: installedVersion, supported: PINNED_DEVSY_AGENT_VERSION }
     };
   }
   const expectedName = resolved.nativeAssetName ?? nativeAssetName(resolved.platform, resolved.arch);
-  const asset = resolved.assets.find((candidate) => candidate.name === expectedName);
+  const asset = manifest.assets.find((candidate) => candidate.name === expectedName);
   if (!asset) {
     return {
       state: "stale",
       source,
-      reason: `this Devrouter release has no pinned Devsy agent for ${resolved.platform}/${resolved.arch}`,
-      installedVersion
+      reason: `Devsy ${installedVersion} has no official agent for ${resolved.platform}/${resolved.arch}`,
+      installedVersion,
+      manifestOrigin: manifest.origin
+    };
+  }
+  if (explicitPath) {
+    return {
+      ...inspectBinary(explicitPath, [asset], "invalid"),
+      source,
+      binaryPath: explicitPath,
+      installedVersion,
+      manifestOrigin: manifest.origin
     };
   }
-  const binaryPath = managedBinaryPath(resolved.cacheRoot, asset);
+  const binaryPath = managedBinaryPath(resolved.cacheRoot, installedVersion, asset);
   return {
     ...inspectBinary(binaryPath, [asset], "missing"),
     source,
     binaryPath,
     asset,
-    installedVersion
+    installedVersion,
+    manifestOrigin: manifest.origin
   };
 }
-function requireReadyDevsyAgent(options = {}) {
-  const inspection = inspectDevsyAgent(options);
-  if (inspection.state !== "ready") throw new DevsyAgentReadinessError(inspection);
+function isReadyInspection(inspection) {
+  return inspection.state === "ready" && inspection.installedVersion !== void 0;
+}
+function preparedFromInspection(inspection) {
   return {
+    version: inspection.installedVersion,
     binaryPath: inspection.binaryPath,
     source: inspection.source,
     asset: inspection.asset,
@@ -2218,6 +2313,11 @@ function requireReadyDevsyAgent(options = {}) {
     transport: "existing"
   };
 }
+function requireReadyDevsyAgent(options = {}) {
+  const inspection = inspectDevsyAgent(options);
+  if (!isReadyInspection(inspection)) throw new DevsyAgentReadinessError(inspection);
+  return preparedFromInspection(inspection);
+}
 
 // src/core/managed-devsy-stop.ts
 var import_node_fs21 = __toESM(require("fs"));
@@ -4402,6 +4502,8 @@ var CapacityStore = class {
   file;
   establishedFile;
   observedLedger = false;
+  /** Identity of the snapshot file read last, so a replacement cannot reuse its revision. */
+  ledgerGeneration;
   readEstablished() {
     let descriptor;
     try {
@@ -4428,7 +4530,7 @@ var CapacityStore = class {
       import_node_fs15.default.closeSync(descriptor);
     }
   }
-  read() {
+  inspect() {
     const minimumRevision = this.minimumRevision();
     const established = this.readEstablished();
     let descriptor;
@@ -4439,9 +4541,9 @@ var CapacityStore = class {
       );
     } catch (error) {
       if (error.code === "ENOENT") {
-        if (established || this.observedLedger || minimumRevision > 0)
-          throw new CapacityHistoryError("capacity-ledger-lost");
-        return { version: 1, revision: 0, reservations: [] };
+        this.ledgerGeneration = void 0;
+        if (established || this.observedLedger || minimumRevision > 0) return { kind: "absent" };
+        return { kind: "pristine" };
       }
       throw error;
     }
@@ -4454,16 +4556,36 @@ var CapacityStore = class {
       if (count > MAX_BYTES) throw new Error("Capacity reservation snapshot exceeds byte limit.");
       const value = JSON.parse(buffer.subarray(0, count).toString("utf8"));
       validate(value);
-      if (value.revision < minimumRevision) throw new CapacityHistoryError("capacity-ledger-lost");
+      this.ledgerGeneration = `${stat.dev}:${stat.ino}`;
+      if (value.revision < minimumRevision) return { kind: "stale", revision: value.revision };
       this.observedLedger = true;
-      return value;
+      return { kind: "intact", revision: value.revision, snapshot: value };
     } finally {
       import_node_fs15.default.closeSync(descriptor);
     }
   }
+  read() {
+    const state = this.inspect();
+    if (state.kind === "intact") return state.snapshot;
+    if (state.kind === "pristine") return { version: 1, revision: 0, reservations: [] };
+    throw new CapacityHistoryError("capacity-ledger-lost");
+  }
   establish() {
     if (!this.readEstablished()) this.write(this.establishedFile, '{"version":1}\n');
-    for (const file of [this.file, this.establishedFile, this.directory]) {
+    this.syncDurability([this.file, this.establishedFile, this.directory]);
+  }
+  /**
+   * Witness for a ledger that is positively absent. The marker records that
+   * history existed here, so no later process can read the store as a fresh
+   * install and start admitting; the snapshot stays absent until reconciliation.
+   * The caller holds the capacity lock and has proven environment cessation.
+   */
+  establishMarkerOnly() {
+    if (!this.readEstablished()) this.write(this.establishedFile, '{"version":1}\n');
+    this.syncDurability([this.establishedFile, this.directory]);
+  }
+  syncDurability(files) {
+    for (const file of files) {
       const descriptor = import_node_fs15.default.openSync(
         file,
         import_node_fs15.default.constants.O_RDONLY | import_node_fs15.default.constants.O_NOFOLLOW | import_node_fs15.default.constants.O_NONBLOCK
@@ -4479,15 +4601,90 @@ var CapacityStore = class {
     }
   }
   readForMutation() {
+    const expectedGeneration = this.ledgerGeneration;
     const snapshot = this.read();
+    if (expectedGeneration !== void 0 && expectedGeneration !== this.ledgerGeneration)
+      throw new CapacitySnapshotChangedError();
     if (this.observedLedger) this.establish();
     return snapshot;
   }
   commit(snapshot) {
     this.write(this.file, serializeSnapshot(snapshot));
     this.observedLedger = true;
+    this.rememberGeneration();
     this.establish();
   }
+  /** Remember the published snapshot identity for the next generation fence. */
+  rememberGeneration() {
+    try {
+      const stat = import_node_fs15.default.statSync(this.file);
+      this.ledgerGeneration = stat.isFile() ? `${stat.dev}:${stat.ino}` : void 0;
+    } catch {
+      this.ledgerGeneration = void 0;
+    }
+  }
+  /**
+   * Durable evidence that recorded history is gone, for a stop whose physical
+   * cessation is already proven. The caller holds that proof; this writes no
+   * row and asserts nothing about any other environment's charge.
+   */
+  recordLedgerLoss() {
+    assertPrivateDirectory(this.directory);
+    withFileLockSync(
+      `${this.file}.lock`,
+      { activity: "capacity loss witness", waitMs: 100 },
+      () => {
+        if (this.inspect().kind !== "absent")
+          throw new CapacityHistoryError("capacity-ledger-lost");
+        this.establishMarkerOnly();
+      }
+    );
+  }
+  /**
+   * Replace a provably absent ledger with a fresh baseline under the capacity
+   * lock. `plan` runs inside the lock with the authoritative classification and
+   * re-verifies the caller's evidence, returning the baseline to write or
+   * undefined to refuse without mutation. `confirm` runs in the same lock after
+   * the write; returning false withdraws the fresh snapshot, so the store reads
+   * as lost again instead of publishing a baseline the caller cannot stand behind.
+   */
+  reconcileLostHistory(plan, confirm) {
+    assertPrivateDirectory(this.directory);
+    return withFileLockSync(
+      `${this.file}.lock`,
+      { activity: "capacity reconciliation", waitMs: 100 },
+      () => {
+        const baseline = plan(this.inspect());
+        if (!baseline) return { reconciled: false };
+        if (!Number.isSafeInteger(baseline.revision) || baseline.revision < 1)
+          throw new Error("Invalid capacity reconciliation revision.");
+        const pools = structuredClone(baseline.pools ?? []);
+        validatePools(pools);
+        const snapshot = pools.length === 0 ? { version: 1, revision: baseline.revision, reservations: [] } : { version: 1, revision: baseline.revision, reservations: [], pools };
+        validate(snapshot);
+        this.commit(snapshot);
+        if (confirm()) return { reconciled: true, revision: snapshot.revision };
+        this.withdrawSnapshot();
+        return { reconciled: false };
+      }
+    );
+  }
+  /** Remove a snapshot this store just wrote, keeping the loss witness durable. */
+  withdrawSnapshot() {
+    try {
+      import_node_fs15.default.unlinkSync(this.file);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    this.observedLedger = false;
+    this.ledgerGeneration = void 0;
+    const directory = import_node_fs15.default.openSync(this.directory, "r");
+    try {
+      import_node_fs15.default.fsyncSync(directory);
+    } finally {
+      import_node_fs15.default.closeSync(directory);
+    }
+  }
   /**
    * Caller must revoke journal authority and prove exact physical cessation first.
    * An absent reservation still advances the revision to fence that proof.
@@ -5150,7 +5347,7 @@ function retain(session, previous) {
 
 // src/core/reliability-operation-store.ts
 function installedCliVersion() {
-  return true ? "0.0.79" : "0.0.0-dev";
+  return true ? "0.1.0" : "0.0.0-dev";
 }
 function compareCliVersions(left, right) {
   const parts = (value) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
@@ -5475,16 +5672,26 @@ function validate2(record5, identity2) {
 function createLifecycleCapacityStore(directory = import_node_path21.default.join(DEVROUTER_HOME, "controller")) {
   return new CapacityStore(directory, void 0, () => {
     try {
-      let revision = 0;
-      for (const record5 of listReliabilityOperations()) {
-        if (record5.capacity) revision = Math.max(revision, record5.capacity.snapshotRevision ?? 1);
-      }
-      return revision;
+      return listUnsettledCapacityBindings().floor;
     } catch {
       throw new CapacityHistoryError("capacity-history-unprovable");
     }
   });
 }
+function listUnsettledCapacityBindings() {
+  let floor = 0;
+  const bindings = [];
+  for (const record5 of listReliabilityOperations()) {
+    if (!record5.capacity) continue;
+    floor = Math.max(floor, record5.capacity.snapshotRevision ?? 1);
+    bindings.push({
+      environmentId: record5.state.environmentId,
+      repoPath: record5.identity.repoPath,
+      workspace: record5.identity.workspace
+    });
+  }
+  return { floor, bindings };
+}
 function assertCapacityEffect(record5, workerId, nowMs, directory = import_node_path21.default.join(DEVROUTER_HOME, "controller")) {
   if (record5.version === 1) return;
   const binding = record5.capacity;
@@ -5707,7 +5914,7 @@ function formatSupportedTcpProtocols() {
 }
 
 // src/core/repo-config.ts
-function compareSemver(a, b) {
+function compareSemver2(a, b) {
   const parse2 = (v) => {
     const match = v.trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
     return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) } : { major: 0, minor: 0, patch: 0 };
@@ -6956,8 +7163,8 @@ function loadRepoConfig(repoPath, read2 = (file) => import_node_fs18.default.rea
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.79" : "0.0.0-dev";
-    if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
+    const cliVersion = true ? "0.1.0" : "0.0.0-dev";
+    if (cliVersion !== "0.0.0-dev" && compareSemver2(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
         `
@@ -9602,8 +9809,9 @@ function inspectNetworkProviderBinding(input) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(providerContext)) throw new Error();
     const contextArgs = ["--context", providerContext];
     const version = read(provider, provider === "devsy" ? ["--version"] : ["version"]);
-    const expectedVersion = provider === "devsy" ? "1.16.2" : "0.6.15";
-    if (version.match(/\b(?:v)?(\d+\.\d+\.\d+)\b/)?.[1] !== expectedVersion) throw new Error();
+    const parsedVersion = version.match(/\b(?:v)?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/)?.[1];
+    if (provider === "devsy" ? !isSupportedDevsyVersion(parsedVersion) : parsedVersion !== "0.6.15")
+      throw new Error();
     const definitions = object2(
       JSON.parse(
         read(
@@ -11281,6 +11489,9 @@ function holderAttribution(holder, repoPath) {
   return attribution;
 }
 function remediationFor(holder, attribution) {
+  if (holder.name === ROUTER_CONTAINER_NAME) {
+    return "The shared devrouter router owns this port as a platform entrypoint and must keep running; change the consumer's fixed host binding, or route the dependency through devrouter's TCP protocol route, then run ensure again.";
+  }
   if (attribution.holderWorktreePath) {
     return `Stop the holding workspace with 'devrouter stop ${attribution.holderWorktreePath}', or override the consumer's published host binding through its own configuration, then run ensure again.`;
   }
@@ -13922,6 +14133,17 @@ function assertOverlay(container, repoPath) {
     throw new Error(`Container '${container.id}' was not started with ${DEVCONTAINER_OVERLAY}.`);
   }
 }
+function assertWorktreeOwnership(container, repoPath) {
+  const workingDir = container.labels["com.docker.compose.project.working_dir"];
+  if (!workingDir || !isInsideWorktree(workingDir, repoPath)) {
+    throw new Error(`Container '${container.id}' does not belong to the exact worktree.`);
+  }
+}
+function isInsideWorktree(candidate, repoPath) {
+  const normalizedCandidate = comparableWorkspacePath(candidate);
+  const normalizedRoot = comparableWorkspacePath(repoPath);
+  return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}${import_node_path39.default.sep}`);
+}
 function assertReady(container, label) {
   if (!container.state.Running) {
     throw new Error(`${label} container '${container.id}' is not running.`);
@@ -14194,7 +14416,7 @@ function validateWorkspaceContainers(containers, options) {
       );
     }
     if (options.target.kind === "linked") {
-      assertOverlay(matches[0], options.repoPath);
+      assertWorktreeOwnership(matches[0], options.repoPath);
     }
     assertReady(matches[0], `Workspace upstream '${host}'`);
   }
@@ -15875,8 +16097,20 @@ function proveLifecycleStopped() {
       const capacity = createLifecycleCapacityStore(import_node_path40.default.join(DEVROUTER_HOME, "controller"));
       for (let attempt = 0; ; attempt++) {
         try {
-          capacity.settleEnvironmentAfterStop(settlement, capacity.read().revision);
-          break;
+          const state = capacity.inspect();
+          if (state.kind === "intact") {
+            capacity.settleEnvironmentAfterStop(settlement, state.revision);
+            break;
+          }
+          if (state.kind === "absent") {
+            capacity.recordLedgerLoss();
+            break;
+          }
+          if (state.kind === "pristine") {
+            capacity.settleEnvironmentAfterStop(settlement, 0);
+            break;
+          }
+          throw new CapacityHistoryError("capacity-ledger-lost");
         } catch (error) {
           if (!(error instanceof CapacitySnapshotChangedError) || attempt >= 2) throw error;
         }