@devrouter/cli 0.0.33 → 0.0.34

package/README.md

@@ -118,11 +118,11 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 The current `devrouter repo devcontainer write` scaffold is intentionally narrow:
 Node + pnpm + Postgres. Other package managers stop with a JSON diagnostic
 instead of writing files that would need manual repair.
-The generated image extracts `devrouter-process` from the exact Devrouter
-package tarball without installing the CLI dependency tree. Its `post-start.sh`
-uses that helper for locked, owned, idempotent background startup. Application
-commands and environment setup remain repository-owned; route readiness remains
-part of `devrouter ensure`.
+The generated image contains no Devrouter package or helper. `devrouter ensure`
+delivers its matching `devrouter-process` helper to the exact running container,
+then invokes the repository-owned `post-start.sh` for locked, owned, idempotent
+background startup. Application commands and environment setup remain
+repository-owned; route readiness remains part of `devrouter ensure`.
 Use `devrouter repo devcontainer verify --json` for read-only PR evidence; add
 `--live --yes` only for compatibility checks. Normal startup uses `ensure`.
 

package/dist/devrouter.js

@@ -43,6 +43,7 @@ function buildDevrouterSection() {
     `\`${DEVROUTER_SKILL_REL_PATH}\``,
     "",
     "Quick validation sequence:",
+    "- Managed devcontainer consumer images contain no devrouter package or helper; `devrouter ensure` delivers the matching helper at runtime.",
     "- `devrouter up`",
     "- `devrouter tls install` (required when repo defines tcp/postgres apps)",
     "- `devrouter app ls --repo .`",
@@ -347,6 +348,7 @@ For host/docker runtime apps only:
 
 ## Runtime behavior notes
 
+- Managed devcontainer images contain no devrouter package or helper. \`devrouter ensure\` delivers its matching process helper to the exact running container and invokes the repository-owned \`.devcontainer/post-start.sh\`; keep \`.devrouter.yml\` as the only consumer-side devrouter version pin.
 - \`devrouter app run\` auto-starts Docker dependencies and waits for health. Host app runs stop auto-started docker deps on exit; docker app runs leave target services running until explicit cleanup.
 - Host-runtime dependencies are NOT auto-started (v1).
 - \`kind=dependency\` entries do not create routes and cannot be direct targets for \`devrouter app run\`, \`devrouter app exec\`, or \`devrouter open\`.
@@ -1794,7 +1796,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.33" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.34" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -2298,7 +2300,7 @@ function buildOnboardingPrompt(options = {}) {
     "- The owner record survives linked-worktree removal and binds the exact path to its DevPod ID. First use reuses an exact-path DevPod or derives a sanitized branch/path identity. Later flags or `DEVROUTER_WORKSPACE` may repeat but cannot rename it. Ambiguous identities fail closed. The primary checkout stays non-namespaced.",
     `- When a workspace is active: hosts auto-namespace (\`web.localhost\` \u2192 \`web.<ws>.localhost\`), \`${WORKSPACE_PLACEHOLDER}\` in \`upstream\` is substituted with the token, and the docker \`router\` key is suffixed per workspace. The runtime config is computed in memory only \u2014 the committed \`.devrouter.yml\` is never rewritten.`,
     "- TLS: namespaced hosts (`web.<ws>.localhost`) are not covered by the `*.localhost` wildcard; devrouter auto-extends the mkcert cert SANs for active hosts when TLS is enabled.",
-    "- Lifecycle: after one-time setup, use `devrouter ensure .` for both primary and linked checkouts; never branch on checkout kind or use live verify as startup. Use `devrouter stop .` for a non-destructive pause and `devrouter exec . -- <command...>` for container commands. `workspace up` creates linked worktrees; destructive down/GC remains ledger-scoped.",
+    "- Lifecycle: after one-time setup, use `devrouter ensure .` for both primary and linked checkouts; never branch on checkout kind or use live verify as startup. Managed consumer images contain no devrouter package/helper: ensure delivers its matching helper at runtime and invokes the repository-owned post-start adapter. Keep `.devrouter.yml` as the only consumer-side version pin. Use `devrouter stop .` for a non-destructive pause and `devrouter exec . -- <command...>` for container commands. `workspace up` creates linked worktrees; destructive down/GC remains ledger-scoped.",
     "- Owner status is `present`, `missing`, `locked`, or `conflict`. Dirty or locked full down fails before side effects. `workspace gc` is a dry run; only `--yes` deletes exact eligible missing resources and records, never Git worktrees, branches, or prune state.",
     "- Workspace commands require Git. Normal config, app, status, and doctor flows work from a `.devrouter.yml` folder without `.git`. Git has no worktree-removal hook; use `workspace ls`, doctor, or dry-run GC after out-of-band removal.",
     "- devcontainer integration: `devcontainer.json` lists the base compose file then `${localEnv:DEVCONTAINER_COMPOSE_OVERLAY:docker-compose.default.yml}`. The default overlay contains `services: {}`; `.devcontainer/docker-compose.devrouter.yml` passes `WORKSPACE` and `DEVROUTER_WORKSPACE` into the app and bind-mounts `${DEVROUTER_GIT_COMMON_DIR}` to the same absolute app-container path. Ensure proves exact DevPod ownership, overlay/Git mounts, env, aliases, health, Git, HTTP route reachability, and unique running TCP upstream ownership before success.",
@@ -3291,6 +3293,19 @@ function buildDevcontainerChecks(repoPath, config, workspace) {
     details: compose.publishedPorts.length > 0 ? compose.publishedPorts.join(", ") : void 0,
     suggestion: compose.parseError || compose.publishedPorts.length > 0 ? "Remove published ports and route services through devnet aliases with devrouter proxy apps." : void 0
   });
+  const dockerfilePath = import_node_path7.default.join(devcontainerDir, "Dockerfile");
+  const dockerfileExists = import_node_fs8.default.existsSync(dockerfilePath);
+  const dockerfile = dockerfileExists ? import_node_fs8.default.readFileSync(dockerfilePath, "utf-8") : "";
+  const devrouterArtifacts = ["@devrouter/cli", "devrouter-process"].filter(
+    (artifact) => dockerfile.includes(artifact)
+  );
+  checks.push({
+    id: "repo.devcontainer.no-devrouter-image-install",
+    level: !dockerfileExists ? "warn" : devrouterArtifacts.length === 0 ? "ok" : "error",
+    summary: !dockerfileExists ? "No .devcontainer/Dockerfile found to inspect for devrouter artifacts." : devrouterArtifacts.length === 0 ? "Consumer image does not install or extract devrouter artifacts." : "Consumer image installs or extracts devrouter artifacts.",
+    details: devrouterArtifacts.length > 0 ? `artifacts=${devrouterArtifacts.join(", ")}` : void 0,
+    suggestion: !dockerfileExists ? "Inspect the consumer image definition and keep devrouter package/helper installation out of it." : devrouterArtifacts.length > 0 ? "Remove devrouter package/helper installation from the Dockerfile; devrouter ensure delivers the helper at runtime." : void 0
+  });
   if (!config) {
     checks.push({
       id: "repo.devcontainer.upstream-alias-match",
@@ -5087,7 +5102,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.33" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.34" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -5760,6 +5775,107 @@ var init_http_route_probe = __esm({
   }
 });
 
+// src/core/managed-post-start.ts
+function commandFailure(result) {
+  return [result.error?.message, result.stderr, result.stdout].filter(Boolean).map((value) => String(value).trim()).filter(Boolean).join("\n");
+}
+function readRegularFile(filePath) {
+  if (!import_node_fs15.default.existsSync(filePath) || !import_node_fs15.default.lstatSync(filePath).isFile()) return void 0;
+  return import_node_fs15.default.readFileSync(filePath, "utf-8");
+}
+function resolveProcessHelperPath() {
+  const candidates = [
+    import_node_path15.default.resolve(__dirname, "..", "bin", "devrouter-process"),
+    import_node_path15.default.resolve(__dirname, "..", "..", "bin", "devrouter-process")
+  ];
+  const helperPath = candidates.find((candidate) => import_node_fs15.default.existsSync(candidate));
+  if (!helperPath) {
+    throw new Error("Could not locate the packaged devrouter-process helper.");
+  }
+  return helperPath;
+}
+function resolveManagedPostStartPlan(repoPath) {
+  const adapterPath = import_node_path15.default.join(repoPath, MANAGED_ADAPTER_PATH);
+  const adapter = readRegularFile(adapterPath);
+  if (adapter === void 0) return { kind: "unmanaged" };
+  if (!adapter.includes(MANAGED_MARKER)) return { kind: "unmanaged" };
+  if (adapter.includes("DEVROUTER_PROCESS_HELPER")) {
+    return { kind: "runtime", adapterPath: MANAGED_ADAPTER_PATH };
+  }
+  const dockerfilePath = import_node_path15.default.join(repoPath, ".devcontainer", "Dockerfile");
+  const devcontainerPath = import_node_path15.default.join(repoPath, ".devcontainer", "devcontainer.json");
+  const dockerfile = readRegularFile(dockerfilePath) ?? "";
+  const devcontainer = readRegularFile(devcontainerPath) ?? "";
+  if (dockerfile.includes("devrouter-process") && devcontainer.includes("postStartCommand")) {
+    return { kind: "legacy" };
+  }
+  throw new Error(
+    "Managed post-start must use DEVROUTER_PROCESS_HELPER before removing the legacy image helper and postStartCommand. Regenerate or migrate the devcontainer, then retry devrouter ensure."
+  );
+}
+function runManagedPostStart(options) {
+  if (options.plan.kind !== "runtime") return;
+  const helper = import_node_fs15.default.readFileSync(resolveProcessHelperPath());
+  const delivered = (0, import_node_child_process11.spawnSync)(
+    "docker",
+    ["exec", "-i", options.container.id, "sh", "-c", DELIVERY_SCRIPT],
+    { input: helper, encoding: "utf-8" }
+  );
+  if (delivered.status !== 0) {
+    const details = commandFailure(delivered);
+    throw new Error(
+      `Could not deliver the managed process helper${details ? `: ${details}` : "."}`
+    );
+  }
+  const started = (0, import_node_child_process11.spawnSync)(
+    "docker",
+    [
+      "exec",
+      "--workdir",
+      options.container.workspacePath,
+      "--env",
+      `DEVROUTER_PROCESS_HELPER=${RUNTIME_HELPER_PATH}`,
+      options.container.id,
+      "bash",
+      options.plan.adapterPath
+    ],
+    { stdio: options.quiet ? ["ignore", 2, "inherit"] : "inherit" }
+  );
+  if (started.status !== 0) {
+    const details = commandFailure(started);
+    throw new Error(`Managed post-start failed${details ? `: ${details}` : "."}`);
+  }
+}
+var import_node_child_process11, import_node_fs15, import_node_path15, MANAGED_MARKER, MANAGED_ADAPTER_PATH, RUNTIME_HELPER_PATH, DELIVERY_SCRIPT;
+var init_managed_post_start = __esm({
+  "src/core/managed-post-start.ts"() {
+    "use strict";
+    import_node_child_process11 = require("child_process");
+    import_node_fs15 = __toESM(require("fs"));
+    import_node_path15 = __toESM(require("path"));
+    MANAGED_MARKER = "devrouter:managed devcontainer";
+    MANAGED_ADAPTER_PATH = ".devcontainer/post-start.sh";
+    RUNTIME_HELPER_PATH = "/tmp/devrouter/bin/devrouter-process";
+    DELIVERY_SCRIPT = `set -eu
+umask 077
+runtime_root=/tmp/devrouter
+runtime_bin="$runtime_root/bin"
+if [ -L "$runtime_root" ] || [ -L "$runtime_bin" ]; then
+  echo "Refusing symlinked devrouter runtime path." >&2
+  exit 1
+fi
+mkdir -p "$runtime_bin"
+chmod 700 "$runtime_root" "$runtime_bin"
+temporary="$(mktemp "$runtime_bin/.devrouter-process.XXXXXX")"
+trap 'rm -f "$temporary"' EXIT
+cat > "$temporary"
+chmod 700 "$temporary"
+mv -f "$temporary" "${RUNTIME_HELPER_PATH}"
+trap - EXIT
+`;
+  }
+});
+
 // src/core/route-publication.ts
 function routedAppsFromConfig(config) {
   return config.apps.filter((app) => app.kind !== "dependency");
@@ -5833,11 +5949,11 @@ var init_route_publication = __esm({
 // src/core/workspace-ensure.ts
 function assertOverlay(container, repoPath) {
   const workingDir = container.labels["com.docker.compose.project.working_dir"];
-  if (!workingDir || !sameWorkspacePath(workingDir, import_node_path15.default.join(repoPath, ".devcontainer"))) {
+  if (!workingDir || !sameWorkspacePath(workingDir, import_node_path16.default.join(repoPath, ".devcontainer"))) {
     throw new Error(`Container '${container.id}' does not belong to the exact worktree.`);
   }
   const configFiles = (container.labels["com.docker.compose.project.config_files"] ?? "").split(",").filter(Boolean);
-  const expectedOverlay = import_node_path15.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
+  const expectedOverlay = import_node_path16.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
   if (!configFiles.some((configFile) => sameWorkspacePath(configFile, expectedOverlay))) {
     throw new Error(`Container '${container.id}' was not started with ${DEVCONTAINER_OVERLAY}.`);
   }
@@ -5911,7 +6027,7 @@ async function waitForContainerPreflight(repoPath, target, upstreamHosts, timeou
         target
       });
       if (target.kind === "linked") {
-        const workspaceEnv = (0, import_node_child_process11.spawnSync)(
+        const workspaceEnv = (0, import_node_child_process12.spawnSync)(
           "docker",
           ["exec", appContainer.id, "printenv", "WORKSPACE"],
           { encoding: "utf-8" }
@@ -5921,7 +6037,7 @@ async function waitForContainerPreflight(repoPath, target, upstreamHosts, timeou
             `Workspace app container must expose WORKSPACE='${target.workspace}' (got '${workspaceEnv.stdout.trim() || "(empty)"}').`
           );
         }
-        const devrouterWorkspaceEnv = (0, import_node_child_process11.spawnSync)(
+        const devrouterWorkspaceEnv = (0, import_node_child_process12.spawnSync)(
           "docker",
           ["exec", appContainer.id, "printenv", "DEVROUTER_WORKSPACE"],
           { encoding: "utf-8" }
@@ -5932,7 +6048,7 @@ async function waitForContainerPreflight(repoPath, target, upstreamHosts, timeou
           );
         }
       }
-      const gitCheck = (0, import_node_child_process11.spawnSync)(
+      const gitCheck = (0, import_node_child_process12.spawnSync)(
         "docker",
         [
           "exec",
@@ -5948,7 +6064,7 @@ async function waitForContainerPreflight(repoPath, target, upstreamHosts, timeou
       if (gitCheck.status !== 0 || !sameWorkspacePath(gitCheck.stdout.trim(), appContainer.workspacePath)) {
         throw new Error("Git does not resolve the expected checkout inside the app container.");
       }
-      return;
+      return appContainer;
     } catch (error) {
       lastError = error;
     }
@@ -6019,7 +6135,7 @@ function resolvePrimaryTarget(repoPath) {
 }
 function isPrimaryCheckout(repoPath) {
   try {
-    return import_node_fs15.default.statSync(import_node_path15.default.join(repoPath, ".git")).isDirectory();
+    return import_node_fs16.default.statSync(import_node_path16.default.join(repoPath, ".git")).isDirectory();
   } catch {
     return false;
   }
@@ -6056,7 +6172,7 @@ function startDevpod(repoPath, target, recreate = false, quiet = false) {
     delete env.DEVROUTER_GIT_COMMON_DIR;
     delete env.DEVCONTAINER_COMPOSE_OVERLAY;
   }
-  const result = (0, import_node_child_process11.spawnSync)("devpod", args, {
+  const result = (0, import_node_child_process12.spawnSync)("devpod", args, {
     stdio: quiet ? ["inherit", 2, "inherit"] : "inherit",
     env
   });
@@ -6075,7 +6191,7 @@ function assertDevpodAttachment(repoPath, expectedId) {
 }
 function openUrls(urls) {
   for (const url of urls) {
-    const opened = (0, import_node_child_process11.spawnSync)("open", [url], { encoding: "utf-8" });
+    const opened = (0, import_node_child_process12.spawnSync)("open", [url], { encoding: "utf-8" });
     if (opened.status !== 0) {
       process.stderr.write(`Warning: could not open '${url}'.
 `);
@@ -6105,18 +6221,19 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
       const target = linked ? resolveLinkedTarget(repoPath) : resolvePrimaryTarget(repoPath);
       let devpodId = target.devpodId;
       if (target.kind === "linked") {
-        const overlayPath = import_node_path15.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
-        if (!import_node_fs15.default.existsSync(overlayPath)) {
+        const overlayPath = import_node_path16.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
+        if (!import_node_fs16.default.existsSync(overlayPath)) {
           throw new Error(`Missing required DevPod compose overlay: ${overlayPath}`);
         }
       }
+      const managedPostStart = resolveManagedPostStartPlan(repoPath);
       const runtime = loadRuntimeConfig(
         repoPath,
         target.kind === "primary" ? "" : target.workspace
       );
       const apps = proxyAppsFromConfig(runtime.config);
       const parsedUpstreams = apps.map((app) => parseUpstream(app.upstream));
-      const aliasPrefix = target.kind === "linked" ? target.workspace : wsFromBranch(runtime.config.project?.name ?? import_node_path15.default.basename(repoPath)) ?? "app";
+      const aliasPrefix = target.kind === "linked" ? target.workspace : wsFromBranch(runtime.config.project?.name ?? import_node_path16.default.basename(repoPath)) ?? "app";
       for (const [index, app] of apps.entries()) {
         if (app.protocol === "tcp" && !parsedUpstreams[index].host.startsWith(`${aliasPrefix}-`)) {
           const owner = target.kind === "linked" ? "workspace" : "checkout";
@@ -6144,36 +6261,38 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           writeWorkspaceOwnership(repoPath, ownership);
         }
       };
-      const recreateAndWait = async () => {
+      const preflight = (timeoutMs) => waitForContainerPreflight(repoPath, currentTarget(), upstreamHosts, timeoutMs);
+      const recreateAndPreflight = async () => {
         startAndProveAttachment(true);
-        await waitForContainerPreflight(
-          repoPath,
-          currentTarget(),
-          upstreamHosts,
-          options.containerTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS
-        );
+        return preflight(options.containerTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS);
       };
       let recreated = false;
+      let container;
       try {
         startAndProveAttachment();
       } catch (error) {
         if (!target.hadExactDevpod) {
           throw error;
         }
-        await recreateAndWait();
+        container = await recreateAndPreflight();
         recreated = true;
       }
-      if (!recreated) {
+      if (!container) {
         try {
-          await waitForContainerPreflight(repoPath, currentTarget(), upstreamHosts, 0);
+          container = await preflight(0);
         } catch (error) {
           if (!target.hadExactDevpod) {
             throw error;
           }
-          await recreateAndWait();
+          container = await recreateAndPreflight();
           recreated = true;
         }
       }
+      runManagedPostStart({
+        plan: managedPostStart,
+        container,
+        quiet: options.quiet
+      });
       const publication = await replacePublishedProxyRoutes(
         repoPath,
         runtime.config,
@@ -6190,7 +6309,12 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         if (!target.hadExactDevpod || recreated) {
           throw error;
         }
-        await recreateAndWait();
+        const recoveredContainer = await recreateAndPreflight();
+        runManagedPostStart({
+          plan: managedPostStart,
+          container: recoveredContainer,
+          quiet: options.quiet
+        });
         recreated = true;
         replaceHostRoutesForRepo(repoPath, publication.routes);
         await waitForHttpRoutes(
@@ -6233,17 +6357,18 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
     }
   });
 }
-var import_node_child_process11, import_node_fs15, import_node_path15, DEVCONTAINER_OVERLAY, DEFAULT_READINESS_TIMEOUT_MS, POLL_INTERVAL_MS;
+var import_node_child_process12, import_node_fs16, import_node_path16, DEVCONTAINER_OVERLAY, DEFAULT_READINESS_TIMEOUT_MS, POLL_INTERVAL_MS;
 var init_workspace_ensure = __esm({
   "src/core/workspace-ensure.ts"() {
     "use strict";
-    import_node_child_process11 = require("child_process");
-    import_node_fs15 = __toESM(require("fs"));
-    import_node_path15 = __toESM(require("path"));
+    import_node_child_process12 = require("child_process");
+    import_node_fs16 = __toESM(require("fs"));
+    import_node_path16 = __toESM(require("path"));
     init_devpod_environment();
     init_devpod_workspaces();
     init_host_routes();
     init_http_route_probe();
+    init_managed_post_start();
     init_repo_config();
     init_route_publication();
     init_router();
@@ -6313,20 +6438,20 @@ function warnMissingWorkspaceOwnership(repoPath) {
   );
 }
 function defaultWorktreePath(mainRepo, ws) {
-  return import_node_path16.default.join(mainRepo, "trees", ws);
+  return import_node_path17.default.join(mainRepo, "trees", ws);
 }
 function assertDefaultWorktreeRootIgnored(mainRepo) {
-  const ignored = (0, import_node_child_process12.spawnSync)("git", ["-C", mainRepo, "check-ignore", "-q", "--no-index", "trees/"], {
+  const ignored = (0, import_node_child_process13.spawnSync)("git", ["-C", mainRepo, "check-ignore", "-q", "--no-index", "trees/"], {
     encoding: "utf-8"
   });
   if (ignored.status !== 0) {
     throw new Error(
-      `Default worktree root '${import_node_path16.default.join(mainRepo, "trees")}' is not ignored. Add 'trees/' to '${import_node_path16.default.join(mainRepo, ".gitignore")}' or use --path.`
+      `Default worktree root '${import_node_path17.default.join(mainRepo, "trees")}' is not ignored. Add 'trees/' to '${import_node_path17.default.join(mainRepo, ".gitignore")}' or use --path.`
     );
   }
 }
 function legacyDefaultWorktreePath(mainRepo, ws) {
-  return import_node_path16.default.join(import_node_path16.default.dirname(mainRepo), `${import_node_path16.default.basename(mainRepo)}-${ws}`);
+  return import_node_path17.default.join(import_node_path17.default.dirname(mainRepo), `${import_node_path17.default.basename(mainRepo)}-${ws}`);
 }
 function teardownFallbackPath(mainRepo, workspace) {
   const candidates = [
@@ -6439,13 +6564,13 @@ function assertFullDownPreflight(mainRepo, target) {
   if (sameWorkspacePath(target.worktreePath, mainRepo)) {
     throw new Error("Refusing to remove the primary Git checkout.");
   }
-  if (!target.worktree || target.worktree.prunable || !import_node_fs16.default.existsSync(target.worktreePath)) return;
+  if (!target.worktree || target.worktree.prunable || !import_node_fs17.default.existsSync(target.worktreePath)) return;
   if (target.worktree.locked) {
     throw new Error(
       `Worktree '${target.worktreePath}' is locked; unlock it before workspace down.`
     );
   }
-  const status = (0, import_node_child_process12.spawnSync)(
+  const status = (0, import_node_child_process13.spawnSync)(
     "git",
     ["-C", target.worktreePath, "status", "--porcelain", "--untracked-files=normal"],
     { encoding: "utf-8" }
@@ -6466,8 +6591,8 @@ async function workspaceUp(branch, opts = {}) {
   if (!ws) {
     throw new Error(`Branch '${branch}' does not yield a valid workspace token.`);
   }
-  const worktreePath = opts.path ? import_node_path16.default.resolve(opts.path) : defaultWorktreePath(mainRepo, ws);
-  if (import_node_fs16.default.existsSync(worktreePath)) {
+  const worktreePath = opts.path ? import_node_path17.default.resolve(opts.path) : defaultWorktreePath(mainRepo, ws);
+  if (import_node_fs17.default.existsSync(worktreePath)) {
     const registered = listGitWorktrees(mainRepo).find(
       (worktree) => sameWorkspacePath(worktree.path, worktreePath)
     );
@@ -6485,11 +6610,11 @@ async function workspaceUp(branch, opts = {}) {
     if (!opts.path) {
       assertDefaultWorktreeRootIgnored(mainRepo);
     }
-    const add = (0, import_node_child_process12.spawnSync)("git", ["-C", mainRepo, "worktree", "add", worktreePath, branch], {
+    const add = (0, import_node_child_process13.spawnSync)("git", ["-C", mainRepo, "worktree", "add", worktreePath, branch], {
       encoding: "utf-8"
     });
     if (add.status !== 0) {
-      const addNew = (0, import_node_child_process12.spawnSync)(
+      const addNew = (0, import_node_child_process13.spawnSync)(
         "git",
         ["-C", mainRepo, "worktree", "add", "-b", branch, worktreePath],
         {
@@ -6590,8 +6715,8 @@ async function runWorkspaceLifecycle(action2, target, opts = {}) {
     }
     const result = mutateWorkspaceRuntime(action2, resolved, worktrees, opts.quiet);
     if (removeWorktree) {
-      if (resolved.worktree && !resolved.worktree.prunable && import_node_fs16.default.existsSync(resolved.worktreePath)) {
-        const rm = (0, import_node_child_process12.spawnSync)("git", ["-C", mainRepo, "worktree", "remove", resolved.worktreePath], {
+      if (resolved.worktree && !resolved.worktree.prunable && import_node_fs17.default.existsSync(resolved.worktreePath)) {
+        const rm = (0, import_node_child_process13.spawnSync)("git", ["-C", mainRepo, "worktree", "remove", resolved.worktreePath], {
           encoding: "utf-8"
         });
         if (rm.status !== 0) {
@@ -6609,7 +6734,7 @@ async function runWorkspaceLifecycle(action2, target, opts = {}) {
     }
     return result;
   };
-  return resolved.worktree && !resolved.worktree.prunable && import_node_fs16.default.existsSync(resolved.worktreePath) ? withWorkspaceLifecycleLock(resolved.worktreePath, operation) : operation();
+  return resolved.worktree && !resolved.worktree.prunable && import_node_fs17.default.existsSync(resolved.worktreePath) ? withWorkspaceLifecycleLock(resolved.worktreePath, operation) : operation();
 }
 async function workspaceStopOwnedPath(worktreePath, opts = {}) {
   const mainRepo = resolveRepoPath(opts.repoPath);
@@ -6638,13 +6763,13 @@ async function workspaceStop(target, opts = {}) {
 async function workspaceDown(target, opts = {}) {
   return runWorkspaceLifecycle("down", target, opts);
 }
-var import_node_child_process12, import_node_fs16, import_node_path16;
+var import_node_child_process13, import_node_fs17, import_node_path17;
 var init_workspace_lifecycle = __esm({
   "src/core/workspace-lifecycle.ts"() {
     "use strict";
-    import_node_child_process12 = require("child_process");
-    import_node_fs16 = __toESM(require("fs"));
-    import_node_path16 = __toESM(require("path"));
+    import_node_child_process13 = require("child_process");
+    import_node_fs17 = __toESM(require("fs"));
+    import_node_path17 = __toESM(require("path"));
     init_devpod_workspaces();
     init_repo_config();
     init_route_state();
@@ -6766,7 +6891,7 @@ function ensureGuidance(repoPath) {
   return `Run 'devrouter ensure ${repoPath}' first.`;
 }
 function assertRunningDevpod(devpodId, repoPath) {
-  const result = (0, import_node_child_process13.spawnSync)("devpod", ["status", devpodId, "--output", "json"], {
+  const result = (0, import_node_child_process14.spawnSync)("devpod", ["status", devpodId, "--output", "json"], {
     encoding: "utf-8"
   });
   if (result.status !== 0) {
@@ -6822,7 +6947,7 @@ async function devpodExec(repoPath, command) {
       wrappedCommand
     ];
     return new Promise((resolve, reject) => {
-      const child = (0, import_node_child_process13.spawn)("devpod", args, { stdio: ["inherit", "inherit", "pipe"] });
+      const child = (0, import_node_child_process14.spawn)("devpod", args, { stdio: ["inherit", "inherit", "pipe"] });
       let pending = Buffer.alloc(0);
       let statusBytes = Buffer.alloc(0);
       let readingStatus = false;
@@ -6881,11 +7006,11 @@ async function devpodExec(repoPath, command) {
     });
   });
 }
-var import_node_child_process13, import_node_crypto4, DEVPOD_MISSING_EXIT_STATUS_DIAGNOSTIC;
+var import_node_child_process14, import_node_crypto4, DEVPOD_MISSING_EXIT_STATUS_DIAGNOSTIC;
 var init_devpod_exec = __esm({
   "src/core/devpod-exec.ts"() {
     "use strict";
-    import_node_child_process13 = require("child_process");
+    import_node_child_process14 = require("child_process");
     import_node_crypto4 = require("crypto");
     init_devpod_environment();
     init_devpod_workspaces();
@@ -7070,7 +7195,7 @@ async function runOpenCommand(name) {
     );
     return;
   }
-  const result = (0, import_node_child_process14.spawnSync)("open", [url], { encoding: "utf-8" });
+  const result = (0, import_node_child_process15.spawnSync)("open", [url], { encoding: "utf-8" });
   if (result.status !== 0) {
     const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
     throw new Error(`Unable to open '${url}': ${details || "unknown error"}`);
@@ -7078,11 +7203,11 @@ async function runOpenCommand(name) {
   process.stdout.write(`Opened ${url}
 `);
 }
-var import_node_child_process14;
+var import_node_child_process15;
 var init_open = __esm({
   "src/commands/open.ts"() {
     "use strict";
-    import_node_child_process14 = require("child_process");
+    import_node_child_process15 = require("child_process");
     init_docker();
     init_host_routes();
     init_repo_config();
@@ -7105,7 +7230,7 @@ async function runLogsCommand(options) {
   const args = ["logs", "--tail", tail, ROUTER_CONTAINER_NAME];
   if (options.follow) {
     args.splice(1, 0, "-f");
-    const child = (0, import_node_child_process15.spawn)("docker", args, { stdio: "inherit" });
+    const child = (0, import_node_child_process16.spawn)("docker", args, { stdio: "inherit" });
     const onSignal = () => {
       child.kill("SIGTERM");
     };
@@ -7119,17 +7244,17 @@ async function runLogsCommand(options) {
       });
     });
   } else {
-    const result = (0, import_node_child_process15.spawnSync)("docker", args, { stdio: "inherit" });
+    const result = (0, import_node_child_process16.spawnSync)("docker", args, { stdio: "inherit" });
     if (result.status !== 0) {
       throw new Error("Failed to retrieve router logs.");
     }
   }
 }
-var import_node_child_process15;
+var import_node_child_process16;
 var init_logs = __esm({
   "src/commands/logs.ts"() {
     "use strict";
-    import_node_child_process15 = require("child_process");
+    import_node_child_process16 = require("child_process");
     init_docker();
     init_router();
   }
@@ -7169,17 +7294,17 @@ function asRecord3(value) {
   return value;
 }
 function readJson(filePath) {
-  if (!import_node_fs17.default.existsSync(filePath)) {
+  if (!import_node_fs18.default.existsSync(filePath)) {
     return void 0;
   }
   try {
-    return JSON.parse(import_node_fs17.default.readFileSync(filePath, "utf-8"));
+    return JSON.parse(import_node_fs18.default.readFileSync(filePath, "utf-8"));
   } catch {
     return void 0;
   }
 }
 function relative(repoPath, filePath) {
-  return import_node_path17.default.relative(repoPath, filePath) || ".";
+  return import_node_path18.default.relative(repoPath, filePath) || ".";
 }
 function redactEnvAssignments(value) {
   return value.replace(
@@ -7220,7 +7345,7 @@ function inspectPackageManager(repoPath, pkg) {
     ["bun.lock", "bun"]
   ];
   for (const [fileName, name] of lockfiles) {
-    if (import_node_fs17.default.existsSync(import_node_path17.default.join(repoPath, fileName))) {
+    if (import_node_fs18.default.existsSync(import_node_path18.default.join(repoPath, fileName))) {
       return { name, source: fileName };
     }
   }
@@ -7235,9 +7360,9 @@ function inspectNode(repoPath, pkg) {
   if (typeof engines?.node === "string") {
     return { version: engines.node, source: "package.json:engines.node" };
   }
-  const nvmrc = import_node_path17.default.join(repoPath, ".nvmrc");
-  if (import_node_fs17.default.existsSync(nvmrc)) {
-    const version = import_node_fs17.default.readFileSync(nvmrc, "utf-8").trim();
+  const nvmrc = import_node_path18.default.join(repoPath, ".nvmrc");
+  if (import_node_fs18.default.existsSync(nvmrc)) {
+    const version = import_node_fs18.default.readFileSync(nvmrc, "utf-8").trim();
     return { version, source: ".nvmrc" };
   }
   return void 0;
@@ -7298,7 +7423,7 @@ function configuredComposeFiles(repoPath) {
     const files = config.apps.filter(
       (app) => app.runtime === "docker"
     ).flatMap((app) => app.docker.composeFiles).filter(
-      (fileName) => !import_node_path17.default.isAbsolute(fileName) && !import_node_path17.default.normalize(fileName).startsWith("..")
+      (fileName) => !import_node_path18.default.isAbsolute(fileName) && !import_node_path18.default.normalize(fileName).startsWith("..")
     );
     return Array.from(new Set(files));
   } catch {
@@ -7316,7 +7441,7 @@ function composeFiles(repoPath) {
     ...configuredComposeFiles(repoPath)
   ];
   return Array.from(new Set(candidates)).filter(
-    (fileName) => import_node_fs17.default.existsSync(import_node_path17.default.join(repoPath, fileName))
+    (fileName) => import_node_fs18.default.existsSync(import_node_path18.default.join(repoPath, fileName))
   );
 }
 function stringArray(value) {
@@ -7354,7 +7479,7 @@ function inspectServices(repoPath) {
   const services = [];
   for (const fileName of composeFiles(repoPath)) {
     try {
-      const parsed = import_yaml5.default.parse(import_node_fs17.default.readFileSync(import_node_path17.default.join(repoPath, fileName), "utf-8"));
+      const parsed = import_yaml5.default.parse(import_node_fs18.default.readFileSync(import_node_path18.default.join(repoPath, fileName), "utf-8"));
       const serviceMap = asRecord3(asRecord3(parsed)?.services);
       for (const [name, value] of Object.entries(serviceMap ?? {})) {
         const service = asRecord3(value);
@@ -7389,8 +7514,8 @@ function inspectServices(repoPath) {
   return services;
 }
 function inspectEnvFiles(repoPath) {
-  const files = import_node_fs17.default.readdirSync(repoPath).filter((fileName) => /^\.env(\.|$)/.test(fileName)).sort().map((fileName) => {
-    const content = import_node_fs17.default.readFileSync(import_node_path17.default.join(repoPath, fileName), "utf-8");
+  const files = import_node_fs18.default.readdirSync(repoPath).filter((fileName) => /^\.env(\.|$)/.test(fileName)).sort().map((fileName) => {
+    const content = import_node_fs18.default.readFileSync(import_node_path18.default.join(repoPath, fileName), "utf-8");
     const names = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#") && line.includes("=")).map((line) => line.split("=")[0]?.trim()).filter((name) => Boolean(name)).sort();
     return { path: fileName, names };
   });
@@ -7404,18 +7529,18 @@ function inspectEnvFiles(repoPath) {
   };
 }
 function inspectDevcontainer(repoPath) {
-  const dir = import_node_path17.default.join(repoPath, ".devcontainer");
-  if (!import_node_fs17.default.existsSync(dir)) {
+  const dir = import_node_path18.default.join(repoPath, ".devcontainer");
+  if (!import_node_fs18.default.existsSync(dir)) {
     return { exists: false, files: [] };
   }
   return {
     exists: true,
-    files: import_node_fs17.default.readdirSync(dir).filter((fileName) => import_node_fs17.default.statSync(import_node_path17.default.join(dir, fileName)).isFile()).sort().map((fileName) => `.devcontainer/${fileName}`)
+    files: import_node_fs18.default.readdirSync(dir).filter((fileName) => import_node_fs18.default.statSync(import_node_path18.default.join(dir, fileName)).isFile()).sort().map((fileName) => `.devcontainer/${fileName}`)
   };
 }
 function inspectDevrouter(repoPath) {
   const configPath = getRepoConfigPath(repoPath);
-  if (!import_node_fs17.default.existsSync(configPath)) {
+  if (!import_node_fs18.default.existsSync(configPath)) {
     return {
       exists: false,
       configPath,
@@ -7459,15 +7584,15 @@ function inspectAgentGuidance(repoPath) {
     ["AGENTS.md", "agents"],
     ["CLAUDE.md", "claude"]
   ]) {
-    if (import_node_fs17.default.existsSync(import_node_path17.default.join(repoPath, fileName))) {
+    if (import_node_fs18.default.existsSync(import_node_path18.default.join(repoPath, fileName))) {
       results.push({ path: fileName, kind });
     }
   }
-  const skillsDir = import_node_path17.default.join(repoPath, ".agents", "skills");
-  if (import_node_fs17.default.existsSync(skillsDir)) {
-    for (const name of import_node_fs17.default.readdirSync(skillsDir).sort()) {
-      const skillPath = import_node_path17.default.join(skillsDir, name, "SKILL.md");
-      if (import_node_fs17.default.existsSync(skillPath)) {
+  const skillsDir = import_node_path18.default.join(repoPath, ".agents", "skills");
+  if (import_node_fs18.default.existsSync(skillsDir)) {
+    for (const name of import_node_fs18.default.readdirSync(skillsDir).sort()) {
+      const skillPath = import_node_path18.default.join(skillsDir, name, "SKILL.md");
+      if (import_node_fs18.default.existsSync(skillPath)) {
         results.push({ path: relative(repoPath, skillPath), kind: "skill" });
       }
     }
@@ -7510,7 +7635,7 @@ function buildIssues(report) {
 }
 function inspectRepo(options = {}) {
   const repoPath = resolveRepoPath(options.repo);
-  const pkg = readJson(import_node_path17.default.join(repoPath, "package.json"));
+  const pkg = readJson(import_node_path18.default.join(repoPath, "package.json"));
   const scripts = inspectScripts(pkg);
   const reportWithoutIssues = {
     repoPath,
@@ -7529,12 +7654,12 @@ function inspectRepo(options = {}) {
     issues: buildIssues(reportWithoutIssues)
   };
 }
-var import_node_fs17, import_node_path17, import_yaml5;
+var import_node_fs18, import_node_path18, import_yaml5;
 var init_repo_inspect = __esm({
   "src/core/repo-inspect.ts"() {
     "use strict";
-    import_node_fs17 = __toESM(require("fs"));
-    import_node_path17 = __toESM(require("path"));
+    import_node_fs18 = __toESM(require("fs"));
+    import_node_path18 = __toESM(require("path"));
     import_yaml5 = __toESM(require("yaml"));
     init_repo_config();
   }
@@ -7639,7 +7764,7 @@ function requiredFileChecks(repoPath) {
     ".devcontainer/docker-compose.yml",
     ".devrouter.yml"
   ];
-  const missing = required.filter((fileName) => !import_node_fs18.default.existsSync(import_node_path18.default.join(repoPath, fileName)));
+  const missing = required.filter((fileName) => !import_node_fs19.default.existsSync(import_node_path19.default.join(repoPath, fileName)));
   return {
     id: "repo.devcontainer.verify-files",
     level: missing.length === 0 ? "ok" : "error",
@@ -7858,12 +7983,12 @@ async function verifyDevcontainer(options = {}) {
     nextSteps: collectNextSteps3(checks)
   };
 }
-var import_node_fs18, import_node_path18;
+var import_node_fs19, import_node_path19;
 var init_devcontainer_verify = __esm({
   "src/core/devcontainer-verify.ts"() {
     "use strict";
-    import_node_fs18 = __toESM(require("fs"));
-    import_node_path18 = __toESM(require("path"));
+    import_node_fs19 = __toESM(require("fs"));
+    import_node_path19 = __toESM(require("path"));
     init_capabilities();
     init_doctor();
     init_host_routes();
@@ -7901,30 +8026,22 @@ function inferDevProcess(repo) {
 function inferPort2(repo) {
   return repo.apps.find((app) => app.port)?.port ?? 3e3;
 }
-function renderDockerfile(nodeMajor, pnpmVersion, version) {
+function renderDockerfile(nodeMajor, pnpmVersion) {
   const pnpmPackageSpec = `pnpm@${pnpmVersion}`;
-  const devrouterPackageSpec = `@devrouter/cli@${version}`;
-  const devrouterTarball = `devrouter-cli-${version}.tgz`;
-  return `# ${MANAGED_MARKER}
+  return `# ${MANAGED_MARKER2}
 FROM node:${nodeMajor}-bookworm-slim
 
 RUN apt-get update \\
-  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl tar util-linux \\
+  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl util-linux \\
   && rm -rf /var/lib/apt/lists/*
 
 RUN npm install -g ${shellSingleQuote(pnpmPackageSpec)}
 
-RUN npm pack --silent ${shellSingleQuote(devrouterPackageSpec)} \\
-  && tar -xzf ${shellSingleQuote(devrouterTarball)} --strip-components=2 \\
-    -C /usr/local/bin package/bin/devrouter-process \\
-  && chmod +x /usr/local/bin/devrouter-process \\
-  && rm ${shellSingleQuote(devrouterTarball)}
-
 WORKDIR /workspaces/app
 `;
 }
 function renderCompose(projectName) {
-  return `# ${MANAGED_MARKER}
+  return `# ${MANAGED_MARKER2}
 services:
   postgres:
     image: postgres:16-alpine
@@ -7977,12 +8094,12 @@ volumes:
 `;
 }
 function renderDefaultComposeOverlay() {
-  return `# ${MANAGED_MARKER}
+  return `# ${MANAGED_MARKER2}
 services: {}
 `;
 }
 function renderDevrouterComposeOverlay() {
-  return `# ${MANAGED_MARKER}
+  return `# ${MANAGED_MARKER2}
 # A linked worktree's .git file points at the host repository's common Git
 # directory. workspace ensure sets this absolute path before DevPod starts.
 services:
@@ -7998,7 +8115,7 @@ services:
 }
 function renderInitDb() {
   return `#!/usr/bin/env bash
-# ${MANAGED_MARKER}
+# ${MANAGED_MARKER2}
 set -euo pipefail
 
 psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<'SQL'
@@ -8017,10 +8134,9 @@ function renderDevcontainerJson(projectName) {
   "service": "app",
   "workspaceFolder": "/workspaces/${projectName}",
   "postCreateCommand": "bash .devcontainer/post-create.sh",
-  "postStartCommand": "bash .devcontainer/post-start.sh",
   "customizations": {
     "devrouter": {
-      "managed": "${MANAGED_MARKER}"
+      "managed": "${MANAGED_MARKER2}"
     },
     "vscode": {
       "extensions": []
@@ -8030,7 +8146,7 @@ function renderDevcontainerJson(projectName) {
 `;
 }
 function renderEnv(projectName, port) {
-  return `# ${MANAGED_MARKER}
+  return `# ${MANAGED_MARKER2}
 WORKSPACE=${projectName}
 HOST=0.0.0.0
 HOSTNAME=0.0.0.0
@@ -8041,7 +8157,7 @@ SHADOW_DATABASE_URL=postgres://prisma:prisma@postgres:5432/shadow
 }
 function renderPostCreate() {
   return `#!/usr/bin/env bash
-# ${MANAGED_MARKER}
+# ${MANAGED_MARKER2}
 set -euo pipefail
 
 export CI=true
@@ -8057,7 +8173,7 @@ function shellSingleQuote(value) {
 }
 function renderPostStart(devProcess) {
   return `#!/usr/bin/env bash
-# ${MANAGED_MARKER}
+# ${MANAGED_MARKER2}
 set -euo pipefail
 
 export CI=true
@@ -8066,7 +8182,9 @@ set -a
 . .devcontainer/devcontainer.env
 set +a
 
-devrouter-process ensure \\
+: "\${DEVROUTER_PROCESS_HELPER:?Run devrouter ensure to start this managed application process.}"
+
+"$DEVROUTER_PROCESS_HELPER" ensure \\
   --name app \\
   --match ${shellSingleQuote(devProcess.match)} \\
   --log /tmp/devrouter-app.log \\
@@ -8074,7 +8192,7 @@ devrouter-process ensure \\
 `;
 }
 function renderDevrouter(projectName, port, version) {
-  return `# ${MANAGED_MARKER}
+  return `# ${MANAGED_MARKER2}
 version: 1
 devrouter:
   version: ${version}
@@ -8096,24 +8214,16 @@ apps:
 `;
 }
 function renderReadme(projectName) {
-  return `<!-- ${MANAGED_MARKER} -->
+  return `<!-- ${MANAGED_MARKER2} -->
 # Devcontainer
 
 Use this repo through the devcontainer, with devrouter providing stable local routes.
 
-Primary checkout:
+Primary or linked checkout:
 
 \`\`\`bash
 devrouter setup --yes
-devpod up .
-devrouter app run app --repo . --yes
-devrouter app run db --repo . --yes
-\`\`\`
-
-Existing linked worktree:
-
-\`\`\`bash
-devrouter workspace ensure .
+devrouter ensure .
 \`\`\`
 
 - App: https://${projectName}.localhost
@@ -8122,18 +8232,9 @@ devrouter workspace ensure .
 }
 function postWriteNextSteps(repoPath) {
   const quotedRepoPath = shellSingleQuote(repoPath);
-  if (isLinkedWorktree(repoPath)) {
-    return [
-      `Run: devrouter setup --repo ${quotedRepoPath} --yes`,
-      `Run: devrouter workspace ensure ${quotedRepoPath}`,
-      `Optional: devrouter repo agents --repo ${quotedRepoPath}`
-    ];
-  }
   return [
     `Run: devrouter setup --repo ${quotedRepoPath} --yes`,
-    `Run: cd ${quotedRepoPath} && devpod up .`,
-    `Run: devrouter app run app --repo ${quotedRepoPath} --yes`,
-    `Run: devrouter app run db --repo ${quotedRepoPath} --yes`,
+    `Run: devrouter ensure ${quotedRepoPath}`,
     `Optional: devrouter repo agents --repo ${quotedRepoPath}`
   ];
 }
@@ -8183,7 +8284,7 @@ function packageManagerIssues(repo) {
 }
 function plannedFiles(repoPath, version) {
   const repo = inspectRepo({ repo: repoPath });
-  const projectName = sanitizeProjectName(import_node_path19.default.basename(repo.repoPath));
+  const projectName = sanitizeProjectName(import_node_path20.default.basename(repo.repoPath));
   const nodeMajor = majorVersion(repo.node?.version, "24");
   const pnpmVersion = repo.packageManager?.name === "pnpm" && repo.packageManager.version ? repo.packageManager.version : DEFAULT_PNPM_VERSION;
   const port = inferPort2(repo);
@@ -8195,7 +8296,7 @@ function plannedFiles(repoPath, version) {
     files: [
       {
         relativePath: ".devcontainer/Dockerfile",
-        content: renderDockerfile(nodeMajor, pnpmVersion, version)
+        content: renderDockerfile(nodeMajor, pnpmVersion)
       },
       { relativePath: ".devcontainer/docker-compose.yml", content: renderCompose(projectName) },
       {
@@ -8228,8 +8329,8 @@ function plannedFiles(repoPath, version) {
   };
 }
 function classifyFile(repoPath, file) {
-  const absolutePath = import_node_path19.default.join(repoPath, file.relativePath);
-  if (!import_node_fs19.default.existsSync(absolutePath)) {
+  const absolutePath = import_node_path20.default.join(repoPath, file.relativePath);
+  if (!import_node_fs20.default.existsSync(absolutePath)) {
     return {
       path: file.relativePath,
       action: "create",
@@ -8237,8 +8338,8 @@ function classifyFile(repoPath, file) {
       bytes: Buffer.byteLength(file.content)
     };
   }
-  const current = import_node_fs19.default.readFileSync(absolutePath, "utf-8");
-  if (!current.includes(MANAGED_MARKER)) {
+  const current = import_node_fs20.default.readFileSync(absolutePath, "utf-8");
+  if (!current.includes(MANAGED_MARKER2)) {
     return {
       path: file.relativePath,
       action: "conflict",
@@ -8294,11 +8395,11 @@ function buildPlan(repoPath, dryRun, version) {
   };
 }
 function writeFile(repoPath, file) {
-  const absolutePath = import_node_path19.default.join(repoPath, file.relativePath);
-  import_node_fs19.default.mkdirSync(import_node_path19.default.dirname(absolutePath), { recursive: true });
-  import_node_fs19.default.writeFileSync(absolutePath, file.content, "utf-8");
+  const absolutePath = import_node_path20.default.join(repoPath, file.relativePath);
+  import_node_fs20.default.mkdirSync(import_node_path20.default.dirname(absolutePath), { recursive: true });
+  import_node_fs20.default.writeFileSync(absolutePath, file.content, "utf-8");
   if (file.executable) {
-    import_node_fs19.default.chmodSync(absolutePath, 493);
+    import_node_fs20.default.chmodSync(absolutePath, 493);
   }
 }
 function writeDevcontainer(options = {}) {
@@ -8336,16 +8437,15 @@ function writeDevcontainer(options = {}) {
     nextSteps: postWriteNextSteps(repoPath)
   };
 }
-var import_node_fs19, import_node_path19, MANAGED_MARKER, DEFAULT_DEVROUTER_VERSION, DEFAULT_PNPM_VERSION, VALID_PACKAGE_VERSION_RE;
+var import_node_fs20, import_node_path20, MANAGED_MARKER2, DEFAULT_DEVROUTER_VERSION, DEFAULT_PNPM_VERSION, VALID_PACKAGE_VERSION_RE;
 var init_devcontainer_write = __esm({
   "src/core/devcontainer-write.ts"() {
     "use strict";
-    import_node_fs19 = __toESM(require("fs"));
-    import_node_path19 = __toESM(require("path"));
+    import_node_fs20 = __toESM(require("fs"));
+    import_node_path20 = __toESM(require("path"));
     init_repo_config();
     init_repo_inspect();
-    init_workspace();
-    MANAGED_MARKER = "devrouter:managed devcontainer";
+    MANAGED_MARKER2 = "devrouter:managed devcontainer";
     DEFAULT_DEVROUTER_VERSION = "0.0.0";
     DEFAULT_PNPM_VERSION = "11.6.0";
     VALID_PACKAGE_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
@@ -8733,7 +8833,7 @@ function sanitizeRouterId(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function repoHash(repoPath) {
-  return (0, import_node_crypto5.createHash)("sha1").update(import_node_path20.default.resolve(repoPath)).digest("hex").slice(0, 12);
+  return (0, import_node_crypto5.createHash)("sha1").update(import_node_path21.default.resolve(repoPath)).digest("hex").slice(0, 12);
 }
 function asDockerApp(app) {
   return app.runtime === "docker";
@@ -8812,11 +8912,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_path20.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
-  import_node_fs20.default.mkdirSync(cachePath, { recursive: true });
-  const overlayPath = import_node_path20.default.join(cachePath, "compose.devrouter.yml");
+  const cachePath = import_node_path21.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
+  import_node_fs21.default.mkdirSync(cachePath, { recursive: true });
+  const overlayPath = import_node_path21.default.join(cachePath, "compose.devrouter.yml");
   const overlayDocument = buildOverlayDocument(dockerApps, publishTcpPorts);
-  import_node_fs20.default.writeFileSync(overlayPath, import_yaml6.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
+  import_node_fs21.default.writeFileSync(overlayPath, import_yaml6.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
   return {
     overlayPath,
     composeFiles: ensureComposeFiles(dockerApps),
@@ -8830,7 +8930,7 @@ function runDockerComposeUp(repoPath, composeFiles2, overlayPath, services) {
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "up", "-d", "--wait", ...services];
-  const result = (0, import_node_child_process16.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process17.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -8858,7 +8958,7 @@ function queryRunningComposeServices(repoPath, composeFiles2, overlayPath, servi
     "--services",
     ...services
   ];
-  const result = (0, import_node_child_process16.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process17.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -8884,7 +8984,7 @@ function runDockerComposeStop(repoPath, composeFiles2, overlayPath, services) {
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "stop", ...services];
-  const result = (0, import_node_child_process16.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process17.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -8910,7 +9010,7 @@ function runDockerComposeLogs(repoPath, composeFiles2, overlayPath, services, ta
     String(tail),
     ...services
   ];
-  (0, import_node_child_process16.spawnSync)("docker", args, {
+  (0, import_node_child_process17.spawnSync)("docker", args, {
     stdio: "inherit",
     cwd: repoPath
   });
@@ -8922,7 +9022,7 @@ function queryMappedPort(repoPath, composeFiles2, overlayPath, service, internal
     fileArgs.push("-f", resolved);
   }
   const args = ["compose", ...fileArgs, "-f", overlayPath, "port", service, String(internalPort)];
-  const result = (0, import_node_child_process16.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process17.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -8936,14 +9036,14 @@ 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_process16, import_node_crypto5, import_node_fs20, import_node_path20, import_yaml6;
+var import_node_child_process17, import_node_crypto5, import_node_fs21, import_node_path21, import_yaml6;
 var init_docker_run = __esm({
   "src/core/docker-run.ts"() {
     "use strict";
-    import_node_child_process16 = require("child_process");
+    import_node_child_process17 = require("child_process");
     import_node_crypto5 = require("crypto");
-    import_node_fs20 = __toESM(require("fs"));
-    import_node_path20 = __toESM(require("path"));
+    import_node_fs21 = __toESM(require("fs"));
+    import_node_path21 = __toESM(require("path"));
     import_yaml6 = __toESM(require("yaml"));
     init_docker_error_guidance();
     init_paths();
@@ -9033,7 +9133,7 @@ function isProcessRunning(pid) {
   }
 }
 function readProcessTree(rootPid) {
-  const result = (0, import_node_child_process17.spawnSync)("ps", ["-ax", "-o", "pid=,ppid="], { encoding: "utf-8" });
+  const result = (0, import_node_child_process18.spawnSync)("ps", ["-ax", "-o", "pid=,ppid="], { encoding: "utf-8" });
   if (result.status !== 0) {
     return [rootPid];
   }
@@ -9144,12 +9244,12 @@ function detectListeningPorts(pids) {
   if (pids.length === 0) {
     return [];
   }
-  const result = (0, import_node_child_process17.spawnSync)("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-a", "-p", pids.join(",")], {
+  const result = (0, import_node_child_process18.spawnSync)("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-a", "-p", pids.join(",")], {
     encoding: "utf-8"
   });
   if (result.error && result.error.code === "ENOENT") {
     if (process.platform === "linux") {
-      const ssResult = (0, import_node_child_process17.spawnSync)("ss", ["-H", "-lntp", "-p"], { encoding: "utf-8" });
+      const ssResult = (0, import_node_child_process18.spawnSync)("ss", ["-H", "-lntp", "-p"], { encoding: "utf-8" });
       if (ssResult.status === 0 && ssResult.stdout) {
         return parseSsListeningPorts(ssResult.stdout, new Set(pids));
       }
@@ -9208,7 +9308,7 @@ async function runHostApp(repoPath, app, extraEnv = {}, secretManager, env, work
     app.hostRun.command,
     true
   ) : app.hostRun.command;
-  const child = (0, import_node_child_process17.spawn)(spawnCommand, {
+  const child = (0, import_node_child_process18.spawn)(spawnCommand, {
     cwd: commandCwd,
     stdio: "inherit",
     shell: true,
@@ -9576,7 +9676,7 @@ async function execWithAppEnv(options) {
           options.command[0],
           true
         );
-        child = (0, import_node_child_process17.spawn)(wrapped, {
+        child = (0, import_node_child_process18.spawn)(wrapped, {
           cwd: deps.repoPath,
           stdio: "inherit",
           shell: true,
@@ -9590,7 +9690,7 @@ async function execWithAppEnv(options) {
           false
         );
         const [cmd, ...wrappedArgs] = wrapped;
-        child = (0, import_node_child_process17.spawn)(cmd, wrappedArgs, {
+        child = (0, import_node_child_process18.spawn)(cmd, wrappedArgs, {
           cwd: deps.repoPath,
           stdio: "inherit",
           shell: false,
@@ -9598,7 +9698,7 @@ async function execWithAppEnv(options) {
         });
       }
     } else if (options.shell) {
-      child = (0, import_node_child_process17.spawn)(options.command[0], {
+      child = (0, import_node_child_process18.spawn)(options.command[0], {
         cwd: deps.repoPath,
         stdio: "inherit",
         shell: true,
@@ -9606,7 +9706,7 @@ async function execWithAppEnv(options) {
       });
     } else {
       const [command, ...args] = options.command;
-      child = (0, import_node_child_process17.spawn)(command, args, {
+      child = (0, import_node_child_process18.spawn)(command, args, {
         cwd: deps.repoPath,
         stdio: "inherit",
         shell: false,
@@ -9627,11 +9727,11 @@ async function execWithAppEnv(options) {
     deps.stopDeps();
   }
 }
-var import_node_child_process17, import_node_net, import_node_process, import_promises, POLL_INTERVAL_MS2, DEFAULT_PORT_TIMEOUT_MS, PROCESS_TERMINATION_GRACE_MS;
+var import_node_child_process18, import_node_net, import_node_process, import_promises, POLL_INTERVAL_MS2, DEFAULT_PORT_TIMEOUT_MS, PROCESS_TERMINATION_GRACE_MS;
 var init_app_run = __esm({
   "src/core/app-run.ts"() {
     "use strict";
-    import_node_child_process17 = require("child_process");
+    import_node_child_process18 = require("child_process");
     import_node_net = __toESM(require("net"));
     import_node_process = require("process");
     import_promises = require("readline/promises");
@@ -9892,7 +9992,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.33" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.34" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "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.34.md

@@ -0,0 +1,28 @@
+# Upgrade to devrouter 0.0.34
+
+Devrouter now supplies its managed process helper at reconciliation time. Consumer images must not download, install, extract, or version-pin devrouter; `.devrouter.yml` is the only consumer-side devrouter version pin.
+
+1. Install `@devrouter/cli@0.0.34` on the host and bump `.devrouter.yml` to `devrouter.version: 0.0.34`.
+2. In a devrouter-managed `.devcontainer/post-start.sh`, keep the repository-owned environment and application command, require `DEVROUTER_PROCESS_HELPER`, and replace direct `devrouter-process ensure` with `"$DEVROUTER_PROCESS_HELPER" ensure`.
+3. Remove `postStartCommand` from `.devcontainer/devcontainer.json`. Canonical `devrouter ensure` delivers the helper and invokes the managed adapter after exact-container proof.
+4. Remove any `@devrouter/cli` download or `devrouter-process` installation/extraction from the consumer Dockerfile. Retain `procps` and `util-linux`; remove `tar` if the application does not otherwise need it.
+5. Run `devrouter repo agents --repo <checkout>` to refresh generated guidance.
+
+Apply the adapter, devcontainer JSON, and Dockerfile migration atomically. A fully legacy image-plus-hook scaffold remains temporarily supported, but a legacy adapter paired with a helper-free image fails before DevPod startup with migration guidance.
+
+Verification:
+
+- Run `devrouter repo devcontainer verify --repo <checkout> --json` and confirm `repo.devcontainer.no-devrouter-image-install` is `ok`.
+- Recreate from the helper-free Dockerfile, then run `devrouter ensure <checkout> --json` twice and confirm cold startup plus warm reuse succeed.
+- Run `devrouter exec <checkout> -- sh -c 'test ! -e /usr/local/bin/devrouter-process'` to prove the helper is absent from the image.
+- Run `devrouter exec <checkout> -- sh -c 'test -x /tmp/devrouter/bin/devrouter-process'` to prove the matching helper was delivered only at runtime.
+
+Report template:
+
+- CLI/config version: `0.0.34`
+- Adapter migration: `<file changed or not applicable>`
+- Image coupling diagnostic: `<ok or details>`
+- Cold/warm ensure: `<DevPod id and route evidence>`
+- Image helper absent: `<passed or failure details>`
+- Runtime helper present: `<passed or failure details>`
+- Remaining blockers: `<none or details>`