@devrouter/cli 0.0.51 → 0.0.52

package/bin/devrouter-process

@@ -187,9 +187,9 @@ process_owned() {
   [ "$actual_pgid" = "$pgid" ] || return 1
   [ "$pgid" = "$pid" ] || return 1
   tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null |
-    grep -Fqx "DEVROUTER_PROCESS_NAME=$name" || return 1
+    grep -Fx "DEVROUTER_PROCESS_NAME=$name" >/dev/null || return 1
   tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null |
-    grep -Fqx "DEVROUTER_PROCESS_FINGERPRINT=$expected_fingerprint"
+    grep -Fx "DEVROUTER_PROCESS_FINGERPRINT=$expected_fingerprint" >/dev/null
 }
 
 process_group_alive() {
@@ -217,7 +217,7 @@ is_helper_process() {
   local candidate="$1"
 
   [ -r "/proc/$candidate/cmdline" ] || return 1
-  tr '\0' '\n' <"/proc/$candidate/cmdline" 2>/dev/null | grep -Fqx "$0"
+  tr '\0' '\n' <"/proc/$candidate/cmdline" 2>/dev/null | grep -Fx "$0" >/dev/null
 }
 
 marked_process_exists() {
@@ -230,7 +230,7 @@ marked_process_exists() {
     pid="${pid%/environ}"
     process_alive "$pid" || continue
     is_self_or_ancestor "$pid" && continue
-    if tr '\0' '\n' <"$environ" 2>/dev/null | grep -Fqx "DEVROUTER_PROCESS_NAME=$name"; then
+    if tr '\0' '\n' <"$environ" 2>/dev/null | grep -Fx "DEVROUTER_PROCESS_NAME=$name" >/dev/null; then
       return 0
     fi
   done

package/dist/devrouter.js

@@ -400,7 +400,7 @@ Run several worktrees of one repo in parallel without host/route collisions. A *
 - \`devrouter -V [--repo .]\`: show installed CLI version, local repo version, and next upgrade target
 - \`devrouter upgrade [version] [--repo .]\`: list upgrade targets or print target Agent Adaptation Prompt
 - \`devrouter setup --yes [--repo .] [--json] [--workspace-runtime <devpod|devsy>]\`: first-run machine setup plus structured diagnostics; explicit Devsy selection acquires its verified agent
-- \`devrouter ensure [path] [--profile <name>] [--open] [--json]\`: canonical startup/reconciliation for primary and linked checkouts; a managed profile selects its independent resource dimensions
+- \`devrouter ensure [path] [--profile <name>] [--repair] [--open] [--json]\`: canonical startup/reconciliation for primary and linked checkouts; explicit repair uses the recorded degraded profile and unchanged retained configuration
 - \`devrouter profile resolve --repo <path> [--profile <selection>] [--json]\`: resolve exact profile resources for automation without starting or inspecting a runtime
 - \`devrouter profile plan --repo <path> [--profile <selection>] --contract <repo-relative-yaml> [--output <path>] [--json]\`: validate repository-owned resource policy and emit literal bindings without runtime access
 - \`devrouter stop [path] [--delete] [--json]\`: stop the exact workspace runtime and remove exact routes; \`--delete\` explicitly deletes its ownership-proven data without removing the checkout
@@ -425,7 +425,7 @@ Run several worktrees of one repo in parallel without host/route collisions. A *
 - \`devrouter app exec <name> [--shell] [--env <env>] [--workspace <slug>] -- <cmd>\`: one-shot command with resolved dep env
 - \`devrouter app rm <name> [--keep-config]\`: remove app entry (\`--keep-config\` frees only the live route/hostname, leaves \`.devrouter.yml\` untouched)
 - \`devrouter workspace up <branch> [--path <dir>] [--no-devpod] [--open]\`: create a worktree and start/prove it unless create-only mode is requested
-- \`devrouter workspace ensure [path] [--profile <name>] [--open] [--json]\`: compatibility alias of \`devrouter ensure\`
+- \`devrouter workspace ensure [path] [--profile <name>] [--repair] [--open] [--json]\`: compatibility alias of \`devrouter ensure\`
 - \`devrouter workspace ls [--json]\`: list ownership, Git, workspace runtime, route, path, and branch evidence
 - \`devrouter workspace cleanup [--repo .] [--inactive-for 30d] [--check-merged] [--measure-size] [--json]\`: report-only cleanup evidence and exact guarded suggestions; no \`--yes\` or apply mode
 - \`devrouter workspace stop <workspace|branch>\`: stop DevPod and routes; preserve checkout, owner record, and data
@@ -2691,7 +2691,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.51" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.52" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -3273,6 +3273,7 @@ function buildOnboardingPrompt(options = {}) {
     "- devrouter repo devcontainer write --repo <REPO_PATH> --yes",
     "- devrouter repo devcontainer verify --repo <REPO_PATH> --json",
     "- Normal primary or linked startup: devrouter ensure <REPO_PATH> --json",
+    "- Degraded recovery: explicit devrouter ensure <REPO_PATH> --repair --json validates the recorded profile and unchanged retained configuration; stopped primary requires all project containers stopped and zero checkout routes. It starts only retained IDs, never provider bootstrap/recreation. Inspect failures before retrying.",
     "- Managed selective startup: devrouter ensure <REPO_PATH> --profile <name> --json",
     "- Container seed/migration: devrouter exec <REPO_PATH> -- <command...>",
     "- Compatibility verification only after ensure: devrouter repo devcontainer verify --repo <REPO_PATH> --live --yes --json",
@@ -3391,7 +3392,7 @@ var init_ai_prompt = __esm({
         purpose: "Write/update devrouter section in the repo's AGENTS.md and install the devrouter skill."
       },
       {
-        command: "devrouter ensure [path] [--profile <name>] [--open] [--json]",
+        command: "devrouter ensure [path] [--profile <name>] [--repair] [--open] [--json]",
         purpose: "Canonical startup and proof for an exact primary or linked checkout; atomically publishes routes after readiness."
       },
       {
@@ -5691,19 +5692,12 @@ function assertSafeContainerId(containerId) {
     throw new Error(`Container '${containerId}' is not a safe exact identifier.`);
   }
 }
-function startExactManagedServices(options) {
-  if (options.services.length === 0) return;
-  const project = safeComposeProject(options.composeProject);
-  const services = Array.from(new Set(options.services));
-  if (services.some((service) => !options.plan.composeServices.includes(service))) {
-    throw new Error("Exact Compose startup contains a service outside the validated model.");
-  }
-  const fileArgs = options.plan.composeFiles.flatMap((file) => ["-f", file]);
+function managedComposeEnvironment(workspace) {
   const env = { ...process.env };
-  if (options.workspace) {
-    env.WORKSPACE = options.workspace.token;
-    env.DEVROUTER_WORKSPACE = options.workspace.token;
-    env.DEVROUTER_GIT_COMMON_DIR = options.workspace.gitCommonDir;
+  if (workspace) {
+    env.WORKSPACE = workspace.token;
+    env.DEVROUTER_WORKSPACE = workspace.token;
+    env.DEVROUTER_GIT_COMMON_DIR = workspace.gitCommonDir;
     env.DEVCONTAINER_COMPOSE_OVERLAY = "docker-compose.devrouter.yml";
   } else {
     delete env.WORKSPACE;
@@ -5711,6 +5705,87 @@ function startExactManagedServices(options) {
     delete env.DEVROUTER_GIT_COMMON_DIR;
     delete env.DEVCONTAINER_COMPOSE_OVERLAY;
   }
+  return env;
+}
+function assertReadableComposeFile(file) {
+  try {
+    if (!import_node_fs15.default.statSync(file).isFile()) throw new Error("not a regular file");
+    import_node_fs15.default.accessSync(file, import_node_fs15.default.constants.R_OK);
+  } catch {
+    throw new Error("Managed container Compose configuration contains an unreadable file.");
+  }
+}
+function assertManagedContainerConfigUnchanged(options) {
+  if (options.containers.length === 0) {
+    throw new Error("Managed container configuration cannot be verified without containers.");
+  }
+  for (const container of options.containers) {
+    const project = container.labels["com.docker.compose.project"];
+    const service = container.labels["com.docker.compose.service"];
+    const workingDirectory = container.labels["com.docker.compose.project.working_dir"];
+    const recordedConfigFiles = container.labels["com.docker.compose.project.config_files"];
+    const expectedHash = container.labels["com.docker.compose.config-hash"];
+    if (!project || !service || !workingDirectory || !recordedConfigFiles || !expectedHash || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(service) || !/^[a-f0-9]{64}$/.test(expectedHash)) {
+      throw new Error("Managed container is missing valid Compose identity and hash labels.");
+    }
+    const composeProject = safeComposeProject(project);
+    const configFiles = recordedConfigFiles.split(",").map((file) => file.trim());
+    if (configFiles.some((file) => file.length === 0)) {
+      throw new Error("Managed container has an invalid recorded Compose file list.");
+    }
+    if (options.plan.composeFiles.some(
+      (expected) => !configFiles.some((actual) => sameWorkspacePath(actual, expected))
+    )) {
+      throw new Error("Managed container Compose files do not include the managed plan files.");
+    }
+    for (const file of configFiles) assertReadableComposeFile(file);
+    const fileArgs = configFiles.flatMap((file) => ["-f", file]);
+    const result = (() => {
+      try {
+        return (0, import_node_child_process7.spawnSync)(
+          "docker",
+          [
+            "compose",
+            "--project-name",
+            composeProject,
+            "--project-directory",
+            workingDirectory,
+            ...fileArgs,
+            "config",
+            "--hash",
+            service
+          ],
+          {
+            cwd: workingDirectory,
+            encoding: "utf-8",
+            env: managedComposeEnvironment(options.workspace),
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: COMPOSE_HASH_TIMEOUT_MS
+          }
+        );
+      } catch {
+        throw new Error(`Could not verify managed Compose configuration for service '${service}'.`);
+      }
+    })();
+    if (result.status !== 0 || result.error) {
+      throw new Error(`Could not verify managed Compose configuration for service '${service}'.`);
+    }
+    const output2 = typeof result.stdout === "string" ? result.stdout.trim() : "";
+    const match = /^(\S+)\s+([a-f0-9]{64})$/.exec(output2);
+    if (!match || match[1] !== service || match[2] !== expectedHash) {
+      throw new Error(`Managed Compose configuration changed for service '${service}'.`);
+    }
+  }
+}
+function startExactManagedServices(options) {
+  if (options.services.length === 0) return;
+  const project = safeComposeProject(options.composeProject);
+  const services = Array.from(new Set(options.services));
+  if (services.some((service) => !options.plan.composeServices.includes(service))) {
+    throw new Error("Exact Compose startup contains a service outside the validated model.");
+  }
+  const fileArgs = options.plan.composeFiles.flatMap((file) => ["-f", file]);
+  const env = managedComposeEnvironment(options.workspace);
   const result = (0, import_node_child_process7.spawnSync)(
     "docker",
     [
@@ -5749,7 +5824,7 @@ function stopExactManagedService(containerId, service) {
     throw new Error(`Could not stop exact managed service '${service}' (${containerId}).`);
   }
 }
-var import_node_child_process7, import_node_crypto7, import_node_fs15, import_node_path15, import_yaml4, MANAGED_DEVCONTAINER_PATH, MANAGED_DEVCONTAINER_MARKER;
+var import_node_child_process7, import_node_crypto7, import_node_fs15, import_node_path15, import_yaml4, MANAGED_DEVCONTAINER_PATH, MANAGED_DEVCONTAINER_MARKER, COMPOSE_HASH_TIMEOUT_MS;
 var init_devcontainer_profile = __esm({
   "src/core/devcontainer-profile.ts"() {
     "use strict";
@@ -5761,8 +5836,10 @@ var init_devcontainer_profile = __esm({
     init_atomic_file();
     init_devcontainer_config();
     init_paths();
+    init_workspace();
     MANAGED_DEVCONTAINER_PATH = ".devcontainer/devcontainer.devrouter.json";
     MANAGED_DEVCONTAINER_MARKER = "// devrouter:managed devcontainer profile";
+    COMPOSE_HASH_TIMEOUT_MS = 1e4;
   }
 });
 
@@ -5857,7 +5934,7 @@ var init_devpod_environment = __esm({
     import_node_child_process8 = require("child_process");
     import_node_path16 = __toESM(require("path"));
     init_workspace();
-    SAFE_INSPECT_TEMPLATE = '{"id":{{json .Id}},"state":{"Running":{{json .State.Running}},"Health":{{with (index .State "Health")}}{"Status":{{json .Status}}}{{else}}null{{end}}},"labels":{"com.docker.compose.project":{{json (index .Config.Labels "com.docker.compose.project")}},"com.docker.compose.service":{{json (index .Config.Labels "com.docker.compose.service")}},"com.docker.compose.project.working_dir":{{json (index .Config.Labels "com.docker.compose.project.working_dir")}},"com.docker.compose.project.config_files":{{json (index .Config.Labels "com.docker.compose.project.config_files")}}},"mounts":{{json .Mounts}},"networks":{{json .NetworkSettings.Networks}}}';
+    SAFE_INSPECT_TEMPLATE = '{"id":{{json .Id}},"state":{"Running":{{json .State.Running}},"Health":{{with (index .State "Health")}}{"Status":{{json .Status}}}{{else}}null{{end}}},"labels":{"com.docker.compose.project":{{json (index .Config.Labels "com.docker.compose.project")}},"com.docker.compose.service":{{json (index .Config.Labels "com.docker.compose.service")}},"com.docker.compose.project.working_dir":{{json (index .Config.Labels "com.docker.compose.project.working_dir")}},"com.docker.compose.project.config_files":{{json (index .Config.Labels "com.docker.compose.project.config_files")}},"com.docker.compose.config-hash":{{json (index .Config.Labels "com.docker.compose.config-hash")}}},"mounts":{{json .Mounts}},"networks":{{json .NetworkSettings.Networks}}}';
     SIZE_INSPECT_TEMPLATE = SAFE_INSPECT_TEMPLATE.replace(
       /}$/,
       ',"sizeRw":{{json (index . "SizeRw")}},"sizeRootFs":{{json (index . "SizeRootFs")}}}'
@@ -6172,7 +6249,7 @@ function collectManagedRuntimeStatus(options) {
   let state;
   let stateReadFailed = false;
   try {
-    state = readManagedRuntimeState(options.repoPath, options.workspace);
+    state = options.candidateState ?? readManagedRuntimeState(options.repoPath, options.workspace);
   } catch {
     stateReadFailed = true;
   }
@@ -8054,6 +8131,12 @@ function validateRecord(value, expectedWorkspace) {
     updatedAt: validateTimestamp(candidate.updatedAt, "updatedAt")
   };
 }
+function recordPath(repoPath, workspace) {
+  return import_node_path22.default.join(
+    ownershipDirectory(repoPath),
+    `${validateWorkspace(workspace, "workspace")}.json`
+  );
+}
 function readRecordFile(filePath, expectedWorkspace) {
   let parsed;
   try {
@@ -8066,6 +8149,15 @@ function readRecordFile(filePath, expectedWorkspace) {
   }
   return validateRecord(parsed, expectedWorkspace);
 }
+function readWorkspaceOwnership(repoPath, workspace) {
+  const filePath = recordPath(repoPath, workspace);
+  try {
+    return readRecordFile(filePath, workspace);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
 function listWorkspaceOwnership(repoPath) {
   const directory = ownershipDirectory(repoPath);
   return listWorkspaceOwnershipInDirectory(directory);
@@ -9015,7 +9107,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.51" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.52" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -9727,9 +9819,9 @@ async function ensureRouteInfrastructure(apps, options = {}) {
   startRouterStack();
   return tlsCoverage;
 }
-async function replacePublishedProxyRoutes(repoPath, config, workspace) {
+async function replacePublishedProxyRoutes(repoPath, config, workspace, options = {}) {
   const apps = proxyAppsFromConfig(config);
-  const tlsCoverage = await ensureRouteInfrastructure(apps, { repoPath });
+  const tlsCoverage = options.prepareInfrastructure === false ? { refreshed: false } : await ensureRouteInfrastructure(apps, { repoPath });
   const routes = apps.map((app) => {
     const upstream = parseUpstream(app.upstream);
     return {
@@ -9769,7 +9861,7 @@ function inspectRouterApi(protocol) {
       "--show-error",
       "--fail",
       "--max-time",
-      "2",
+      ROUTER_API_REQUEST_TIMEOUT_SECONDS,
       `${ROUTER_API_BASE}/${protocol}/routers?per_page=${ROUTER_API_PAGE_SIZE}`
     ],
     { encoding: "utf-8" }
@@ -9801,6 +9893,161 @@ function inspectRouterApi(protocol) {
     )
   };
 }
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function inspectNamedRouterApi(protocol, resource, name) {
+  const result = (0, import_node_child_process20.spawnSync)(
+    "curl",
+    [
+      "--silent",
+      "--show-error",
+      "--fail",
+      "--max-time",
+      ROUTER_API_REQUEST_TIMEOUT_SECONDS,
+      `${ROUTER_API_BASE}/${protocol}/${resource}/${encodeURIComponent(name)}`
+    ],
+    { encoding: "utf-8" }
+  );
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      details: result.stderr?.trim() || `curl exited with status ${result.status ?? "unknown"}`
+    };
+  }
+  let value;
+  try {
+    value = JSON.parse(result.stdout);
+  } catch {
+    return {
+      ok: false,
+      details: `${protocol.toUpperCase()} ${resource.slice(0, -1)} API returned invalid JSON`
+    };
+  }
+  if (!isRecord2(value)) {
+    return {
+      ok: false,
+      details: `${protocol.toUpperCase()} ${resource.slice(0, -1)} API returned a non-object`
+    };
+  }
+  return { ok: true, value };
+}
+function renderExpectedRoute(route) {
+  const protocol = route.protocol ?? "http";
+  const routerName = buildHostRouteRouterName(route.repoPath, route.name);
+  const routeState = {
+    id: buildHostRouteId(route.repoPath, route.name),
+    name: route.name,
+    host: route.host,
+    protocol,
+    tcpProtocol: route.tcpProtocol,
+    repoPath: route.repoPath,
+    port: route.port,
+    mode: route.mode,
+    upstreamHost: route.upstreamHost,
+    pid: route.pid,
+    command: route.command,
+    workspace: route.workspace,
+    createdAt: "",
+    updatedAt: ""
+  };
+  const document = buildHostRoutesDocument([routeState], false);
+  const protocolDocument = document[protocol];
+  if (!isRecord2(protocolDocument)) return void 0;
+  const routers = protocolDocument.routers;
+  const services = protocolDocument.services;
+  if (!isRecord2(routers) || !isRecord2(services)) return void 0;
+  const routerKey = routerName.slice(0, routerName.lastIndexOf("@"));
+  const router = routers[routerKey];
+  const service = services[routerKey];
+  if (!isRecord2(router) || !isRecord2(service)) return void 0;
+  const rule = router.rule;
+  const serviceReference = router.service;
+  const loadBalancer = service.loadBalancer;
+  const servers = isRecord2(loadBalancer) ? loadBalancer.servers : void 0;
+  if (typeof rule !== "string" || serviceReference !== routerKey || !isRecord2(loadBalancer) || !Array.isArray(servers) || servers.length !== 1 || !isRecord2(servers[0])) {
+    return void 0;
+  }
+  const serverField = protocol === "http" ? "url" : "address";
+  const server = servers[0][serverField];
+  if (typeof server !== "string") return void 0;
+  const provider = routerName.slice(routerName.lastIndexOf("@")).trim();
+  if (!provider.startsWith("@")) return void 0;
+  return {
+    protocol,
+    routerName,
+    serviceKey: routerKey,
+    serviceName: `${routerKey}${provider}`,
+    rule,
+    serverField,
+    server
+  };
+}
+function inspectExpectedRouteMatch(route) {
+  const expected = renderExpectedRoute(route);
+  const routeName = buildHostRouteRouterName(route.repoPath, route.name);
+  if (!expected) {
+    return {
+      ok: false,
+      routes: [routeName],
+      details: "host-route renderer returned an incomplete route configuration"
+    };
+  }
+  const routerResult = inspectNamedRouterApi(expected.protocol, "routers", expected.routerName);
+  if (!routerResult.ok) {
+    return { ok: false, routes: [routeName], details: routerResult.details };
+  }
+  if (routerResult.value.status !== "enabled" || routerResult.value.name !== expected.routerName || routerResult.value.rule !== expected.rule || routerResult.value.service !== expected.serviceKey && routerResult.value.service !== expected.serviceName) {
+    return {
+      ok: false,
+      routes: [routeName],
+      details: "active Traefik router does not match the rendered route"
+    };
+  }
+  const serviceResult = inspectNamedRouterApi(expected.protocol, "services", expected.serviceName);
+  if (!serviceResult.ok) {
+    return { ok: false, routes: [routeName], details: serviceResult.details };
+  }
+  const loadBalancer = serviceResult.value.loadBalancer;
+  const servers = isRecord2(loadBalancer) ? loadBalancer.servers : void 0;
+  const server = Array.isArray(servers) && servers.length === 1 ? servers[0] : void 0;
+  if (serviceResult.value.status !== "enabled" || serviceResult.value.name !== expected.serviceName || !isRecord2(loadBalancer) || !Array.isArray(servers) || servers.length !== 1 || !isRecord2(server) || server[expected.serverField] !== expected.server) {
+    return {
+      ok: false,
+      routes: [routeName],
+      details: "active Traefik service does not match the rendered route"
+    };
+  }
+  return { ok: true };
+}
+function inspectExpectedRouteMatches(routes) {
+  const mismatched = [];
+  const failures = [];
+  for (const route of routes) {
+    const result = inspectExpectedRouteMatch(route);
+    if (!result.ok) {
+      mismatched.push(...result.routes);
+      failures.push(result.details);
+    }
+  }
+  return mismatched.length === 0 ? { ok: true } : {
+    ok: false,
+    routes: mismatched,
+    details: failures.join("; ")
+  };
+}
+async function waitForExpectedRouteMatches(routes, timeoutMs, pollIntervalMs) {
+  const deadline = Date.now() + timeoutMs;
+  let result;
+  do {
+    result = inspectExpectedRouteMatches(routes);
+    if (result.ok) return result;
+    if (Date.now() < deadline) {
+      await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())));
+    }
+  } while (Date.now() < deadline);
+  return result;
+}
 function inspectExpectedRoutes(routes, expectation) {
   const mismatched = [];
   const failures = [];
@@ -9857,6 +10104,10 @@ async function ensureTraefikRouteExpectation(routes, expectation, options) {
     pollIntervalMs
   );
   if (initial.ok) return { restarted: false };
+  if (options.allowRestart === false)
+    throw new Error(
+      "Traefik routes did not reload; shared router restart is disabled for this operation."
+    );
   import_node_fs24.default.mkdirSync(DEVROUTER_HOME, { recursive: true });
   return withFileLock(
     ROUTER_RELOAD_LOCK_FILE,
@@ -9887,10 +10138,21 @@ async function ensureTraefikRouteExpectation(routes, expectation, options) {
 async function ensureTraefikRoutesLoaded(routes, options = {}) {
   return ensureTraefikRouteExpectation(routes, "loaded", options);
 }
+async function ensureTraefikRoutesMatch(routes, options = {}) {
+  if (routes.length === 0) return;
+  const timeoutMs = options.initialTimeoutMs ?? options.recoveryTimeoutMs ?? DEFAULT_INITIAL_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const result = await waitForExpectedRouteMatches(routes, timeoutMs, pollIntervalMs);
+  if (!result.ok) {
+    throw new Error(
+      `Traefik route configuration did not match rendered routes: ${result.routes.join(", ")} (${result.details})`
+    );
+  }
+}
 async function ensureTraefikRoutesRemoved(routes, options = {}) {
   return ensureTraefikRouteExpectation(routes, "removed", options);
 }
-var import_node_child_process20, import_node_fs24, import_node_path25, ROUTER_API_BASE, ROUTER_RELOAD_LOCK_FILE, DEFAULT_INITIAL_TIMEOUT_MS, DEFAULT_RECOVERY_TIMEOUT_MS, DEFAULT_POLL_INTERVAL_MS, ROUTER_API_PAGE_SIZE;
+var import_node_child_process20, import_node_fs24, import_node_path25, ROUTER_API_BASE, ROUTER_RELOAD_LOCK_FILE, ROUTER_API_REQUEST_TIMEOUT_SECONDS, DEFAULT_INITIAL_TIMEOUT_MS, DEFAULT_RECOVERY_TIMEOUT_MS, DEFAULT_POLL_INTERVAL_MS, ROUTER_API_PAGE_SIZE;
 var init_traefik_route_health = __esm({
   "src/core/traefik-route-health.ts"() {
     "use strict";
@@ -9902,6 +10164,7 @@ var init_traefik_route_health = __esm({
     init_router();
     ROUTER_API_BASE = "http://127.0.0.1:8080/api";
     ROUTER_RELOAD_LOCK_FILE = import_node_path25.default.join(DEVROUTER_HOME, "router-reload.lock");
+    ROUTER_API_REQUEST_TIMEOUT_SECONDS = "2";
     DEFAULT_INITIAL_TIMEOUT_MS = 3e3;
     DEFAULT_RECOVERY_TIMEOUT_MS = 1e4;
     DEFAULT_POLL_INTERVAL_MS = 250;
@@ -10165,7 +10428,7 @@ function validateWorkspaceContainers(containers, options) {
   if (options.target.kind === "linked") {
     assertOverlay(appContainer, options.repoPath);
   }
-  assertReady(appContainer, "Workspace app");
+  if (!options.allowStopped) assertReady(appContainer, "Workspace app");
   if (options.target.kind === "linked") {
     const gitCommonDir = options.target.gitCommonDir;
     const gitMount = appContainer.mounts.find(
@@ -10317,6 +10580,142 @@ function resolveLinkedTarget(repoPath) {
     gitCommonDir: resolveGitCommonDir(repoPath)
   };
 }
+function resolveRepairTarget(repoPath, linked) {
+  const workspace = linked ? readPersistedWorkspace(repoPath) : void 0;
+  if (linked && !workspace) throw new Error("Repair requires an existing workspace identity.");
+  const state = readManagedRuntimeState(repoPath, workspace);
+  if (state?.status !== "degraded") {
+    throw new Error("Repair requires a persisted degraded managed runtime.");
+  }
+  resetWorkspaceRuntimeCaches();
+  const snapshots = getWorkspaceRegistrySnapshots();
+  if (snapshots.unavailable.length) throw new Error("Repair cannot read every provider registry.");
+  const matches = [...snapshots.devpod ?? [], ...snapshots.devsy ?? []].filter(
+    (entry) => entry.id === state.devpodId || sameWorkspacePath(entry.source.localFolder, repoPath)
+  );
+  if (matches.length !== 1 || matches[0].id !== state.devpodId || !sameWorkspacePath(matches[0].source.localFolder, repoPath)) {
+    throw new Error("Repair requires one exact retained provider registration.");
+  }
+  const selected = snapshots[resolveWorkspaceRuntimeOrDefault(repoPath)] ?? [];
+  if (!selected.some(
+    (entry) => entry.id === state.devpodId && sameWorkspacePath(entry.source.localFolder, repoPath)
+  )) {
+    throw new Error("Repair provider selection does not own the retained workspace.");
+  }
+  if (workspace) {
+    const owner = readWorkspaceOwnership(repoPath, workspace);
+    if (!owner || owner.devpodId !== state.devpodId || !sameWorkspacePath(owner.worktreePath, repoPath)) {
+      throw new Error("Repair requires the existing exact workspace owner record.");
+    }
+    return {
+      kind: "linked",
+      workspace,
+      devpodId: state.devpodId,
+      hadExactDevpod: true,
+      gitCommonDir: resolveGitCommonDir(repoPath)
+    };
+  }
+  return { kind: "primary", devpodId: state.devpodId, hadExactDevpod: true };
+}
+function assertRepairBaseline(options) {
+  const { repoPath, target, state, plan, config, profile, processes } = options;
+  const desired = {
+    apps: proxyAppsFromConfig(config).map((app) => app.name),
+    services: plan.desiredProfileServices,
+    processes
+  };
+  if (state.profile !== profile || state.sourceConfigSha256 !== plan.sourceConfigSha256 || state.effectiveConfigSha256 !== plan.effectiveConfigSha256 || Object.keys(desired).some((key) => {
+    const resource = key;
+    return JSON.stringify([...desired[resource]].sort()) !== JSON.stringify([...state.desired[resource]].sort());
+  }) || inspectManagedDevcontainerGeneratedConfig(plan).status !== "valid") {
+    throw new Error(
+      "Repair requires the recorded profile, resource sets, and unchanged managed configuration."
+    );
+  }
+  if (options.routes.some(
+    (route) => route.workspace !== target.workspace || !desired.apps.includes(route.name)
+  )) {
+    throw new Error("Repair refuses unexpected active routes.");
+  }
+  const containers = inspectWorkspaceContainers();
+  const retained = plan.desiredServices.map((service) => {
+    const matches = exactWorkspaceServiceContainers(
+      containers,
+      repoPath,
+      state.composeProject,
+      service,
+      plan.composeFiles
+    );
+    if (matches.length !== 1)
+      throw new Error(`Repair requires one retained container for '${service}'.`);
+    return matches[0];
+  });
+  const primary = retained.find(
+    (c) => c.labels["com.docker.compose.service"] === plan.primaryService
+  );
+  if (!primary) throw new Error("Repair cannot identify the retained primary container.");
+  if (!primary.state.Running && (options.routes.length > 0 || containers.some(
+    (container) => container.labels["com.docker.compose.project"] === state.composeProject && container.state.Running !== false
+  ))) {
+    throw new Error(
+      "Repair of a stopped primary requires all exact project containers stopped and no checkout routes."
+    );
+  }
+  validateWorkspaceContainers(containers, {
+    repoPath,
+    target,
+    upstreamHosts: [],
+    allowStopped: !primary.state.Running
+  });
+  for (const container of containers) {
+    if (container.labels["com.docker.compose.project"] !== state.composeProject) continue;
+    const service = container.labels["com.docker.compose.service"] ?? "";
+    if (typeof container.state.Running !== "boolean" || !hasExactComposeIdentity(container, {
+      repoPath,
+      service,
+      composeProject: state.composeProject,
+      composeFiles: plan.composeFiles
+    }) || container.state.Running && !plan.desiredServices.includes(service)) {
+      throw new Error("Repair refuses foreign or unexpected active Compose resources.");
+    }
+  }
+  const workspacePath = primary.mounts.find(
+    (m) => m.Type === "bind" && sameWorkspacePath(m.Source, repoPath)
+  )?.Destination;
+  if (!workspacePath) throw new Error("Repair cannot prove the primary workspace mount.");
+  for (const name of primary.state.Running ? config.managedRuntime?.processes ?? [] : []) {
+    if (!processes.includes(name) && runManagedProcessAction({
+      container: { id: primary.id, workspacePath },
+      name,
+      action: "status",
+      quiet: true
+    }) !== "stopped") {
+      throw new Error(`Repair refuses unexpected or unproven process '${name}'.`);
+    }
+  }
+  assertManagedContainerConfigUnchanged({
+    plan,
+    containers: retained,
+    workspace: options.workspace
+  });
+  return retained;
+}
+function assertRetainedRepairContainers(repoPath, plan, retained) {
+  const current = inspectWorkspaceContainers();
+  for (const previous of retained) {
+    const service = previous.labels["com.docker.compose.service"] ?? "";
+    const matches = exactWorkspaceServiceContainers(
+      current,
+      repoPath,
+      previous.labels["com.docker.compose.project"] ?? "",
+      service,
+      plan.composeFiles
+    );
+    if (matches.length !== 1 || matches[0].id !== previous.id) {
+      throw new Error(`Repair lost retained container identity for '${service}'.`);
+    }
+  }
+}
 function resolvePrimaryTarget(repoPath) {
   const existingDevpod = selectDevpodWorkspace(listDevpodWorkspaces(repoPath), repoPath);
   return {
@@ -10358,7 +10757,9 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       );
     }
   }
-  return withWorkspaceLifecycleLock(repoPath, async () => {
+  const ensureLocked = async () => {
+    let repairMutationStarted = false;
+    let retainedRepairContainers = [];
     let environmentStarted = false;
     let managedPlan;
     let previousManagedState;
@@ -10376,10 +10777,11 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
     let firstTransitionBaseline;
     const routeLoadOptions = {
       initialTimeoutMs: Math.min(options.httpTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS, 3e3),
-      recoveryTimeoutMs: Math.min(options.httpTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS, 1e4)
+      recoveryTimeoutMs: Math.min(options.httpTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS, 1e4),
+      ...options.repair ? { allowRestart: false } : {}
     };
     try {
-      const target = linked ? resolveLinkedTarget(repoPath) : resolvePrimaryTarget(repoPath);
+      const target = options.repair ? resolveRepairTarget(repoPath, linked) : linked ? resolveLinkedTarget(repoPath) : resolvePrimaryTarget(repoPath);
       let devpodId = target.devpodId;
       if (target.kind === "linked") {
         const overlayPath = import_node_path26.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
@@ -10389,12 +10791,16 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       }
       const managedPostStart = resolveManagedPostStartPlan(repoPath);
       managedPostStartPlan = managedPostStart;
+      if (options.repair)
+        previousManagedState = readManagedRuntimeState(repoPath, target.workspace);
       const runtime = loadRuntimeConfig(
         repoPath,
         target.kind === "primary" ? "" : target.workspace,
-        options.profile
+        options.profile ?? (options.repair ? previousManagedState?.profile : void 0)
       );
       const managedRuntime = runtime.config.managedRuntime;
+      if (options.repair && !managedRuntime)
+        throw new Error("Repair requires managedRuntime configuration.");
       previousRoutes = listHostRouteState().filter(
         (route) => sameWorkspacePath(route.repoPath, repoPath)
       );
@@ -10403,12 +10809,12 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       const desiredProcesses = managedRuntime ? desiredManagedProcesses(managedRuntime, runtime.resolvedProfile) : [];
       if (managedRuntime) {
         previousManagedState = readManagedRuntimeState(repoPath, target.workspace);
-        if (previousManagedState && !hasExactManagedComposeProject(repoPath, previousManagedState)) {
+        if (!options.repair && previousManagedState && !hasExactManagedComposeProject(repoPath, previousManagedState)) {
           previousManagedState = void 0;
         }
-        if (previousManagedState?.status === "degraded") {
+        if (!options.repair && previousManagedState?.status === "degraded") {
           throw new Error(
-            "Managed runtime state is degraded; refusing a new profile transition until drift is repaired."
+            "Managed runtime state is degraded; refusing a new profile transition until drift is repaired. Inspect status, then use ensure --repair for the recorded profile."
           );
         }
         if (previousManagedState && previousManagedState.devpodId !== target.devpodId) {
@@ -10462,7 +10868,20 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           );
         }
       }
-      if (managedPlan) {
+      if (options.repair && managedPlan && previousManagedState) {
+        retainedRepairContainers = assertRepairBaseline({
+          repoPath,
+          target,
+          state: previousManagedState,
+          plan: managedPlan,
+          config: runtime.config,
+          profile: runtime.profile,
+          processes: desiredProcesses,
+          routes: previousRoutes,
+          workspace: managedWorkspaceEnv
+        });
+      }
+      if (managedPlan && !options.repair) {
         writeManagedDevcontainerConfig(managedPlan);
         managedConfigWritten = true;
       }
@@ -10498,7 +10917,7 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       let recreated = false;
       let container;
       try {
-        await startAndProveAttachment();
+        if (!options.repair) await startAndProveAttachment();
       } catch (error) {
         if (managedPlan || !target.hadExactDevpod) {
           throw error;
@@ -10508,7 +10927,45 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       }
       if (!container) {
         try {
-          container = await preflight(0);
+          if (options.repair && managedPlan && previousManagedState) {
+            assertRetainedRepairContainers(repoPath, managedPlan, retainedRepairContainers);
+            const primaryService = managedPlan.primaryService;
+            const primary = retainedRepairContainers.find(
+              (entry) => entry.labels["com.docker.compose.service"] === primaryService
+            );
+            if (!primary) throw new Error("Repair lost its retained primary container.");
+            const stopped = retainedRepairContainers.filter((entry) => !entry.state.Running);
+            for (const entry of stopped) {
+              if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(entry.id))
+                throw new Error("Repair found an invalid retained container ID.");
+            }
+            if (stopped.length > 0) {
+              repairMutationStarted = true;
+              transitionPhase = "service-start";
+              const result = (0, import_node_child_process21.spawnSync)("docker", ["start", ...stopped.map((entry) => entry.id)], {
+                encoding: "utf-8",
+                timeout: DEFAULT_READINESS_TIMEOUT_MS,
+                stdio: options.quiet ? ["ignore", 2, "inherit"] : "inherit"
+              });
+              if (result.status !== 0)
+                throw new Error("Could not start retained repair containers.");
+              assertRetainedRepairContainers(repoPath, managedPlan, retainedRepairContainers);
+            }
+            await waitForManagedServices(
+              managedPlan,
+              repoPath,
+              previousManagedState.composeProject,
+              managedPlan.desiredServices,
+              primary.id,
+              options.containerTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS
+            );
+          }
+          container = options.repair ? await waitForContainerPreflight(
+            repoPath,
+            currentTarget(),
+            [],
+            options.containerTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS
+          ) : await preflight(0);
         } catch (error) {
           if (managedPlan || !target.hadExactDevpod) {
             throw error;
@@ -10549,13 +11006,18 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           }
           if (!matches[0]?.state.Running) missingServices.push(service);
         }
-        startExactManagedServices({
-          plan: managedPlan,
-          composeProject: managedComposeProject,
-          services: missingServices,
-          quiet: options.quiet,
-          workspace: managedWorkspaceEnv
-        });
+        if (options.repair) {
+          assertRetainedRepairContainers(repoPath, managedPlan, retainedRepairContainers);
+          repairMutationStarted = true;
+        }
+        if (!options.repair)
+          startExactManagedServices({
+            plan: managedPlan,
+            composeProject: managedComposeProject,
+            services: missingServices,
+            quiet: options.quiet,
+            workspace: managedWorkspaceEnv
+          });
         await waitForManagedServices(
           managedPlan,
           repoPath,
@@ -10567,6 +11029,8 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         container = await preflight(options.containerTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS);
         managedContainer = container;
       }
+      if (options.repair && managedPlan)
+        assertRetainedRepairContainers(repoPath, managedPlan, retainedRepairContainers);
       transitionPhase = "process-start";
       runManagedPostStart({
         plan: managedPostStart,
@@ -10580,6 +11044,17 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         const desiredProcessSet = new Set(desiredProcesses);
         for (const process2 of processRegistry) {
           if (desiredProcessSet.has(process2)) continue;
+          if (options.repair) {
+            if (runManagedProcessAction({
+              container,
+              name: process2,
+              action: "status",
+              quiet: options.quiet
+            }) !== "stopped") {
+              throw new Error(`Repair found unexpected process '${process2}' after adapter replay.`);
+            }
+            continue;
+          }
           runManagedProcessAction({
             container,
             name: process2,
@@ -10599,7 +11074,8 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           }
         }
         transitionPhase = "service-stop";
-        stopDroppedManagedServices(managedPlan, repoPath, managedComposeProject);
+        if (!options.repair)
+          stopDroppedManagedServices(managedPlan, repoPath, managedComposeProject);
         assertDroppedManagedServicesStopped(managedPlan, repoPath, managedComposeProject);
         await waitForManagedServices(
           managedPlan,
@@ -10614,11 +11090,13 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       const publication = await replacePublishedProxyRoutes(
         repoPath,
         runtime.config,
-        target.workspace
+        target.workspace,
+        options.repair ? { prepareInfrastructure: false } : void 0
       );
       candidateRoutes = publication.routes;
       candidateRoutesPublished = true;
-      await ensureTraefikRoutesLoaded(publication.routes, routeLoadOptions);
+      if (options.repair) await ensureTraefikRoutesMatch(publication.routes, routeLoadOptions);
+      else await ensureTraefikRoutesLoaded(publication.routes, routeLoadOptions);
       await ensureTraefikRoutesRemoved(
         removedRoutesForReplacement(previousRoutes.map(routeInputFromState), publication.routes),
         routeLoadOptions
@@ -10665,8 +11143,9 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       if (!devpodId) {
         throw new Error(`DevPod id for '${repoPath}' was not resolved after startup.`);
       }
+      let candidateState;
       if (managedPlan && managedComposeProject) {
-        writeManagedRuntimeState({
+        candidateState = {
           version: 1,
           repoPath,
           ...target.workspace !== void 0 ? { workspace: target.workspace } : {},
@@ -10682,15 +11161,24 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           effectiveConfigSha256: managedPlan.effectiveConfigSha256,
           status: "ready",
           updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        });
+        };
+        if (!options.repair) writeManagedRuntimeState(candidateState);
       }
       const managedRuntimeStatus = managedPlan ? collectManagedRuntimeStatus({
         repoPath,
         workspace: target.workspace,
         config: runtime.config,
         profile: runtime.profile,
-        resolvedProfile: runtime.resolvedProfile
+        resolvedProfile: runtime.resolvedProfile,
+        ...options.repair ? { candidateState } : {}
       }) : void 0;
+      if (options.repair && candidateState && managedPlan) {
+        assertRetainedRepairContainers(repoPath, managedPlan, retainedRepairContainers);
+        resolveRepairTarget(repoPath, linked);
+        if (managedRuntimeStatus?.status !== "ready")
+          throw new Error("Repaired candidate runtime did not pass final readiness validation.");
+        writeManagedRuntimeState(candidateState);
+      }
       return {
         kind: target.kind,
         repoPath,
@@ -10703,6 +11191,37 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         ...managedRuntimeStatus ? { managedRuntime: managedRuntimeStatus } : {}
       };
     } catch (error) {
+      if (options.repair && !repairMutationStarted) throw error;
+      if (options.repair && repairMutationStarted && previousManagedState && managedPlan) {
+        const failures = [];
+        if (transitionPhase === "route-publication") {
+          try {
+            const currentRoutes = listHostRouteState().filter((route) => sameWorkspacePath(route.repoPath, repoPath)).map(routeInputFromState);
+            const rollbackRoutes = previousRoutes.map(routeInputFromState);
+            replaceHostRoutesForRepo(repoPath, rollbackRoutes);
+            await ensureTraefikRoutesMatch(rollbackRoutes, routeLoadOptions);
+            await ensureTraefikRoutesRemoved(
+              removedRoutesForReplacement(currentRoutes, rollbackRoutes),
+              routeLoadOptions
+            );
+          } catch (rollbackError) {
+            failures.push(
+              `routes: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+            );
+          }
+        }
+        try {
+          markManagedRuntimeDegraded(previousManagedState, transitionPhase);
+        } catch (stateError) {
+          failures.push(
+            `state: ${stateError instanceof Error ? stateError.message : String(stateError)}`
+          );
+        }
+        const original = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `${original} Repair failed; owned resources may remain running.${failures.length ? ` Recovery errors: ${failures.join("; ")}.` : " State remains degraded."}`
+        );
+      }
       if (managedPlan && managedContainer && managedComposeProject) {
         const rollbackErrors = [];
         const failedPhase = transitionPhase;
@@ -10904,6 +11423,22 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       }
       throw error;
     }
