@devrouter/cli 0.0.66 → 0.0.67

package/dist/devrouter-lifecycle-worker.js

@@ -1188,6 +1188,17 @@ function inspectDevsyRuntimeStatus(devsyId) {
   if (result.status !== 0 || result.error) return "unknown";
   return parseDevsyRuntimeStatus(result.stdout, devsyId);
 }
+function inspectDevsyRuntimeAbsence(devsyId) {
+  const result = (0, import_node_child_process5.spawnSync)("devsy", ["workspace", "status", devsyId, "--result-format", "json"], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (!result.error && result.status === 0) {
+    return parseDevsyRuntimeStatus(result.stdout, devsyId) === "not-found";
+  }
+  const output = [result.error?.message, result.stdout, result.stderr].filter(Boolean).join("\n");
+  return /workspace not found/i.test(output);
+}
 function inspectDevsyWorkspaceOwnership(workspaces, devsyId, worktreePath) {
   const idOwners = workspaces.filter((workspace) => workspace.id === devsyId);
   const pathOwners = workspaces.filter(
@@ -1987,6 +1998,7 @@ function requireReadyDevsyAgent(options = {}) {
 // src/core/managed-devsy-stop.ts
 var import_node_os4 = __toESM(require("os"));
 var import_node_path20 = __toESM(require("path"));
+var import_node_util4 = require("util");
 
 // src/core/devcontainer-profile.ts
 var import_node_child_process10 = require("child_process");
@@ -4863,7 +4875,7 @@ function loadRepoConfig(repoPath, read2 = (file) => import_node_fs14.default.rea
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.66" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.67" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -5418,6 +5430,66 @@ function stopRetainedManagedDevsyWorkspace(options) {
     }
     return owner.workspace;
   }
+  function registrationStatus() {
+    resetWorkspaceRuntimeCaches();
+    if (resolveWorkspaceRuntimeOrDefault(repoPath) !== "devsy") {
+      throw new Error("Managed stop provider selection changed.");
+    }
+    return inspectDevsyWorkspaceOwnership(listDevsyWorkspaces(), devsyId, repoPath);
+  }
+  function proveAbsentRegistrationStop() {
+    const observe = () => {
+      const owner = registrationStatus();
+      if (owner.status === "conflict") throw new Error(owner.reason);
+      if (owner.status !== "absent") {
+        throw new Error("Managed stop absence proof requires the registration to remain absent.");
+      }
+      if (listDevpodWorkspacesRaw({ allowMissingExecutable: true }).some(
+        (entry) => entry.id === devsyId || sameWorkspacePath(entry.source.localFolder, repoPath)
+      )) {
+        throw new Error(
+          "Managed stop absence proof requires both provider registrations to remain absent."
+        );
+      }
+      if (!inspectDevsyRuntimeAbsence(devsyId)) {
+        throw new Error(
+          "Managed stop absence proof requires Devsy to report the runtime not-found."
+        );
+      }
+      if (inspectManagedStopContainers(state.composeProject).length !== 0) {
+        throw new Error("Managed stop absence proof observed a remaining compose population.");
+      }
+      if (inspectProviderRunnerContainers(resolveManagedStopEndpoint(), devsyId).length !== 0) {
+        throw new Error("Managed stop absence proof observed a remaining runner population.");
+      }
+      const owned = inspectWorkspaceContainers().filter(
+        (container) => sameWorkspacePath(
+          container.labels["com.docker.compose.project.working_dir"] ?? "",
+          import_node_path20.default.join(repoPath, ".devcontainer")
+        )
+      );
+      if (owned.length !== 0) {
+        throw new Error("Managed stop absence proof observed a remaining workspace container.");
+      }
+      if (workspace) {
+        const record5 = readWorkspaceOwnership(repoPath, workspace);
+        if (!record5 || record5.devpodId !== devsyId || !sameWorkspacePath(record5.worktreePath, repoPath) || resolveWorktreeWorkspace(repoPath) !== workspace || resolveGitCommonDir(repoPath) !== workspaceEnv?.gitCommonDir || inspectWorkspaceOwnership(record5, listGitWorktrees(repoPath), void 0).ownerStatus !== "present") {
+          throw new Error("Managed stop workspace ownership changed during absence proof.");
+        }
+      }
+      if (!(0, import_node_util4.isDeepStrictEqual)(readManagedRuntimeState(repoPath, workspace), state)) {
+        throw new Error("Managed stop retained state changed during absence proof.");
+      }
+    };
+    observe();
+    observe();
+  }
+  const initialOwner = registrationStatus();
+  if (initialOwner.status === "conflict") throw new Error(initialOwner.reason);
+  if (initialOwner.status === "absent") {
+    proveAbsentRegistrationStop();
+    return "proven-absent";
+  }
   const context = registration2().context;
   if (!context || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(context) || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(devsyId)) {
     throw new Error("Managed stop requires a valid exact Devsy context and workspace ID.");
@@ -7396,6 +7468,7 @@ function assertReliabilityEvent(value) {
     case "launched":
     case "interrupted":
     case "not-started":
+    case "settle":
       valid = isReliabilityId(value.operationId);
       break;
     case "completion":
@@ -7465,8 +7538,13 @@ function transition(state, outcome, effects = []) {
   assertReliabilityState(state);
   return { state, effects, outcome };
 }
-function unchanged(state, outcome) {
-  return transition(cloneState(state), outcome);
+function unchanged(state, outcome, reason2) {
+  const result = transition(cloneState(state), outcome);
+  if (reason2) result.reason = reason2;
+  return result;
+}
+function blocked(state, reason2) {
+  return unchanged(state, "blocked", reason2);
 }
 function advance(value) {
   return value === Number.MAX_SAFE_INTEGER ? null : value + 1;
@@ -7491,7 +7569,10 @@ function updateRunningPhase(state) {
 }
 function handleRequest(state, event) {
   if (state.executionPolicy === "manual" && event.mode === "start")
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      "start requests are not admitted under manual execution policy; use the ensure/stop commands."
+    );
   const existing = state.requests.find((request) => request.key === event.key);
   if (existing) {
     const consumer = state.consumers.find((candidate) => candidate.id === existing.consumerId);
@@ -7558,7 +7639,8 @@ function handleRequest(state, event) {
 }
 function canExecAfterInterruptedEnsure(state) {
   const latestEnsure = [...state.operationHistory].reverse().find((operation) => operation.kind === "ensure");
-  return state.executionPolicy === "manual" && state.desired === "running" && latestEnsure?.status === "INTERRUPTED" && latestEnsure.drained && state.operation?.drained === true && (state.operation.kind === "ensure" && state.phase === "recovering" || state.operation.kind === "exec" && ["COMPLETED", "NOT_LAUNCHED", "NOT_STARTED"].includes(state.operation.status));
+  const quiescent = state.stopProof.workloadsStopped && state.stopProof.routesRemoved;
+  return state.executionPolicy === "manual" && (state.desired === "running" || quiescent && state.desired === "stopped-by-user") && latestEnsure?.status === "INTERRUPTED" && latestEnsure.drained && state.operation?.drained === true && (state.operation.kind === "ensure" && (state.phase === "recovering" || quiescent) || state.operation.kind === "exec" && ["COMPLETED", "NOT_LAUNCHED", "NOT_STARTED"].includes(state.operation.status));
 }
 function handleOperationRequest(state, event) {
   if (state.executionPolicy !== "manual") return unchanged(state, "blocked");
@@ -7571,25 +7653,39 @@ function handleOperationRequest(state, event) {
   if (state.operationHistory.some((entry) => entry.id === event.operationId))
     return unchanged(state, "conflict");
   if (event.kind === "exec" && canExecAfterInterruptedEnsure(state) && event.recoverInterruptedEnsure !== true)
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      "the latest ensure is INTERRUPTED and drained; exec requires recovering it first (run ensure, or exec with recovery proof)."
+    );
   const fullyStopped = state.stopProof.workloadsStopped && state.stopProof.routesRemoved;
   const reconcileEnsure = event.kind === "ensure" && state.operation?.kind === "ensure" && ["NOT_STARTED", "INTERRUPTED"].includes(state.operation.status);
   if (state.operation && (!state.operation.drained || !["COMPLETED", "NOT_LAUNCHED", "NOT_STARTED"].includes(state.operation.status) && !fullyStopped && !reconcileEnsure && !(event.kind === "exec" && event.recoverInterruptedEnsure === true && canExecAfterInterruptedEnsure(state))))
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      `operation ${state.operation.id} is ${state.operation.status} (drained=${state.operation.drained}) and no stop proof, ensure reconciliation, or exec recovery supersedes it.`
+    );
   if (state.phase === "stopping" || state.desired === "parked-for-capacity")
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      `phase is '${state.phase}' with desired '${state.desired}'; wait for the running stop to finish.`
+    );
   if (event.kind === "exec" && (!event.runtimeRunning || state.desired !== "running" && state.intentRevision !== 0))
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      `exec requires a running workspace (runtimeRunning=${event.runtimeRunning}, desired='${state.desired}').`
+    );
   const rollover = state.operationHistory.length >= RELIABILITY_MAX_ITEMS;
   let retired = -1;
   if (rollover) {
-    if (state.operation && (!state.operation.drained || !["COMPLETED", "NOT_LAUNCHED"].includes(state.operation.status)))
-      return unchanged(state, "blocked");
     const latestEnsureId = [...state.operationHistory].reverse().find((entry) => entry.kind === "ensure")?.id;
     retired = state.operationHistory.findIndex(
-      (entry) => entry.id !== state.operation?.id && entry.id !== latestEnsureId && entry.drained && ["COMPLETED", "NOT_LAUNCHED"].includes(entry.status)
+      (entry) => entry.id !== state.operation?.id && entry.id !== latestEnsureId && entry.drained && ["COMPLETED", "NOT_LAUNCHED", "INTERRUPTED"].includes(entry.status)
     );
-    if (retired === -1) return unchanged(state, "blocked");
+    if (retired === -1)
+      return blocked(
+        state,
+        `journal holds ${state.operationHistory.length} entries and every retirable entry is the current operation or the latest ensure.`
+      );
   }
   if (state.desired !== "running" || rollover) {
     const revision = advance(state.intentRevision);
@@ -7644,7 +7740,10 @@ function handleDispatch(state) {
   if (state.operation?.drained || state.operation?.status !== "NOT_STARTED")
     return unchanged(state, "stale");
   if (state.desired !== "running" || state.executionPolicy === "capacity-managed" && state.admission !== "admitted" || state.consumers.length === 0) {
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      `dispatch requires desired 'running' with a registered consumer (desired='${state.desired}', consumers=${state.consumers.length}).`
+    );
   }
   const corrective = state.phase === "recovering" && state.incident !== null;
   state.operation = { ...state.operation, status: "DISPATCH_PENDING", exitCode: null };
@@ -7659,7 +7758,10 @@ function handleDispatchPersisted(state, event) {
   if (state.desired !== "running" || state.executionPolicy === "capacity-managed" && (state.admission !== "admitted" || !state.chargeHeld)) {
     state.operation = setUnknown(state.operation);
     state.chargeHeld = state.executionPolicy === "capacity-managed";
-    return transition(state, "blocked");
+    return blocked(
+      state,
+      `dispatch persistence requires desired 'running' (desired='${state.desired}'); the operation outcome is unknown.`
+    );
   }
   if (state.phase === "recovering" && state.incident !== null && state.incident.correctiveActionsTaken >= state.incident.actionLimit) {
     return unchanged(state, "blocked");
@@ -7707,6 +7809,22 @@ function handleInterrupted(state, event) {
   if (state.desired === "running") state.phase = "recovering";
   return transition(state, "accepted");
 }
+function handleSettle(state, event) {
+  if (state.executionPolicy !== "manual") return unchanged(state, "stale");
+  if (!state.operation || state.operation.id !== event.operationId)
+    return unchanged(state, "stale");
+  if (state.operation.drained && state.operation.status === "INTERRUPTED")
+    return unchanged(state, "joined");
+  if (state.operation.status === "COMPLETED") return unchanged(state, "joined");
+  state.operation = {
+    ...state.operation,
+    status: "INTERRUPTED",
+    drained: true,
+    exitCode: null
+  };
+  if (state.desired === "running") state.phase = "recovering";
+  return transition(state, "accepted");
+}
 function handleObservation(state, event, nowMs) {
   if (state.desired !== "running") return unchanged(state, "stale");
   const previous = state.observations.find(
@@ -7716,7 +7834,10 @@ function handleObservation(state, event, nowMs) {
     return unchanged(state, "stale");
   }
   if (!previous && state.observations.length >= RELIABILITY_MAX_ITEMS)
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      `observation set holds ${state.observations.length} distinct capabilities; observations repeat per capability and never retire.`
+    );
   state.observations = state.observations.filter(
     (observation) => observation.capability !== event.observation.capability
   );
@@ -7744,7 +7865,10 @@ function handleStop(state) {
 function handleStopProof(state, event) {
   if (state.desired === "running") return unchanged(state, "stale");
   if (state.executionPolicy === "manual" && state.operation && !state.operation.drained && event.workloadsStopped && event.routesRemoved)
-    return unchanged(state, "blocked");
+    return blocked(
+      state,
+      `stop proof cannot settle while operation ${state.operation.id} is not drained; wait for its worker or settle the journal.`
+    );
   const previous = { ...state.stopProof };
   if (previous.workloadsStopped === event.workloadsStopped && previous.routesRemoved === event.routesRemoved)
     return unchanged(state, "joined");
@@ -7923,6 +8047,8 @@ function applyReliabilityEvent(state, event, nowMs) {
       return handleCompletion(next, event);
     case "interrupted":
       return handleInterrupted(next, event);
+    case "settle":
+      return handleSettle(next, event);
     case "observation":
       return handleObservation(next, event, nowMs);
     case "stop-proof":
@@ -7958,6 +8084,19 @@ function stepReliability(state, event, nowMs) {
 var import_node_crypto11 = require("crypto");
 var import_node_fs20 = __toESM(require("fs"));
 var import_node_path25 = __toESM(require("path"));
+function installedCliVersion() {
+  return true ? "0.0.67" : "0.0.0-dev";
+}
+function compareCliVersions(left, right) {
+  const parts = (value) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const leftParts = parts(left);
+  const rightParts = parts(right);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
 var MAX_RECORD_BYTES = 1048576;
 function identityKey(identity2) {
   if (!import_node_path25.default.isAbsolute(identity2.repoPath) || import_node_path25.default.resolve(identity2.repoPath) !== identity2.repoPath || identity2.repoPath.includes("\0") || identity2.workspace !== null && !isReliabilityId(identity2.workspace) || !["devpod", "devsy"].includes(identity2.provider)) {
@@ -7974,7 +8113,21 @@ function keys(value, expected) {
   }
 }
 function validate(record5, identity2) {
-  keys(record5, ["version", "identity", "revision", "state", "worker", "effectSequence", "outcome"]);
+  keys(record5, [
+    "version",
+    "identity",
+    "revision",
+    "state",
+    "worker",
+    "effectSequence",
+    "outcome",
+    "writtenByVersion"
+  ]);
+  if (record5.writtenByVersion !== void 0 && compareCliVersions(record5.writtenByVersion, installedCliVersion()) > 0) {
+    throw new Error(
+      `Reliability record was last written by devrouter ${record5.writtenByVersion}, which is newer than the installed ${installedCliVersion()}; upgrade devrouter (devrouter upgrade) before running lifecycle commands.`
+    );
+  }
   keys(record5.identity, ["repoPath", "workspace", "provider"]);
   if (record5.version !== 1 || record5.identity.repoPath !== identity2.repoPath || record5.identity.workspace !== identity2.workspace || record5.identity.provider !== identity2.provider || !isReliabilityCounter(record5.revision) || !isReliabilityCounter(record5.effectSequence)) {
     throw new Error("Reliability record has invalid version, ownership, or counters.");
@@ -8115,6 +8268,7 @@ function updateReliabilityOperation(identity2, operation) {
     if (result && typeof result.then === "function") {
       throw new Error("Reliability record updates must be synchronous.");
     }
+    record5.writtenByVersion = installedCliVersion();
     validate(record5, identity2);
     record5.revision += 1;
     persist(record5);
@@ -12861,7 +13015,9 @@ async function withLifecycleOperationLock(repoPath, operation) {
 function stepRecord(record5, event) {
   const transition2 = stepReliability(record5.state, event, Date.now());
   if (!["accepted", "joined"].includes(transition2.outcome))
-    throw new Error(`Lifecycle transition is ${transition2.outcome}.`);
+    throw new Error(
+      `Lifecycle transition is ${transition2.outcome}.${transition2.reason ? ` ${transition2.reason}` : ""}`
+    );
   record5.state = transition2.state;
 }
 function reconcileDrained(record5) {

package/dist/devrouter.js

@@ -2520,7 +2520,7 @@ function loadRepoConfig(repoPath, read2 = (file) => import_node_fs6.default.read
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.66" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.67" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -3494,6 +3494,19 @@ var init_reliability_contract = __esm({
 });
 
 // src/core/reliability-operation-store.ts
+function installedCliVersion() {
+  return true ? "0.0.67" : "0.0.0-dev";
+}
+function compareCliVersions(left, right) {
+  const parts = (value) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const leftParts = parts(left);
+  const rightParts = parts(right);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
 function identityKey(identity2) {
   if (!import_node_path10.default.isAbsolute(identity2.repoPath) || import_node_path10.default.resolve(identity2.repoPath) !== identity2.repoPath || identity2.repoPath.includes("\0") || identity2.workspace !== null && !isReliabilityId(identity2.workspace) || !["devpod", "devsy"].includes(identity2.provider)) {
     throw new Error("Invalid reliability workspace identity.");
@@ -3509,7 +3522,21 @@ function keys(value, expected) {
   }
 }
 function validate(record5, identity2) {
-  keys(record5, ["version", "identity", "revision", "state", "worker", "effectSequence", "outcome"]);
+  keys(record5, [
+    "version",
+    "identity",
+    "revision",
+    "state",
+    "worker",
+    "effectSequence",
+    "outcome",
+    "writtenByVersion"
+  ]);
+  if (record5.writtenByVersion !== void 0 && compareCliVersions(record5.writtenByVersion, installedCliVersion()) > 0) {
+    throw new Error(
+      `Reliability record was last written by devrouter ${record5.writtenByVersion}, which is newer than the installed ${installedCliVersion()}; upgrade devrouter (devrouter upgrade) before running lifecycle commands.`
+    );
+  }
   keys(record5.identity, ["repoPath", "workspace", "provider"]);
   if (record5.version !== 1 || record5.identity.repoPath !== identity2.repoPath || record5.identity.workspace !== identity2.workspace || record5.identity.provider !== identity2.provider || !isReliabilityCounter(record5.revision) || !isReliabilityCounter(record5.effectSequence)) {
     throw new Error("Reliability record has invalid version, ownership, or counters.");
@@ -3650,6 +3677,7 @@ function updateReliabilityOperation(identity2, operation) {
     if (result && typeof result.then === "function") {
       throw new Error("Reliability record updates must be synchronous.");
     }
+    record5.writtenByVersion = installedCliVersion();
     validate(record5, identity2);
     record5.revision += 1;
     persist(record5);
@@ -7462,6 +7490,10 @@ var init_ai_prompt = __esm({
       {
         command: "devrouter workspace gc [--json] [--yes]",
         purpose: "Report missing owners without mutation by default; --yes deletes only exact eligible ledger-owned resources and records, never Git worktrees."
+      },
+      {
+        command: "devrouter workspace journal settle [path] [--json]",
+        purpose: "Settle a lifecycle operation whose worker is provably gone as unobservable so ensure/stop can proceed; never hand-edit the devrouter state directory."
       }
     ];
   }
@@ -11467,6 +11499,17 @@ function inspectDevsyRuntimeStatus(devsyId) {
   if (result.status !== 0 || result.error) return "unknown";
   return parseDevsyRuntimeStatus(result.stdout, devsyId);
 }
+function inspectDevsyRuntimeAbsence(devsyId) {
+  const result = (0, import_node_child_process16.spawnSync)("devsy", ["workspace", "status", devsyId, "--result-format", "json"], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (!result.error && result.status === 0) {
+    return parseDevsyRuntimeStatus(result.stdout, devsyId) === "not-found";
+  }
+  const output2 = [result.error?.message, result.stdout, result.stderr].filter(Boolean).join("\n");
+  return /workspace not found/i.test(output2);
+}
 function inspectDevsyWorkspaceOwnership(workspaces, devsyId, worktreePath) {
   const idOwners = workspaces.filter((workspace) => workspace.id === devsyId);
   const pathOwners = workspaces.filter(
@@ -13092,6 +13135,66 @@ function stopRetainedManagedDevsyWorkspace(options) {
     }
     return owner.workspace;
   }
+  function registrationStatus() {
+    resetWorkspaceRuntimeCaches();
+    if (resolveWorkspaceRuntimeOrDefault(repoPath) !== "devsy") {
+      throw new Error("Managed stop provider selection changed.");
+    }
+    return inspectDevsyWorkspaceOwnership(listDevsyWorkspaces(), devsyId, repoPath);
+  }
+  function proveAbsentRegistrationStop() {
+    const observe = () => {
+      const owner = registrationStatus();
+      if (owner.status === "conflict") throw new Error(owner.reason);
+      if (owner.status !== "absent") {
+        throw new Error("Managed stop absence proof requires the registration to remain absent.");
+      }
+      if (listDevpodWorkspacesRaw({ allowMissingExecutable: true }).some(
+        (entry) => entry.id === devsyId || sameWorkspacePath(entry.source.localFolder, repoPath)
+      )) {
+        throw new Error(
+          "Managed stop absence proof requires both provider registrations to remain absent."
+        );
+      }
+      if (!inspectDevsyRuntimeAbsence(devsyId)) {
+        throw new Error(
+          "Managed stop absence proof requires Devsy to report the runtime not-found."
+        );
+      }
+      if (inspectManagedStopContainers(state.composeProject).length !== 0) {
+        throw new Error("Managed stop absence proof observed a remaining compose population.");
+      }
+      if (inspectProviderRunnerContainers(resolveManagedStopEndpoint(), devsyId).length !== 0) {
+        throw new Error("Managed stop absence proof observed a remaining runner population.");
+      }
+      const owned = inspectWorkspaceContainers().filter(
+        (container) => sameWorkspacePath(
+          container.labels["com.docker.compose.project.working_dir"] ?? "",
+          import_node_path36.default.join(repoPath, ".devcontainer")
+        )
+      );
+      if (owned.length !== 0) {
+        throw new Error("Managed stop absence proof observed a remaining workspace container.");
+      }
+      if (workspace) {
+        const record5 = readWorkspaceOwnership(repoPath, workspace);
+        if (!record5 || record5.devpodId !== devsyId || !sameWorkspacePath(record5.worktreePath, repoPath) || resolveWorktreeWorkspace(repoPath) !== workspace || resolveGitCommonDir(repoPath) !== workspaceEnv?.gitCommonDir || inspectWorkspaceOwnership(record5, listGitWorktrees(repoPath), void 0).ownerStatus !== "present") {
+          throw new Error("Managed stop workspace ownership changed during absence proof.");
+        }
+      }
+      if (!(0, import_node_util4.isDeepStrictEqual)(readManagedRuntimeState(repoPath, workspace), state)) {
+        throw new Error("Managed stop retained state changed during absence proof.");
+      }
+    };
+    observe();
+    observe();
+  }
+  const initialOwner = registrationStatus();
+  if (initialOwner.status === "conflict") throw new Error(initialOwner.reason);
+  if (initialOwner.status === "absent") {
+    proveAbsentRegistrationStop();
+    return "proven-absent";
+  }
   const context = registration2().context;
   if (!context || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(context) || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(devsyId)) {
     throw new Error("Managed stop requires a valid exact Devsy context and workspace ID.");
@@ -13201,14 +13304,16 @@ function stopRetainedManagedDevsyWorkspace(options) {
   if (providerFailed) throw providerError;
   return true;
 }
-var import_node_os4, import_node_path36;
+var import_node_os4, import_node_path36, import_node_util4;
 var init_managed_devsy_stop = __esm({
   "src/core/managed-devsy-stop.ts"() {
     "use strict";
     import_node_os4 = __toESM(require("os"));
     import_node_path36 = __toESM(require("path"));
+    import_node_util4 = require("util");
     init_devcontainer_profile();
     init_devpod_environment();
+    init_devpod_registry();
     init_devsy_workspaces();
     init_managed_compose_population();
     init_managed_runtime_state();
@@ -14185,7 +14290,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.66" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.67" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -14871,6 +14976,7 @@ function assertReliabilityEvent(value) {
     case "launched":
     case "interrupted":
     case "not-started":
+    case "settle":
       valid = isReliabilityId(value.operationId);
       break;
     case "completion":
@@ -14940,8 +15046,13 @@ function transition(state, outcome, effects = []) {
   assertReliabilityState(state);
   return { state, effects, outcome };
 }
-function unchanged(state, outcome) {
-  return transition(cloneState(state), outcome);
+function unchanged(state, outcome, reason) {
+  const result = transition(cloneState(state), outcome);
+  if (reason) result.reason = reason;
+  return result;
+}
+function blocked2(state, reason) {
+  return unchanged(state, "blocked", reason);
 }
 function advance(value) {
   return value === Number.MAX_SAFE_INTEGER ? null : value + 1;
@@ -14966,7 +15077,10 @@ function updateRunningPhase(state) {
 }
 function handleRequest(state, event) {
   if (state.executionPolicy === "manual" && event.mode === "start")
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      "start requests are not admitted under manual execution policy; use the ensure/stop commands."
+    );
   const existing = state.requests.find((request) => request.key === event.key);
   if (existing) {
     const consumer = state.consumers.find((candidate) => candidate.id === existing.consumerId);
@@ -15033,7 +15147,8 @@ function handleRequest(state, event) {
 }
 function canExecAfterInterruptedEnsure(state) {
   const latestEnsure = [...state.operationHistory].reverse().find((operation) => operation.kind === "ensure");
-  return state.executionPolicy === "manual" && state.desired === "running" && latestEnsure?.status === "INTERRUPTED" && latestEnsure.drained && state.operation?.drained === true && (state.operation.kind === "ensure" && state.phase === "recovering" || state.operation.kind === "exec" && ["COMPLETED", "NOT_LAUNCHED", "NOT_STARTED"].includes(state.operation.status));
+  const quiescent = state.stopProof.workloadsStopped && state.stopProof.routesRemoved;
+  return state.executionPolicy === "manual" && (state.desired === "running" || quiescent && state.desired === "stopped-by-user") && latestEnsure?.status === "INTERRUPTED" && latestEnsure.drained && state.operation?.drained === true && (state.operation.kind === "ensure" && (state.phase === "recovering" || quiescent) || state.operation.kind === "exec" && ["COMPLETED", "NOT_LAUNCHED", "NOT_STARTED"].includes(state.operation.status));
 }
 function handleOperationRequest(state, event) {
   if (state.executionPolicy !== "manual") return unchanged(state, "blocked");
@@ -15046,25 +15161,39 @@ function handleOperationRequest(state, event) {
   if (state.operationHistory.some((entry) => entry.id === event.operationId))
     return unchanged(state, "conflict");
   if (event.kind === "exec" && canExecAfterInterruptedEnsure(state) && event.recoverInterruptedEnsure !== true)
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      "the latest ensure is INTERRUPTED and drained; exec requires recovering it first (run ensure, or exec with recovery proof)."
+    );
   const fullyStopped = state.stopProof.workloadsStopped && state.stopProof.routesRemoved;
   const reconcileEnsure = event.kind === "ensure" && state.operation?.kind === "ensure" && ["NOT_STARTED", "INTERRUPTED"].includes(state.operation.status);
   if (state.operation && (!state.operation.drained || !["COMPLETED", "NOT_LAUNCHED", "NOT_STARTED"].includes(state.operation.status) && !fullyStopped && !reconcileEnsure && !(event.kind === "exec" && event.recoverInterruptedEnsure === true && canExecAfterInterruptedEnsure(state))))
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      `operation ${state.operation.id} is ${state.operation.status} (drained=${state.operation.drained}) and no stop proof, ensure reconciliation, or exec recovery supersedes it.`
+    );
   if (state.phase === "stopping" || state.desired === "parked-for-capacity")
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      `phase is '${state.phase}' with desired '${state.desired}'; wait for the running stop to finish.`
+    );
   if (event.kind === "exec" && (!event.runtimeRunning || state.desired !== "running" && state.intentRevision !== 0))
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      `exec requires a running workspace (runtimeRunning=${event.runtimeRunning}, desired='${state.desired}').`
+    );
   const rollover = state.operationHistory.length >= RELIABILITY_MAX_ITEMS;
   let retired = -1;
   if (rollover) {
-    if (state.operation && (!state.operation.drained || !["COMPLETED", "NOT_LAUNCHED"].includes(state.operation.status)))
-      return unchanged(state, "blocked");
     const latestEnsureId = [...state.operationHistory].reverse().find((entry) => entry.kind === "ensure")?.id;
     retired = state.operationHistory.findIndex(
-      (entry) => entry.id !== state.operation?.id && entry.id !== latestEnsureId && entry.drained && ["COMPLETED", "NOT_LAUNCHED"].includes(entry.status)
+      (entry) => entry.id !== state.operation?.id && entry.id !== latestEnsureId && entry.drained && ["COMPLETED", "NOT_LAUNCHED", "INTERRUPTED"].includes(entry.status)
     );
-    if (retired === -1) return unchanged(state, "blocked");
+    if (retired === -1)
+      return blocked2(
+        state,
+        `journal holds ${state.operationHistory.length} entries and every retirable entry is the current operation or the latest ensure.`
+      );
   }
   if (state.desired !== "running" || rollover) {
     const revision = advance(state.intentRevision);
@@ -15119,7 +15248,10 @@ function handleDispatch(state) {
   if (state.operation?.drained || state.operation?.status !== "NOT_STARTED")
     return unchanged(state, "stale");
   if (state.desired !== "running" || state.executionPolicy === "capacity-managed" && state.admission !== "admitted" || state.consumers.length === 0) {
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      `dispatch requires desired 'running' with a registered consumer (desired='${state.desired}', consumers=${state.consumers.length}).`
+    );
   }
   const corrective = state.phase === "recovering" && state.incident !== null;
   state.operation = { ...state.operation, status: "DISPATCH_PENDING", exitCode: null };
@@ -15134,7 +15266,10 @@ function handleDispatchPersisted(state, event) {
   if (state.desired !== "running" || state.executionPolicy === "capacity-managed" && (state.admission !== "admitted" || !state.chargeHeld)) {
     state.operation = setUnknown(state.operation);
     state.chargeHeld = state.executionPolicy === "capacity-managed";
-    return transition(state, "blocked");
+    return blocked2(
+      state,
+      `dispatch persistence requires desired 'running' (desired='${state.desired}'); the operation outcome is unknown.`
+    );
   }
   if (state.phase === "recovering" && state.incident !== null && state.incident.correctiveActionsTaken >= state.incident.actionLimit) {
     return unchanged(state, "blocked");
@@ -15182,6 +15317,22 @@ function handleInterrupted(state, event) {
   if (state.desired === "running") state.phase = "recovering";
   return transition(state, "accepted");
 }
+function handleSettle(state, event) {
+  if (state.executionPolicy !== "manual") return unchanged(state, "stale");
+  if (!state.operation || state.operation.id !== event.operationId)
+    return unchanged(state, "stale");
+  if (state.operation.drained && state.operation.status === "INTERRUPTED")
+    return unchanged(state, "joined");
+  if (state.operation.status === "COMPLETED") return unchanged(state, "joined");
+  state.operation = {
+    ...state.operation,
+    status: "INTERRUPTED",
+    drained: true,
+    exitCode: null
+  };
+  if (state.desired === "running") state.phase = "recovering";
+  return transition(state, "accepted");
+}
 function handleObservation(state, event, nowMs) {
   if (state.desired !== "running") return unchanged(state, "stale");
   const previous = state.observations.find(
@@ -15191,7 +15342,10 @@ function handleObservation(state, event, nowMs) {
     return unchanged(state, "stale");
   }
   if (!previous && state.observations.length >= RELIABILITY_MAX_ITEMS)
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      `observation set holds ${state.observations.length} distinct capabilities; observations repeat per capability and never retire.`
+    );
   state.observations = state.observations.filter(
     (observation) => observation.capability !== event.observation.capability
   );
@@ -15219,7 +15373,10 @@ function handleStop(state) {
 function handleStopProof(state, event) {
   if (state.desired === "running") return unchanged(state, "stale");
   if (state.executionPolicy === "manual" && state.operation && !state.operation.drained && event.workloadsStopped && event.routesRemoved)
-    return unchanged(state, "blocked");
+    return blocked2(
+      state,
+      `stop proof cannot settle while operation ${state.operation.id} is not drained; wait for its worker or settle the journal.`
+    );
   const previous = { ...state.stopProof };
   if (previous.workloadsStopped === event.workloadsStopped && previous.routesRemoved === event.routesRemoved)
     return unchanged(state, "joined");
@@ -15398,6 +15555,8 @@ function applyReliabilityEvent(state, event, nowMs) {
       return handleCompletion(next, event);
     case "interrupted":
       return handleInterrupted(next, event);
+    case "settle":
+      return handleSettle(next, event);
     case "observation":
       return handleObservation(next, event, nowMs);
     case "stop-proof":
@@ -15558,7 +15717,9 @@ async function runLifecycleWorker(request, beforeAdmission) {
                   Date.now()
                 );
                 if (admitted.outcome !== "accepted")
-                  throw new Error(`Lifecycle admission is ${admitted.outcome}.`);
+                  throw new Error(
+                    `Lifecycle admission is ${admitted.outcome}.${admitted.reason ? ` ${admitted.reason}` : ""}`
+                  );
                 record5.state = admitted.state;
                 record5.outcome = null;
                 request.fence = reliabilityFence(record5.state);
@@ -16048,7 +16209,9 @@ async function withLifecycleOperationLock(repoPath, operation) {
 function stepRecord(record5, event) {
   const transition2 = stepReliability(record5.state, event, Date.now());
   if (!["accepted", "joined"].includes(transition2.outcome))
-    throw new Error(`Lifecycle transition is ${transition2.outcome}.`);
+    throw new Error(
+      `Lifecycle transition is ${transition2.outcome}.${transition2.reason ? ` ${transition2.reason}` : ""}`
+    );
   record5.state = transition2.state;
 }
 function reconcileDrained(record5) {
@@ -20397,6 +20560,70 @@ var init_workspace_cleanup = __esm({
   }
 });
 
+// src/core/workspace-journal-settle.ts
+async function settleWorkspaceJournal(repoPath) {
+  repoPath = comparableWorkspacePath(repoPath);
+  if (isLinkedWorktree(repoPath) && !readPersistedWorkspace(repoPath)) {
+    throw new Error("Settle requires the existing linked workspace identity.");
+  }
+  const identity2 = {
+    repoPath,
+    workspace: resolveWorktreeWorkspace(repoPath) ?? null,
+    provider: resolveWorkspaceRuntimeOrDefault(repoPath)
+  };
+  if (!readReliabilityOperation(identity2)) {
+    throw new Error(`No reliability journal exists for '${repoPath}'; nothing to settle.`);
+  }
+  const settled = await withWorkspaceLifecycleLock(
+    repoPath,
+    async () => updateReliabilityOperation(identity2, (record5) => settleRecord(record5))
+  );
+  return { repoPath, workspace: identity2.workspace, ...settled };
+}
+function settleRecord(record5) {
+  if (record5.worker) {
+    const birth = processBirthIdentity(record5.worker.pid);
+    if (birth === record5.worker.birth || !workerGroupAbsent(record5.worker.pid)) {
+      throw new Error(
+        `Lifecycle worker '${record5.worker.id}' is still running; settle is refused while its outcome is observable.`
+      );
+    }
+    reconcileDrained(record5);
+    if (record5.worker) throw new Error("Dead lifecycle worker could not be drained.");
+  }
+  const operation = record5.state.operation;
+  if (!operation) throw new Error("No lifecycle operation is recorded; nothing to settle.");
+  const priorStatus = operation.status;
+  const transition2 = stepReliability(
+    record5.state,
+    { ...reliabilityFence(record5.state), type: "settle", operationId: operation.id },
+    Date.now()
+  );
+  if (!["accepted", "joined"].includes(transition2.outcome))
+    throw new Error(
+      `Lifecycle settlement is ${transition2.outcome}.${transition2.reason ? ` ${transition2.reason}` : ""}`
+    );
+  record5.state = transition2.state;
+  return {
+    operationId: operation.id,
+    status: transition2.outcome === "joined" ? "already-settled" : "settled",
+    priorStatus
+  };
+}
+var init_workspace_journal_settle = __esm({
+  "src/core/workspace-journal-settle.ts"() {
+    "use strict";
+    init_file_lock();
+    init_reliability_contract();
+    init_reliability_lifecycle();
+    init_reliability_model();
+    init_reliability_operation_store();
+    init_reliability_worker();
+    init_workspace();
+    init_workspace_runtime();
+  }
+});
+
 // src/core/workspace-lifecycle.ts
 function withWorkspaceAllocationTransaction(repoPath, operation) {
   return withWorkspaceOwnershipTransaction(repoPath, operation, {
@@ -20800,6 +21027,7 @@ __export(workspace_exports, {
   runWorkspaceCleanupCommand: () => runWorkspaceCleanupCommand,
   runWorkspaceDownCommand: () => runWorkspaceDownCommand,
   runWorkspaceGcCommand: () => runWorkspaceGcCommand,
+  runWorkspaceJournalSettleCommand: () => runWorkspaceJournalSettleCommand,
   runWorkspaceLsCommand: () => runWorkspaceLsCommand,
   runWorkspaceStopCommand: () => runWorkspaceStopCommand,
   runWorkspaceUpCommand: () => runWorkspaceUpCommand
@@ -20889,6 +21117,26 @@ function runWorkspaceGcCommand(options) {
   }
   if (report.summary.errors > 0) process.exitCode = 1;
 }
+async function runWorkspaceJournalSettleCommand(options) {
+  const repoPath = resolveGitCheckoutPath(options.path);
+  const result = await settleWorkspaceJournal(repoPath);
+  if (options.json) {
+    printJSON(result);
+    return;
+  }
+  const workspaceLabel = result.workspace ? ` (workspace '${result.workspace}')` : "";
+  if (result.status === "already-settled") {
+    process.stdout.write(
+      `Journal operation ${result.operationId} is already settled${workspaceLabel}.
+`
+    );
+    return;
+  }
+  process.stdout.write(
+    `Settled journal operation ${result.operationId} (was ${result.priorStatus})${workspaceLabel}; ensure and stop may proceed.
+`
+  );
+}
 var init_workspace2 = __esm({
   "src/commands/workspace.ts"() {
     "use strict";
@@ -20896,8 +21144,10 @@ var init_workspace2 = __esm({
     init_repo_config();
     init_workspace_cleanup();
     init_workspace_gc();
+    init_workspace_journal_settle();
     init_workspace_lifecycle();
     init_workspace_ownership();
+    init_environment_path();
   }
 });
 
@@ -20939,7 +21189,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.66" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.67" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {
@@ -21309,6 +21559,15 @@ workspaceCommand2.command("down").description("Delete a workspace's runtime and
     await runWorkspaceDownCommand2(target, options);
   })
 );
+workspaceCommand2.command("journal settle").description(
+  "Settle an interrupted lifecycle operation as unobservable so ensure and stop can proceed"
+).argument("[path]", "Checkout path (defaults to current directory)").option("--json", "Output JSON").action(
+  withErrorHandling(async (path54, _options, command) => {
+    const options = command.opts();
+    const { runWorkspaceJournalSettleCommand: runWorkspaceJournalSettleCommand2 } = await Promise.resolve().then(() => (init_workspace2(), workspace_exports));
+    await runWorkspaceJournalSettleCommand2({ ...path54 ? { path: path54 } : {}, ...options });
+  })
+);
 function parseVersionRequest(argv) {
   let requested = false;
   let repo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "description": "Local dev routing CLI with shared Traefik reverse proxy",
   "author": "Roland Schlaefli",
   "homepage": "https://github.com/rschlaefli/devrouter#readme",

package/upgrade-prompts/0.0.67.md

@@ -0,0 +1,41 @@
+# Upgrade to devrouter 0.0.67
+
+This patch release makes the reliability journal incapable of deadlocking
+lifecycle commands and completes managed stop when a registration was deleted
+rather than replaced. It restores workspaces that every canonical command
+previously refused with "Lifecycle admission is blocked." after a saturated
+journal held a drained `INTERRUPTED` ensure.
+
+## Task
+
+Install the published release and update `.devrouter.yml` devrouter.version to
+0.0.67. No schema migration or configuration change is required. Do not change
+the committed configuration, delete registrations, containers, or source files,
+and do not reset lifecycle state manually. Recovery runs inside the existing
+canonical commands under their normal locks, ownership proofs, and journal
+accounting. If a command reports a live worker, wait for it or re-run later;
+`workspace journal settle` refuses while a worker outcome is still observable.
+
+## Validation
+
+On a workspace whose commands were refused with "Lifecycle admission is
+blocked." (saturated journal with a drained interrupted ensure), run
+`devrouter stop <path>` and confirm it completes — including the case where the
+Devsy registration was already deleted and every workload is positively absent
+— then run `devrouter ensure <path> --json` and confirm admission succeeds with
+routes published. On a record whose worker is provably gone and that still
+refuses progress, run `devrouter workspace journal settle <path> --json` and
+confirm it reports the settled operation, then retry `ensure`. Confirm refusal
+messages now name the blocking field and remediation. For workspaces that never
+hit the deadlock, confirm existing stop, ensure, exec, and `devrouter doctor`
+behavior is unchanged, and confirm a downgrade attempt (record written by a
+newer CLI than the installed one) fails with an explicit upgrade instruction
+instead of a mid-flight refusal.
+
+## Report
+
+Report the tested CLI version, the exact workspace path or synthetic fixture,
+each command result (stop, ensure, settle if used) with route state after the
+run, any diagnostic failure output verbatim, and whether the
+deleted-registration case, the saturated-journal case, or only the unchanged
+retained path was exercised.