@devrouter/cli 0.0.50 → 0.0.52

package/dist/devrouter.js

@@ -50,6 +50,7 @@ function buildDevrouterSection() {
     "- `devrouter app ls --repo .`",
     "- Primary or linked devcontainer checkout: `devrouter ensure . --json`",
     "- Managed selective profile: `devrouter ensure . --profile <name> --json`",
+    "- Side-effect-free automation: `devrouter profile resolve --repo . --profile <name> --json`; add `profile plan --contract <repo-relative-yaml>` when the repository needs literal bindings.",
     "- Host/docker runtime app only: `devrouter app run <host-app> --repo . --yes`",
     "- `devrouter ls`",
     "- Managed devcontainer source configs with `postCreateCommand` and a managed post-start adapter must set `waitFor` exactly to `postCreateCommand` or `postStartCommand`; generated managed configs preserve lifecycle fields and change only `runServices`.",
@@ -300,6 +301,27 @@ profiles:
   selective configuration preserves lifecycle fields and changes only
   \`runServices\`.
 
+## Automation profile plans
+
+Use \`devrouter profile resolve --json\` when automation only needs exact selected
+resources. Use \`devrouter profile plan\` when a repository-owned contract must
+bind selected app names to build arguments, readiness URLs, or other literals:
+
+\`\`\`bash
+devrouter profile plan --repo . --profile <selection> \\
+  --contract <repo-relative-yaml> --output <plan.json> --json
+\`\`\`
+
+The version-1 contract is separate from \`.devrouter.yml\`. It maps every allowed
+app to named non-empty string arrays, constrains dependencies and managed
+services to allowed sets, and requires an exact managed-process set. All
+resource names must exist in \`.devrouter.yml\`. The path must be a regular,
+non-symlink file inside the repository. Devrouter emits canonical, deduplicated
+literal arrays and atomically writes mode \`0600\`; it never interprets binding
+names, expands values, or runs a shell or runtime. Consumers validate expected
+keys and pass values as literal data. Keep separate contracts for workloads
+with different exact process policies.
+
 ## Env var injection
 
 When a host app depends on a TCP Docker service, \`devrouter app run\` and \`devrouter app exec\` inject per-dep deterministic vars (where \`{PREFIX} = dep.name.toUpperCase().replace(/-/g, "_")\`):
@@ -378,8 +400,9 @@ 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
 - \`devrouter exec [path] -- <command...>\`: literal one-shot command inside the exact running workspace runtime
 - \`devrouter up\` / \`devrouter down\`: start/stop shared Traefik router
@@ -402,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
@@ -2668,7 +2691,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.50" : "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(
@@ -3153,6 +3176,8 @@ function buildOnboardingPrompt(options = {}) {
     "- managedRuntime (optional) registers devcontainer baseServices, profileServices, and managed process markers",
     "- managed profiles may add devcontainerServices and processes independently; with managedRuntime, apps may be omitted for a route-free capability profile",
     "- an omitted optional managed dimension selects nothing; use `*` or a full profile to select every registered service/process; baseServices and the primary service are always retained",
+    "- automation may use a separate strict version-1 contract with `devrouter profile plan`; the contract maps apps to named literal arrays, constrains dependencies and services to allowed registries, requires an exact managed-process set, and remains repository-owned",
+    "- profile plan values are data: Devrouter never interprets binding names, expands values, runs a shell, or starts/inspects a runtime; consumers validate expected keys and pass values literally",
     "- native Dev Container clients continue to use the source configuration's full service set; managed ensure derives an ignored sibling and changes only runServices",
     "",
     "Validation rules to enforce:",
@@ -3248,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",
@@ -3366,13 +3392,17 @@ 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."
       },
       {
         command: "devrouter profile resolve --repo <path> [--profile <selection>] [--json]",
         purpose: "Resolve exact profile resources without starting or inspecting a runtime; fail closed on invalid selections or unknown report schemas."
       },
+      {
+        command: "devrouter profile plan --repo <path> [--profile <selection>] --contract <repo-relative-yaml> [--output <path>] [--json]",
+        purpose: "Validate exact profile resources against a repository-owned contract and emit named literal arrays without interpreting them or touching a runtime."
+      },
       {
         command: "devrouter stop [path] [--delete] [--json]",
         purpose: "Stop the exact checkout workspace runtime and routes; --delete explicitly deletes the ownership-proven runtime without removing the checkout."
@@ -5662,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;
@@ -5682,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",
     [
@@ -5720,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";
@@ -5732,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;
   }
 });
 
@@ -5828,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")}}}'
@@ -6143,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;
   }
@@ -8025,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 {
@@ -8037,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);
@@ -8986,7 +9107,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.50" : "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, {
@@ -9698,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 {
@@ -9740,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" }
@@ -9772,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 = [];
@@ -9828,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,
@@ -9858,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";
@@ -9873,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;
@@ -10136,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(
@@ -10288,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 {
@@ -10329,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;
@@ -10347,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);
@@ -10360,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)
       );
@@ -10374,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) {
@@ -10433,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;
       }
@@ -10469,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;
@@ -10479,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;
@@ -10520,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,
@@ -10538,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,
@@ -10551,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,
@@ -10570,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,
@@ -10585,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
@@ -10636,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 } : {},
@@ -10653,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,
@@ -10674,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;
@@ -10875,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;
@@ -10888,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();
@@ -10935,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)}
@@ -13235,9 +13801,294 @@ var init_profile_resolution = __esm({
   }
 });
 
+// src/core/profile-plan.ts
+function fail(message) {
+  throw new Error(message);
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(value, label) {
+  if (!isRecord3(value)) fail(`${label} must be a mapping.`);
+  return value;
+}
+function requireExactKeys(value, allowed, label) {
+  const allowedSet = new Set(allowed);
+  const unknown = Object.keys(value).filter((key) => !allowedSet.has(key));
+  if (unknown.length > 0) fail(`${label} has unsupported keys: ${unknown.sort().join(", ")}.`);
+  const missing = allowed.filter((key) => !Object.hasOwn(value, key));
+  if (missing.length > 0) fail(`${label} is missing keys: ${missing.join(", ")}.`);
+}
+function requireBoolean(value, label) {
+  if (typeof value !== "boolean") fail(`${label} must be a boolean.`);
+  return value;
+}
+function requireStringList(value, label, options = {}) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    fail(`${label} must be an array of strings.`);
+  }
+  if (options.allowEmpty === false && value.length === 0) fail(`${label} must not be empty.`);
+  for (const entry of value) {
+    if (entry.length === 0) fail(`${label} must not contain empty strings.`);
+    if (entry.length > MAX_LITERAL_LENGTH) {
+      fail(`${label} contains a value longer than ${MAX_LITERAL_LENGTH} characters.`);
+    }
+  }
+  if (new Set(value).size !== value.length) fail(`${label} must not contain duplicates.`);
+  return [...value];
+}
+function parseMappings(value) {
+  const input2 = requireRecord(value, "apps.mappings");
+  const entries = Object.entries(input2);
+  if (entries.length > MAX_APP_MAPPINGS) {
+    fail(`apps.mappings exceeds the limit of ${MAX_APP_MAPPINGS}.`);
+  }
+  const mappings = [];
+  const allBindingKeys = /* @__PURE__ */ new Set();
+  let bindingValues = 0;
+  for (const [appName, rawMapping] of entries) {
+    if (appName.length === 0) fail("apps.mappings must not contain an empty app name.");
+    const mapping = requireRecord(rawMapping, `apps.mappings.${appName}`);
+    requireExactKeys(mapping, ["bindings"], `apps.mappings.${appName}`);
+    const rawBindings = requireRecord(mapping.bindings, `apps.mappings.${appName}.bindings`);
+    if (Object.keys(rawBindings).length === 0) {
+      fail(`apps.mappings.${appName}.bindings must not be empty.`);
+    }
+    const bindings = [];
+    for (const [key, rawValues] of Object.entries(rawBindings)) {
+      if (!BINDING_KEY.test(key)) {
+        fail(`binding key '${key}' must match ${BINDING_KEY.source}.`);
+      }
+      const values = requireStringList(rawValues, `apps.mappings.${appName}.bindings.${key}`, {
+        allowEmpty: false
+      });
+      allBindingKeys.add(key);
+      bindingValues += values.length;
+      bindings.push([key, values]);
+    }
+    mappings.push([appName, { bindings: Object.fromEntries(bindings) }]);
+  }
+  if (allBindingKeys.size > MAX_BINDING_KEYS) {
+    fail(`contract exceeds the limit of ${MAX_BINDING_KEYS} binding keys.`);
+  }
+  if (bindingValues > MAX_BINDING_VALUES) {
+    fail(`contract exceeds the limit of ${MAX_BINDING_VALUES} binding values.`);
+  }
+  return Object.fromEntries(mappings);
+}
+function parseProfilePlanContract(source) {
+  const document = (0, import_yaml7.parseDocument)(source, {
+    merge: false,
+    schema: "core",
+    uniqueKeys: true
+  });
+  if (document.errors.length > 0) {
+    fail(`profile plan contract is invalid YAML: ${document.errors[0]?.message}`);
+  }
+  if (document.warnings.length > 0) {
+    fail(`profile plan contract has unsupported YAML: ${document.warnings[0]?.message}`);
+  }
+  let raw;
+  try {
+    raw = document.toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    fail(`profile plan contract could not be converted: ${error.message}`);
+  }
+  const contract = requireRecord(raw, "profile plan contract");
+  requireExactKeys(
+    contract,
+    ["version", "apps", "dependencies", "managedRuntime"],
+    "profile plan contract"
+  );
+  if (contract.version !== CONTRACT_VERSION) {
+    fail(`unsupported profile plan contract version ${String(contract.version)}.`);
+  }
+  const apps = requireRecord(contract.apps, "apps");
+  requireExactKeys(apps, ["requireNonEmpty", "mappings"], "apps");
+  const dependencies = requireRecord(contract.dependencies, "dependencies");
+  requireExactKeys(dependencies, ["allowed"], "dependencies");
+  const managedRuntime = requireRecord(contract.managedRuntime, "managedRuntime");
+  requireExactKeys(managedRuntime, ["services", "processes"], "managedRuntime");
+  const services = requireRecord(managedRuntime.services, "managedRuntime.services");
+  requireExactKeys(services, ["allowed"], "managedRuntime.services");
+  const processes = requireRecord(managedRuntime.processes, "managedRuntime.processes");
+  requireExactKeys(processes, ["exact"], "managedRuntime.processes");
+  return {
+    version: CONTRACT_VERSION,
+    apps: {
+      requireNonEmpty: requireBoolean(apps.requireNonEmpty, "apps.requireNonEmpty"),
+      mappings: parseMappings(apps.mappings)
+    },
+    dependencies: {
+      allowed: requireStringList(dependencies.allowed, "dependencies.allowed")
+    },
+    managedRuntime: {
+      services: {
+        allowed: requireStringList(services.allowed, "managedRuntime.services.allowed")
+      },
+      processes: {
+        exact: requireStringList(processes.exact, "managedRuntime.processes.exact")
+      }
+    }
+  };
+}
+function sortedUnique3(values) {
+  return Array.from(new Set(values)).sort();
+}
+function registryFor(config) {
+  const managedRuntime = config.managedRuntime;
+  return {
+    apps: sortedUnique3(
+      config.apps.filter((app) => app.kind !== "dependency").map((app) => app.name)
+    ),
+    dependencies: sortedUnique3(
+      config.apps.filter((app) => app.kind === "dependency").map((app) => app.name)
+    ),
+    managedServices: sortedUnique3([
+      ...managedRuntime?.devcontainer.baseServices ?? [],
+      ...managedRuntime?.devcontainer.profileServices ?? []
+    ]),
+    managedProcesses: sortedUnique3(managedRuntime?.processes ?? [])
+  };
+}
+function assertKnown(values, registry, label) {
+  const known = new Set(registry);
+  const unknown = values.filter((value) => !known.has(value));
+  if (unknown.length > 0) fail(`${label} contains unknown resources: ${unknown.join(", ")}.`);
+}
+function assertAllowed(selected, allowed, label) {
+  const allowedSet = new Set(allowed);
+  const unsupported = selected.filter((value) => !allowedSet.has(value));
+  if (unsupported.length > 0) {
+    fail(`${label} selects unsupported resources: ${unsupported.join(", ")}.`);
+  }
+}
+function assertExact(selected, expected, label) {
+  const left = sortedUnique3(selected);
+  const right = sortedUnique3(expected);
+  if (left.length !== right.length || left.some((value, index) => value !== right[index])) {
+    fail(`${label} must equal [${right.join(", ")}], received [${left.join(", ")}].`);
+  }
+}
+function buildProfilePlanReport(options) {
+  const { report, contract, registry, contractPath } = options;
+  assertKnown(Object.keys(contract.apps.mappings), registry.apps, "apps.mappings");
+  assertKnown(contract.dependencies.allowed, registry.dependencies, "dependencies.allowed");
+  assertKnown(
+    contract.managedRuntime.services.allowed,
+    registry.managedServices,
+    "managedRuntime.services.allowed"
+  );
+  assertKnown(
+    contract.managedRuntime.processes.exact,
+    registry.managedProcesses,
+    "managedRuntime.processes.exact"
+  );
+  if (contract.apps.requireNonEmpty && report.apps.length === 0) {
+    fail("selected profile must contain at least one app for this contract.");
+  }
+  const unmapped = report.apps.filter((app) => !Object.hasOwn(contract.apps.mappings, app));
+  if (unmapped.length > 0) fail(`selected apps have no contract mapping: ${unmapped.join(", ")}.`);
+  assertAllowed(report.dependencies, contract.dependencies.allowed, "dependencies");
+  assertAllowed(
+    report.managedRuntime.services,
+    contract.managedRuntime.services.allowed,
+    "managedRuntime.services"
+  );
+  assertExact(
+    report.managedRuntime.processes,
+    contract.managedRuntime.processes.exact,
+    "managedRuntime.processes"
+  );
+  const bindingValues = /* @__PURE__ */ new Map();
+  const bindingSeen = /* @__PURE__ */ new Map();
+  for (const app of report.apps) {
+    if (!Object.hasOwn(contract.apps.mappings, app)) {
+      fail(`selected app '${app}' has no contract mapping.`);
+    }
+    const mapping = contract.apps.mappings[app];
+    if (!mapping) fail(`selected app '${app}' has no contract mapping.`);
+    for (const key of Object.keys(mapping.bindings).sort()) {
+      const values = bindingValues.get(key) ?? [];
+      const seen = bindingSeen.get(key) ?? /* @__PURE__ */ new Set();
+      for (const value of mapping.bindings[key] ?? []) {
+        if (seen.has(value)) continue;
+        values.push(value);
+        seen.add(value);
+      }
+      bindingValues.set(key, values);
+      bindingSeen.set(key, seen);
+    }
+  }
+  const bindings = Object.fromEntries(
+    Array.from(bindingValues.keys()).sort().map((key) => [key, bindingValues.get(key) ?? []])
+  );
+  return { ...report, contractPath, bindings };
+}
+function loadContract(repoPath, contractPath) {
+  if (import_node_path31.default.isAbsolute(contractPath)) {
+    fail("profile plan contract path must be relative to the repository.");
+  }
+  const absolutePath = assertPathWithinRepo(contractPath, repoPath, "Profile plan contract");
+  let metadata;
+  try {
+    metadata = import_node_fs30.default.lstatSync(absolutePath);
+  } catch (error) {
+    fail(`could not inspect profile plan contract '${contractPath}': ${error.message}`);
+  }
+  if (metadata.isSymbolicLink() || !metadata.isFile()) {
+    fail(`profile plan contract '${contractPath}' must be a regular file, not a symlink.`);
+  }
+  if (metadata.size > MAX_CONTRACT_BYTES) {
+    fail(`profile plan contract exceeds the ${MAX_CONTRACT_BYTES}-byte limit.`);
+  }
+  const realRepo = import_node_fs30.default.realpathSync(repoPath);
+  const realContract = import_node_fs30.default.realpathSync(absolutePath);
+  assertPathWithinRepo(realContract, realRepo, "Profile plan contract");
+  const source = import_node_fs30.default.readFileSync(absolutePath, "utf-8");
+  if (Buffer.byteLength(source, "utf-8") > MAX_CONTRACT_BYTES) {
+    fail(`profile plan contract exceeds the ${MAX_CONTRACT_BYTES}-byte limit.`);
+  }
+  return {
+    contract: parseProfilePlanContract(source),
+    contractPath: import_node_path31.default.relative(repoPath, absolutePath).split(import_node_path31.default.sep).join("/")
+  };
+}
+function resolveProfilePlan(options) {
+  const repoPath = resolveRepoPath(options.repo);
+  const config = loadRepoConfig(repoPath);
+  const loaded = loadContract(repoPath, options.contract);
+  return buildProfilePlanReport({
+    report: buildProfileResolutionReport(config, repoPath, options.profile),
+    contract: loaded.contract,
+    registry: registryFor(config),
+    contractPath: loaded.contractPath
+  });
+}
+var import_node_fs30, import_node_path31, import_yaml7, CONTRACT_VERSION, MAX_CONTRACT_BYTES, MAX_APP_MAPPINGS, MAX_BINDING_KEYS, MAX_BINDING_VALUES, MAX_LITERAL_LENGTH, BINDING_KEY;
+var init_profile_plan = __esm({
+  "src/core/profile-plan.ts"() {
+    "use strict";
+    import_node_fs30 = __toESM(require("fs"));
+    import_node_path31 = __toESM(require("path"));
+    import_yaml7 = require("yaml");
+    init_paths();
+    init_profile_resolution();
+    init_repo_config();
+    CONTRACT_VERSION = 1;
+    MAX_CONTRACT_BYTES = 1024 * 1024;
+    MAX_APP_MAPPINGS = 256;
+    MAX_BINDING_KEYS = 64;
+    MAX_BINDING_VALUES = 4096;
+    MAX_LITERAL_LENGTH = 4096;
+    BINDING_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+  }
+});
+
 // src/commands/profile.ts
 var profile_exports = {};
 __export(profile_exports, {
+  runProfilePlanCommand: () => runProfilePlanCommand,
   runProfileResolveCommand: () => runProfileResolveCommand
 });
 async function runProfileResolveCommand(options) {
@@ -13248,6 +14099,18 @@ async function runProfileResolveCommand(options) {
   }
   printProfileResolutionSummary(report);
 }
+async function runProfilePlanCommand(options) {
+  const report = resolveProfilePlan(options);
+  if (options.output) {
+    writeFileAtomically(import_node_path32.default.resolve(options.output), `${JSON.stringify(report, null, 2)}
+`);
+  }
+  if (options.json) {
+    printJSON(report);
+    return;
+  }
+  printProfilePlanSummary(report, options.output);
+}
 function renderValues(values) {
   return values.join(", ") || "-";
 }
@@ -13267,10 +14130,25 @@ function printProfileResolutionSummary(report) {
   process.stdout.write(`Managed processes: ${renderValues(report.managedRuntime.processes)}
 `);
 }
+function printProfilePlanSummary(report, output2) {
+  printProfileResolutionSummary(report);
+  process.stdout.write(`Contract: ${report.contractPath}
+`);
+  for (const key of Object.keys(report.bindings).sort()) {
+    process.stdout.write(`Binding ${key}: ${renderValues(report.bindings[key] ?? [])}
+`);
+  }
+  if (output2) process.stdout.write(`Output: ${import_node_path32.default.resolve(output2)}
+`);
+}
+var import_node_path32;
 var init_profile = __esm({
   "src/commands/profile.ts"() {
     "use strict";
+    import_node_path32 = __toESM(require("path"));
+    init_atomic_file();
     init_output();
+    init_profile_plan();
     init_profile_resolution();
   }
 });
@@ -13557,7 +14435,7 @@ function sanitizeRouterId(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function repoHash(repoPath) {
-  return (0, import_node_crypto10.createHash)("sha1").update(import_node_path31.default.resolve(repoPath)).digest("hex").slice(0, 12);
+  return (0, import_node_crypto10.createHash)("sha1").update(import_node_path33.default.resolve(repoPath)).digest("hex").slice(0, 12);
 }
 function asDockerApp(app) {
   return app.runtime === "docker";
@@ -13636,11 +14514,11 @@ function prepareDockerOverlay(repoPath, appName, apps, publishTcpPorts = false)
   if (dockerApps.length === 0) {
     throw new Error("No docker apps selected to prepare compose overlay.");
   }
-  const cachePath = import_node_path31.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
-  import_node_fs30.default.mkdirSync(cachePath, { recursive: true });
-  const overlayPath = import_node_path31.default.join(cachePath, "compose.devrouter.yml");
+  const cachePath = import_node_path33.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
+  import_node_fs31.default.mkdirSync(cachePath, { recursive: true });
+  const overlayPath = import_node_path33.default.join(cachePath, "compose.devrouter.yml");
   const overlayDocument = buildOverlayDocument(dockerApps, publishTcpPorts);
-  import_node_fs30.default.writeFileSync(overlayPath, import_yaml7.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
+  import_node_fs31.default.writeFileSync(overlayPath, import_yaml8.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
   return {
     overlayPath,
     composeFiles: ensureComposeFiles(dockerApps),
@@ -13760,15 +14638,15 @@ function queryMappedPort(repoPath, composeFiles2, overlayPath, service, internal
   const port = Number(match[1]);
   return Number.isInteger(port) && port > 0 ? port : void 0;
 }
-var import_node_child_process27, import_node_crypto10, import_node_fs30, import_node_path31, import_yaml7;
+var import_node_child_process27, import_node_crypto10, import_node_fs31, import_node_path33, import_yaml8;
 var init_docker_run = __esm({
   "src/core/docker-run.ts"() {
     "use strict";
     import_node_child_process27 = require("child_process");
     import_node_crypto10 = require("crypto");
-    import_node_fs30 = __toESM(require("fs"));
-    import_node_path31 = __toESM(require("path"));
-    import_yaml7 = __toESM(require("yaml"));
+    import_node_fs31 = __toESM(require("fs"));
+    import_node_path33 = __toESM(require("path"));
+    import_yaml8 = __toESM(require("yaml"));
     init_docker_error_guidance();
     init_paths();
     init_router();
@@ -14589,13 +15467,13 @@ function measureWorktreeConsumption(worktreePath, options) {
   const startedAt = Date.now();
   let rootStat;
   try {
-    rootStat = import_node_fs31.default.lstatSync(worktreePath);
+    rootStat = import_node_fs32.default.lstatSync(worktreePath);
   } catch (error) {
     return { status: "unknown", reason: describeError(error, worktreePath) };
   }
   let rootEntries;
   try {
-    rootEntries = import_node_fs31.default.readdirSync(worktreePath, { withFileTypes: true });
+    rootEntries = import_node_fs32.default.readdirSync(worktreePath, { withFileTypes: true });
   } catch (error) {
     return { status: "unknown", reason: describeError(error, worktreePath) };
   }
@@ -14621,10 +15499,10 @@ function measureWorktreeConsumption(worktreePath, options) {
         timedOut = true;
         break;
       }
-      const entryPath = import_node_path32.default.join(dirPath, entry.name);
+      const entryPath = import_node_path34.default.join(dirPath, entry.name);
       let entryStat;
       try {
-        entryStat = import_node_fs31.default.lstatSync(entryPath);
+        entryStat = import_node_fs32.default.lstatSync(entryPath);
       } catch (error) {
         if (error?.code === "ENOENT") continue;
         unreadableReason = describeIncompleteWalk(error);
@@ -14634,7 +15512,7 @@ function measureWorktreeConsumption(worktreePath, options) {
       if (!entryStat.isDirectory()) continue;
       let childEntries;
       try {
-        childEntries = import_node_fs31.default.readdirSync(entryPath, { withFileTypes: true });
+        childEntries = import_node_fs32.default.readdirSync(entryPath, { withFileTypes: true });
       } catch (error) {
         unreadableReason = describeIncompleteWalk(error);
         break;
@@ -14698,12 +15576,12 @@ function describeError(error, worktreePath) {
   }
   return `could not stat worktree path '${worktreePath}': ${error?.message ?? String(error)}`;
 }
-var import_node_fs31, import_node_path32, DEFAULT_DEADLINE_MS, BLOCK_SIZE_BYTES;
+var import_node_fs32, import_node_path34, DEFAULT_DEADLINE_MS, BLOCK_SIZE_BYTES;
 var init_workspace_consumption = __esm({
   "src/core/workspace-consumption.ts"() {
     "use strict";
-    import_node_fs31 = __toESM(require("fs"));
-    import_node_path32 = __toESM(require("path"));
+    import_node_fs32 = __toESM(require("fs"));
+    import_node_path34 = __toESM(require("path"));
     init_devpod_environment();
     DEFAULT_DEADLINE_MS = 1e4;
     BLOCK_SIZE_BYTES = 512;
@@ -14711,7 +15589,7 @@ var init_workspace_consumption = __esm({
 });
 
 // src/core/workspace-cleanup.ts
-function isRecord2(value) {
+function isRecord4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isSha(value) {
@@ -14804,7 +15682,7 @@ function evaluateWorkspaceActivity(evidence, cutoff) {
 }
 function readGitSnapshot(worktree, commandRunner) {
   const comparablePath = comparableWorkspacePath(worktree.path);
-  if (worktree.prunable || !import_node_fs32.default.existsSync(comparablePath)) {
+  if (worktree.prunable || !import_node_fs33.default.existsSync(comparablePath)) {
     return { worktree, checkout: "missing", head: null, committerDate: null };
   }
   const head = gitOutput(comparablePath, ["rev-parse", "--verify", "HEAD"], commandRunner);
@@ -14855,14 +15733,14 @@ function parseGitHubChanges(value, project, branch) {
   if (!Array.isArray(value)) return void 0;
   const changes = [];
   for (const item of value) {
-    if (!isRecord2(item)) return void 0;
-    const repository = isRecord2(item.repository) ? item.repository.nameWithOwner : void 0;
-    const headRepository = isRecord2(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 = isRecord2(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,
@@ -14879,14 +15757,14 @@ function parseGitLabChanges(value, _project, branch) {
   if (!Array.isArray(value)) return void 0;
   const changes = [];
   for (const item of value) {
-    if (!isRecord2(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 = isRecord2(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({
@@ -15329,7 +16207,7 @@ function buildWorkspaceCleanupReport(options = {}, dependencies = {}) {
       containers = measureContainersFn(worktreePaths);
     } catch (error) {
       const reason = `container measurement failed: ${describeCause(error)}`;
-      containers = new Map(worktreePaths.map((path32) => [path32, unknownContainers(reason)]));
+      containers = new Map(worktreePaths.map((path34) => [path34, unknownContainers(reason)]));
     }
   }
   const rows = records.map((record) => {
@@ -15378,12 +16256,12 @@ function buildWorkspaceCleanupReport(options = {}, dependencies = {}) {
     workspaces: rows
   };
 }
-var import_node_child_process29, import_node_fs32, DEFAULT_INACTIVE_FOR, READ_ONLY_GIT_ENV2, ACTIVITY_SOURCES, defaultCommandRunner;
+var import_node_child_process29, import_node_fs33, DEFAULT_INACTIVE_FOR, READ_ONLY_GIT_ENV2, ACTIVITY_SOURCES, defaultCommandRunner;
 var init_workspace_cleanup = __esm({
   "src/core/workspace-cleanup.ts"() {
     "use strict";
     import_node_child_process29 = require("child_process");
-    import_node_fs32 = __toESM(require("fs"));
+    import_node_fs33 = __toESM(require("fs"));
     init_devpod_workspaces();
     init_host_routes();
     init_repo_config();
@@ -15560,7 +16438,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.50" : "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) => {
@@ -15615,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)
     });
@@ -15728,6 +16607,17 @@ profileCommand.command("resolve").description("Print the exact apps, dependencie
     await runProfileResolveCommand2(options);
   })
 );
+profileCommand.command("plan").description("Validate a profile against a repository contract and emit literal bindings").option("--repo <path>", "Repository path (defaults to current directory)").option(
+  "--profile <name>",
+  "Profile name or comma-separated selection (defaults to configured profile)"
+).requiredOption("--contract <path>", "Repository-relative profile plan contract").option("--output <path>", "Atomically write the JSON plan with mode 0600").option("--json", "Output stable JSON").action(
+  withErrorHandling(
+    async (options) => {
+      const { runProfilePlanCommand: runProfilePlanCommand2 } = await Promise.resolve().then(() => (init_profile(), profile_exports));
+      await runProfilePlanCommand2(options);
+    }
+  )
+);
 var appCommand = program.command("app").description("Manage app entries and runtime actions from `.devrouter.yml`");
 appCommand.command("add").description("Add or update one app definition in `.devrouter.yml`").requiredOption("--name <name>", "App name").option("--kind <kind>", "app or dependency", "app").option("--host <host>", "Hostname ending with .localhost (required for --kind app)").option("--protocol <protocol>", "http or tcp (required for --kind app)").option(
   "--runtime <runtime>",
@@ -15832,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();
@@ -15840,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)
       });