+  };
+  return withWorkspaceLifecycleLock(repoPath, async () => {
+    if (!options.repair) return ensureLocked();
+    const runtime = resolveWorkspaceRuntimeOrDefault(repoPath);
+    import_node_fs25.default.mkdirSync(DEVROUTER_HOME, { recursive: true });
+    return withFileLock(
+      import_node_path26.default.join(DEVROUTER_HOME, `${runtime}-mutation.lock`),
+      {
+        activity: "Managed runtime repair",
+        target: repoPath,
+        fair: true,
+        waitMs: 18e5,
+        onWait: createStderrWaitReporter("Managed runtime repair", repoPath)
+      },
+      ensureLocked
+    );
   });
 }
 var import_node_child_process21, import_node_fs25, import_node_path26, DEVCONTAINER_OVERLAY, DEFAULT_READINESS_TIMEOUT_MS, POLL_INTERVAL_MS;
@@ -10917,6 +11452,7 @@ var init_workspace_ensure = __esm({
     init_devpod_environment();
     init_devpod_mutation();
     init_devpod_workspaces();
+    init_file_lock();
     init_host_routes();
     init_http_route_probe();
     init_managed_post_start();
@@ -10964,7 +11500,8 @@ async function runEnsureCommand(options) {
   const result = await workspaceEnsure(repoPath, {
     open: options.open,
     quiet: Boolean(options.json),
-    profile: options.profile
+    profile: options.profile,
+    ...options.repair ? { repair: true } : {}
   });
   if (options.json) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}
@@ -13268,11 +13805,11 @@ var init_profile_resolution = __esm({
 function fail(message) {
   throw new Error(message);
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function requireRecord(value, label) {
-  if (!isRecord2(value)) fail(`${label} must be a mapping.`);
+  if (!isRecord3(value)) fail(`${label} must be a mapping.`);
   return value;
 }
 function requireExactKeys(value, allowed, label) {
@@ -15052,7 +15589,7 @@ var init_workspace_consumption = __esm({
 });
 
 // src/core/workspace-cleanup.ts
-function isRecord3(value) {
+function isRecord4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isSha(value) {
@@ -15196,14 +15733,14 @@ function parseGitHubChanges(value, project, branch) {
   if (!Array.isArray(value)) return void 0;
   const changes = [];
   for (const item of value) {
-    if (!isRecord3(item)) return void 0;
-    const repository = isRecord3(item.repository) ? item.repository.nameWithOwner : void 0;
-    const headRepository = isRecord3(item.headRepository) ? item.headRepository.nameWithOwner : void 0;
+    if (!isRecord4(item)) return void 0;
+    const repository = isRecord4(item.repository) ? item.repository.nameWithOwner : void 0;
+    const headRepository = isRecord4(item.headRepository) ? item.headRepository.nameWithOwner : void 0;
     if (repository !== project || headRepository !== project || item.headRefName !== branch || !isSha(item.headRefOid) || typeof item.baseRefName !== "string") {
       continue;
     }
     const merged = item.state === "MERGED" && validTimestamp(item.mergedAt);
-    const mergeCommit = isRecord3(item.mergeCommit) && isSha(item.mergeCommit.oid) ? item.mergeCommit.oid : void 0;
+    const mergeCommit = isRecord4(item.mergeCommit) && isSha(item.mergeCommit.oid) ? item.mergeCommit.oid : void 0;
     const baseSha = isSha(item.baseRefOid) ? item.baseRefOid : void 0;
     changes.push({
       sourceBranch: branch,
@@ -15220,14 +15757,14 @@ function parseGitLabChanges(value, _project, branch) {
   if (!Array.isArray(value)) return void 0;
   const changes = [];
   for (const item of value) {
-    if (!isRecord3(item)) return void 0;
+    if (!isRecord4(item)) return void 0;
     const sourceProjectId = item.source_project_id;
     const targetProjectId = item.target_project_id;
     const sameProject = typeof sourceProjectId === "number" && typeof targetProjectId === "number" && sourceProjectId === targetProjectId;
     if (!sameProject || item.source_branch !== branch || !isSha(item.sha) || typeof item.target_branch !== "string") {
       continue;
     }
-    const diffRefs = isRecord3(item.diff_refs) ? item.diff_refs : void 0;
+    const diffRefs = isRecord4(item.diff_refs) ? item.diff_refs : void 0;
     const mergeCommitSha = isSha(item.merge_commit_sha) ? item.merge_commit_sha : void 0;
     const baseSha = diffRefs && isSha(diffRefs.base_sha) ? diffRefs.base_sha : void 0;
     changes.push({
@@ -15901,7 +16438,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.51" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.52" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {
@@ -15956,13 +16493,14 @@ program.command("up").description("Ensure devnet and start shared Traefik (reser
     await runUpCommand2();
   })
 );
-program.command("ensure").description("Start and prove a primary or linked checkout's environment and routes").argument("[path]", "Git checkout path (defaults to current directory)").option("--profile <name>", "Start only this profile's apps/dependencies from .devrouter.yml").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
+program.command("ensure").description("Start and prove a primary or linked checkout's environment and routes").argument("[path]", "Git checkout path (defaults to current directory)").option("--profile <name>", "Start only this profile's apps/dependencies from .devrouter.yml").option("--repair", "Repair a degraded managed runtime from its recorded profile").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
   withErrorHandling(async (repoPath, _options, command) => {
     const options = command.opts();
     const { runEnsureCommand: runEnsureCommand2 } = await Promise.resolve().then(() => (init_ensure(), ensure_exports));
     await runEnsureCommand2({
       path: repoPath,
       profile: options.profile,
+      repair: options.repair,
       open: Boolean(options.open),
       json: Boolean(options.json)
     });
@@ -16184,7 +16722,7 @@ workspaceCommand2.command("up").description(
 );
 workspaceCommand2.command("ensure").description(
   "Start and prove a primary or linked checkout's workspace runtime, upstreams, and routes"
-).argument("[path]", "Git checkout path (defaults to current directory)").option("--profile <name>", "Start only this profile's apps/dependencies from .devrouter.yml").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
+).argument("[path]", "Git checkout path (defaults to current directory)").option("--profile <name>", "Start only this profile's apps/dependencies from .devrouter.yml").option("--repair", "Repair a degraded managed runtime from its recorded profile").option("--open", "Open HTTP routes after readiness succeeds").option("--json", "Output JSON").action(
   withErrorHandling(
     async (worktreePath, _options, command) => {
       const options = command.opts();
@@ -16192,6 +16730,7 @@ workspaceCommand2.command("ensure").description(
       await runEnsureCommand2({
         path: worktreePath,
         profile: options.profile,
+        repair: options.repair,
         open: Boolean(options.open),
         json: Boolean(options.json)
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "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.52.md

@@ -0,0 +1,34 @@
+# Upgrade to devrouter 0.0.52
+
+Managed process ownership now handles large environments correctly. Explicit
+`ensure --repair` recovers a retained degraded runtime without deleting its data
+or invoking provider bootstrap. Ordinary `ensure` retains its degraded-state guard.
+
+## Task
+
+1. Install the published CLI with `npm install -g @devrouter/cli@0.0.52`.
+2. Bump `devrouter.version` in the consumer `.devrouter.yml` to `0.0.52`.
+3. For an approved exact workspace recovery, inspect status and run
+   `devrouter ensure <checkout> --repair --json`. Omit the profile to reuse the
+   recorded profile. Preserve required non-secret Compose interpolation settings.
+4. Stop at ownership or configuration drift. Repair requires retained containers;
+   it never creates missing resources or changes the recorded profile.
+
+## Validation
+
+Verify installed/configured versions with `devrouter -V --repo <checkout>`.
+Repair accepts a stopped primary only with every project container explicitly
+stopped and no checkout routes. It starts retained IDs, including their existing
+entrypoints, then replays the current repository adapter. Owned processes may
+restart when fingerprints change. Failure can leave owned resources running.
+
+Require zero command exit status, ready services/processes, exact active route
+rules and targets, and no managed drift. Check the application separately.
+No live recovery is implied by installing the CLI. No schema migration or manual
+state-file edit is required.
+
+## Report
+
+Report installed/configured versions, exact checkout/profile, repair exit status,
+managed state, application check, and remaining blockers. Distinguish source
+checks from live runtime proof. Data deletion remains a separate explicit action.