@devrouter/cli 0.0.29 → 0.0.31

package/dist/devrouter.js

@@ -235,13 +235,15 @@ Config-level \`envMap\` on dependency references aliases per-dep vars to app-exp
 
 ## Workspace isolation (parallel git worktrees / agents)
 
-Run several worktrees of one repo in parallel without host/route collisions. A **workspace token** is a persisted identity spanning the DevPod id, devrouter routes, \`\${WORKSPACE}\` proxy upstreams, and devcontainer aliases.
+Run several worktrees of one repo in parallel without host/route collisions. A **workspace token** spans the DevPod id, devrouter routes, \`\${WORKSPACE}\` proxy upstreams, and devcontainer aliases.
 
-- **Identity**: each linked worktree stores one authoritative identity in Git metadata. First use reuses an exact-path DevPod or derives a sanitized branch/path slug. Later flags or \`DEVROUTER_WORKSPACE\` may repeat the identity but cannot rename it. Ambiguous identities fail closed. The primary checkout remains non-namespaced.
+- **Identity**: each managed linked worktree stores a local token in Git metadata plus a durable owner record in the repository's Git common directory. The 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 slug. Later flags or \`DEVROUTER_WORKSPACE\` may repeat the identity but cannot rename it. Ambiguous identities fail closed. The primary checkout remains non-namespaced.
 - **When active**: hosts auto-namespace (\`web.localhost\` \u2192 \`web.<ws>.localhost\`), \`\${WORKSPACE}\` 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.
 - **devcontainer integration**: managed scaffolds list the base compose file, then \`\${localEnv:DEVCONTAINER_COMPOSE_OVERLAY:docker-compose.default.yml}\`; custom repositories may keep another default overlay. Selecting \`.devcontainer/docker-compose.devrouter.yml\` for linked worktrees must pass \`WORKSPACE\` and \`DEVROUTER_WORKSPACE\` across the combined base/overlay config and bind-mount \`\${DEVROUTER_GIT_COMMON_DIR}\` to the same absolute app-container path. The app exposes \`\${WORKSPACE}-app\`; the proxy uses \`upstream: \${WORKSPACE}-app:<port>\`.
-- **Lifecycle**: \`devrouter workspace up <branch>\` creates and starts a new worktree under the repository's ignored \`trees/<workspace>\` directory; \`devrouter workspace ensure .\` is the canonical startup/reconciliation command in an existing linked worktree; \`workspace ls\` lists identity/route state; \`workspace down\` serializes teardown with ensure. Ensure proves exact DevPod ownership, overlay/Git mounts, env, aliases, health, Git, HTTP route reachability, and unique running TCP upstream ownership before success, with one bounded recreate for stale state.
+- **Lifecycle**: \`workspace up\` creates and starts a worktree; \`workspace ensure .\` starts/reconciles an existing linked worktree; \`workspace ls\` reports owner/Git/DevPod/route state; \`workspace stop\` stops DevPod/routes but keeps checkout, record, and data; full \`workspace down\` deletes runtime/routes and removes only a clean, unlocked worktree, then its record; \`down --keep-worktree\` keeps checkout and record. Dirty or locked full down fails before side effects.
+- **Cleanup**: owner status is \`present\`, \`missing\`, \`locked\`, or \`conflict\`. \`workspace gc\` is a dry-run report; \`--yes\` deletes only exact ledger-owned missing/prunable resources and their records. GC never removes Git worktrees, branches, or prune state. Git has no worktree-removal hook.
+- **Boundary**: workspace commands require Git. Normal config, app, status, and doctor flows remain usable from a \`.devrouter.yml\` folder without \`.git\`.
 
 ## Secret manager interop (Infisical/Doppler)
 
@@ -312,8 +314,10 @@ Run several worktrees of one repo in parallel without host/route collisions. A *
 - \`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] [--open]\`: start/reconcile and prove an existing linked worktree environment
-- \`devrouter workspace ls [--json]\`: list git worktrees with workspace token + route count
-- \`devrouter workspace down <workspace|branch> [--keep-worktree] [--keep-devpod]\`: free routes + stop devpod + remove worktree
+- \`devrouter workspace ls [--json]\`: list ownership, Git, DevPod, route, path, and branch evidence
+- \`devrouter workspace stop <workspace|branch>\`: stop DevPod and routes; preserve checkout, owner record, and data
+- \`devrouter workspace down <workspace|branch> [--keep-worktree]\`: delete runtime/routes and optionally remove the clean worktree and record
+- \`devrouter workspace gc [--json] [--yes]\`: report missing owners by default; apply exact eligible cleanup with \`--yes\`
 
 ## Validation workflow
 
@@ -1787,7 +1791,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.29" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.31" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -2287,11 +2291,13 @@ function buildOnboardingPrompt(options = {}) {
     "- `envMap` on dependency references (config-level) aliases per-dep vars after dependency env resolution. `envMap` fails fast when source var is missing.",
     "",
     "Workspace isolation (parallel git worktrees / agents):",
-    `- A "workspace token" lets several worktrees of one repo run in parallel without host/route collisions. Each linked worktree persists one authoritative identity spanning the DevPod id, devrouter routes, the \`${WORKSPACE_PLACEHOLDER}\` proxy upstream, and devcontainer aliases.`,
-    "- First use reuses an exact-path DevPod or derives a sanitized branch/path identity. Later flags or `DEVROUTER_WORKSPACE` may repeat but cannot rename the persisted identity. Ambiguous identities fail closed. The primary checkout stays non-namespaced.",
+    `- A "workspace token" lets several worktrees of one repo run in parallel without host/route collisions. Each managed linked worktree has a local Git token plus a durable owner record in the repository's Git common directory spanning the DevPod id, devrouter routes, the \`${WORKSPACE_PLACEHOLDER}\` proxy upstream, and devcontainer aliases.`,
+    "- 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: `devrouter workspace up <branch>` creates and starts a new worktree; `devrouter workspace ensure .` is the canonical start/reconcile command inside an existing linked worktree; `workspace ls` reports state; `workspace down` serializes teardown with ensure.",
+    "- Lifecycle: `workspace up` creates and starts a worktree; `workspace ensure .` starts/reconciles an existing linked worktree; `workspace ls` reports owner/Git/DevPod/route state; `workspace stop` preserves checkout, record, and data; full `workspace down` deletes runtime/routes and removes only a clean, unlocked worktree; `down --keep-worktree` retains checkout and record.",
+    "- 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.",
     "",
     "Secret Manager Integration (config-based):",
@@ -2458,11 +2464,19 @@ var init_ai_prompt = __esm({
       },
       {
         command: "devrouter workspace ls [--json]",
-        purpose: "List git worktrees with their resolved workspace token and active route count."
+        purpose: "List owner, Git, DevPod, route, path, and branch evidence for managed workspaces."
       },
       {
-        command: "devrouter workspace down <workspace|branch> [--keep-worktree] [--keep-devpod]",
-        purpose: "Free a workspace's routes, stop its devpod, and remove its worktree (routes are freed by state-file workspace tag, no config load)."
+        command: "devrouter workspace stop <workspace|branch>",
+        purpose: "Stop the exact DevPod and remove exact routes while preserving the worktree, owner record, and data."
+      },
+      {
+        command: "devrouter workspace down <workspace|branch> [--keep-worktree]",
+        purpose: "Delete exact runtime/routes and remove only a clean, unlocked worktree and its owner record; --keep-worktree preserves checkout and record."
+      },
+      {
+        command: "devrouter workspace gc [--json] [--yes]",
+        purpose: "Report missing owners without mutation by default; --yes deletes only exact eligible ledger-owned resources and records, never Git worktrees."
       }
     ];
   }
@@ -3396,12 +3410,6 @@ function reconcileRouteRunConflict(repoPath, app) {
     }
   }
 }
-function isOrphanedWorkspaceProxyRoute(route) {
-  return route.mode === "proxy" && route.workspace !== void 0 && !import_node_fs9.default.existsSync(route.repoPath);
-}
-function findOrphanedWorkspaceProxyRoutes(routes = listHostRouteState()) {
-  return routes.filter((route) => isOrphanedWorkspaceProxyRoute(route));
-}
 var import_node_fs9;
 var init_route_state = __esm({
   "src/core/route-state.ts"() {
@@ -4064,6 +4072,634 @@ var init_tool_diagnostics = __esm({
   }
 });
 
+// src/core/devpod-workspaces.ts
+function listDevpodWorkspaces() {
+  const result = (0, import_node_child_process6.spawnSync)("devpod", ["list", "--output", "json"], { encoding: "utf-8" });
+  if (result.status !== 0) {
+    const details = [result.error?.message, result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    throw new Error(`devpod list failed: ${details || "devpod is not installed or unavailable"}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("devpod list returned invalid JSON.");
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error("devpod list returned an unexpected response.");
+  }
+  return parsed.map((entry) => {
+    const candidate = entry;
+    if (typeof candidate.id !== "string" || !candidate.source || typeof candidate.source.localFolder !== "string") {
+      throw new Error("devpod list returned a workspace without id/source.localFolder.");
+    }
+    return candidate;
+  });
+}
+function inspectDevpodWorkspaceOwnership(workspaces, devpodId, worktreePath) {
+  const idOwners = workspaces.filter((workspace) => workspace.id === devpodId);
+  const pathOwners = workspaces.filter(
+    (workspace) => sameWorkspacePath(workspace.source.localFolder, worktreePath)
+  );
+  const exact = idOwners.filter(
+    (workspace) => sameWorkspacePath(workspace.source.localFolder, worktreePath)
+  );
+  if (idOwners.length > 1 || pathOwners.length > 1 || idOwners[0] && exact.length === 0 || pathOwners[0] && pathOwners[0].id !== devpodId) {
+    return {
+      status: "conflict",
+      reason: `DevPod '${devpodId}' and worktree '${worktreePath}' do not have one exact owner.`
+    };
+  }
+  return exact[0] ? { status: "owned", workspace: exact[0] } : { status: "absent" };
+}
+function selectDevpodWorkspace(workspaces, repoPath) {
+  const matches = workspaces.filter(
+    (workspace) => sameWorkspacePath(workspace.source.localFolder, repoPath)
+  );
+  if (matches.length > 1) {
+    throw new Error(
+      `Multiple DevPod workspaces reference '${repoPath}': ${matches.map((match) => match.id).join(", ")}`
+    );
+  }
+  return matches[0];
+}
+function runDevpodWorkspaceAction(action2, devpodId) {
+  const args = action2 === "delete" ? [action2, devpodId, "--ignore-not-found"] : [action2, devpodId];
+  const result = (0, import_node_child_process6.spawnSync)("devpod", args, { encoding: "utf-8" });
+  if (result.status !== 0) {
+    const detail = [result.error?.message, result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    throw new Error(`devpod ${action2} failed for '${devpodId}': ${detail || "unknown error"}`);
+  }
+}
+var import_node_child_process6;
+var init_devpod_workspaces = __esm({
+  "src/core/devpod-workspaces.ts"() {
+    "use strict";
+    import_node_child_process6 = require("child_process");
+    init_workspace();
+  }
+});
+
+// src/core/workspace-ownership.ts
+function commandError(command, repoPath, stderr) {
+  return new Error(
+    `${command} failed for '${repoPath}': ${stderr?.trim() || "not a Git repository"}`
+  );
+}
+function resolveGitCommonDir(repoPath) {
+  const result = (0, import_node_child_process7.spawnSync)("git", ["-C", repoPath, "rev-parse", "--git-common-dir"], {
+    encoding: "utf-8"
+  });
+  const output2 = result.stdout.trim();
+  if (result.status !== 0 || !output2) {
+    throw commandError("Could not resolve the Git common directory", repoPath, result.stderr);
+  }
+  return comparableWorkspacePath(import_node_path10.default.isAbsolute(output2) ? output2 : import_node_path10.default.resolve(repoPath, output2));
+}
+function listGitWorktrees(repoPath) {
+  const result = (0, import_node_child_process7.spawnSync)("git", ["-C", repoPath, "worktree", "list", "--porcelain"], {
+    encoding: "utf-8"
+  });
+  if (result.status !== 0) {
+    throw commandError("git worktree list", repoPath, result.stderr);
+  }
+  const worktrees = [];
+  let current = {};
+  const finish = () => {
+    if (!current.path) return;
+    worktrees.push({
+      path: comparableWorkspacePath(current.path),
+      branch: current.branch,
+      locked: current.locked ?? false,
+      prunable: current.prunable ?? false
+    });
+    current = {};
+  };
+  for (const line of `${result.stdout}
+`.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      finish();
+      current.path = line.slice("worktree ".length).trim();
+    } else if (line.startsWith("branch ")) {
+      current.branch = line.slice("branch ".length).trim().replace(/^refs\/heads\//, "");
+    } else if (line === "locked" || line.startsWith("locked ")) {
+      current.locked = true;
+    } else if (line === "prunable" || line.startsWith("prunable ")) {
+      current.prunable = true;
+    } else if (line === "") {
+      finish();
+    }
+  }
+  return worktrees;
+}
+function ownershipDirectory(repoPath) {
+  return import_node_path10.default.join(resolveGitCommonDir(repoPath), OWNERSHIP_DIR);
+}
+function validateWorkspace(value, label) {
+  if (typeof value !== "string" || wsFromBranch(value) !== value) {
+    throw new Error(`invalid workspace ownership ${label}`);
+  }
+  return value;
+}
+function validateTimestamp(value, label) {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+    throw new Error(`invalid workspace ownership ${label}`);
+  }
+  return value;
+}
+function validateRecord(value, expectedWorkspace) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("invalid workspace ownership record");
+  }
+  const candidate = value;
+  if (candidate.version !== OWNERSHIP_VERSION) {
+    throw new Error(`unsupported workspace ownership version '${String(candidate.version)}'`);
+  }
+  const workspace = validateWorkspace(candidate.workspace, "workspace");
+  if (expectedWorkspace && workspace !== expectedWorkspace) {
+    throw new Error(
+      `workspace ownership file '${expectedWorkspace}' contains identity '${workspace}'`
+    );
+  }
+  if (typeof candidate.worktreePath !== "string" || !import_node_path10.default.isAbsolute(candidate.worktreePath)) {
+    throw new Error("invalid workspace ownership worktreePath");
+  }
+  if (candidate.branch !== null && typeof candidate.branch !== "string") {
+    throw new Error("invalid workspace ownership branch");
+  }
+  const devpodId = validateWorkspace(candidate.devpodId, "devpodId");
+  return {
+    version: OWNERSHIP_VERSION,
+    workspace,
+    worktreePath: comparableWorkspacePath(candidate.worktreePath),
+    branch: candidate.branch,
+    devpodId,
+    createdAt: validateTimestamp(candidate.createdAt, "createdAt"),
+    updatedAt: validateTimestamp(candidate.updatedAt, "updatedAt")
+  };
+}
+function readRecordFile(filePath, expectedWorkspace) {
+  let parsed;
+  try {
+    parsed = JSON.parse(import_node_fs13.default.readFileSync(filePath, "utf-8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`invalid workspace ownership JSON at '${filePath}'`);
+    }
+    throw error;
+  }
+  return validateRecord(parsed, expectedWorkspace);
+}
+function listWorkspaceOwnership(repoPath) {
+  const directory = ownershipDirectory(repoPath);
+  return listWorkspaceOwnershipInDirectory(directory);
+}
+function listWorkspaceOwnershipInDirectory(directory) {
+  let entries;
+  try {
+    entries = import_node_fs13.default.readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => {
+    const workspace = entry.name.slice(0, -".json".length);
+    validateWorkspace(workspace, "filename");
+    return readRecordFile(import_node_path10.default.join(directory, entry.name), workspace);
+  });
+}
+function writeWorkspaceOwnershipInDirectory(directory, input2) {
+  const workspace = validateWorkspace(input2.workspace, "workspace");
+  const devpodId = validateWorkspace(input2.devpodId, "devpodId");
+  const worktreePath = comparableWorkspacePath(input2.worktreePath);
+  const filePath = import_node_path10.default.join(directory, `${workspace}.json`);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const records = listWorkspaceOwnershipInDirectory(directory);
+  const existing = records.find((record2) => record2.workspace === workspace);
+  if (existing && !sameWorkspacePath(existing.worktreePath, worktreePath)) {
+    throw new Error(
+      `Workspace '${workspace}' already belongs to '${existing.worktreePath}', refusing '${worktreePath}'.`
+    );
+  }
+  const pathOwner = records.find(
+    (record2) => record2.workspace !== workspace && sameWorkspacePath(record2.worktreePath, worktreePath)
+  );
+  if (pathOwner) {
+    throw new Error(
+      `Worktree '${worktreePath}' is already owned by workspace '${pathOwner.workspace}'.`
+    );
+  }
+  if (existing && existing.devpodId !== devpodId) {
+    throw new Error(
+      `Workspace '${workspace}' already owns DevPod '${existing.devpodId}', refusing '${devpodId}'.`
+    );
+  }
+  const record = {
+    version: OWNERSHIP_VERSION,
+    workspace,
+    worktreePath,
+    branch: input2.branch ?? null,
+    devpodId,
+    createdAt: existing?.createdAt ?? validateTimestamp(now, "createdAt"),
+    updatedAt: validateTimestamp(now, "updatedAt")
+  };
+  const tempPath = `${filePath}.${process.pid}.${(0, import_node_crypto3.randomUUID)()}.tmp`;
+  try {
+    import_node_fs13.default.writeFileSync(tempPath, `${JSON.stringify(record, null, 2)}
+`, {
+      encoding: "utf-8",
+      flag: "wx"
+    });
+    import_node_fs13.default.renameSync(tempPath, filePath);
+  } finally {
+    import_node_fs13.default.rmSync(tempPath, { force: true });
+  }
+  return record;
+}
+function removeWorkspaceOwnershipInDirectory(directory, workspace) {
+  const filePath = import_node_path10.default.join(directory, `${validateWorkspace(workspace, "workspace")}.json`);
+  try {
+    import_node_fs13.default.rmSync(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function sameOwnershipRecord(left, right) {
+  return left.version === right.version && left.workspace === right.workspace && sameWorkspacePath(left.worktreePath, right.worktreePath) && left.branch === right.branch && left.devpodId === right.devpodId && left.createdAt === right.createdAt && left.updatedAt === right.updatedAt;
+}
+function removeWorkspaceOwnershipIfMatchesInDirectory(directory, expected) {
+  const filePath = import_node_path10.default.join(
+    directory,
+    `${validateWorkspace(expected.workspace, "workspace")}.json`
+  );
+  let current;
+  try {
+    current = readRecordFile(filePath, expected.workspace);
+  } catch (error) {
+    if (error.code === "ENOENT") return "absent";
+    throw error;
+  }
+  if (!sameOwnershipRecord(current, expected)) return "changed";
+  import_node_fs13.default.rmSync(filePath);
+  return "removed";
+}
+function withWorkspaceOwnershipTransaction(repoPath, operation) {
+  const directory = ownershipDirectory(repoPath);
+  import_node_fs13.default.mkdirSync(directory, { recursive: true });
+  return withFileLockSync(
+    import_node_path10.default.join(directory, ".lock"),
+    { activity: "workspace ownership transaction", target: `'${repoPath}'`, waitMs: 5e3 },
+    () => operation({
+      list: () => listWorkspaceOwnershipInDirectory(directory),
+      write: (input2) => writeWorkspaceOwnershipInDirectory(directory, input2),
+      remove: (workspace) => removeWorkspaceOwnershipInDirectory(directory, workspace),
+      removeIfMatches: (expected) => removeWorkspaceOwnershipIfMatchesInDirectory(directory, expected)
+    })
+  );
+}
+function writeWorkspaceOwnership(repoPath, input2) {
+  return withWorkspaceOwnershipTransaction(repoPath, (transaction) => transaction.write(input2));
+}
+function removeWorkspaceOwnership(repoPath, workspace) {
+  return withWorkspaceOwnershipTransaction(
+    repoPath,
+    (transaction) => transaction.remove(workspace)
+  );
+}
+function inspectWorkspaceOwnership(record, worktrees, devpods) {
+  const worktree = worktrees.find(
+    (candidate) => sameWorkspacePath(candidate.path, record.worktreePath)
+  );
+  const devpodOwnership = devpods ? inspectDevpodWorkspaceOwnership(devpods, record.devpodId, record.worktreePath) : void 0;
+  const devpodStatus = devpodOwnership?.status ?? "unknown";
+  if (devpodStatus === "conflict") {
+    return { ownerStatus: "conflict", devpodStatus, worktree };
+  }
+  if (worktree?.locked) {
+    return { ownerStatus: "locked", devpodStatus, worktree };
+  }
+  if ((!worktree || worktree.prunable) && import_node_fs13.default.existsSync(record.worktreePath)) {
+    return { ownerStatus: "conflict", devpodStatus, worktree };
+  }
+  if (!worktree || worktree.prunable) {
+    return { ownerStatus: "missing", devpodStatus, worktree };
+  }
+  let persisted;
+  try {
+    persisted = readPersistedWorkspace(worktree.path);
+  } catch {
+    return { ownerStatus: "conflict", devpodStatus, worktree };
+  }
+  return {
+    ownerStatus: persisted === record.workspace ? "present" : "conflict",
+    devpodStatus,
+    worktree
+  };
+}
+function listMissingWorkspaceOwnership(repoPath) {
+  const worktrees = listGitWorktrees(repoPath);
+  return listWorkspaceOwnership(repoPath).filter(
+    (record) => inspectWorkspaceOwnership(record, worktrees, void 0).ownerStatus === "missing"
+  );
+}
+var import_node_child_process7, import_node_crypto3, import_node_fs13, import_node_path10, OWNERSHIP_VERSION, OWNERSHIP_DIR;
+var init_workspace_ownership = __esm({
+  "src/core/workspace-ownership.ts"() {
+    "use strict";
+    import_node_child_process7 = require("child_process");
+    import_node_crypto3 = require("crypto");
+    import_node_fs13 = __toESM(require("fs"));
+    import_node_path10 = __toESM(require("path"));
+    init_devpod_workspaces();
+    init_file_lock();
+    init_workspace();
+    OWNERSHIP_VERSION = 1;
+    OWNERSHIP_DIR = import_node_path10.default.join("devrouter", "workspaces");
+  }
+});
+
+// src/core/workspace-gc.ts
+function routesForOwner(routes, workspace, worktreePath) {
+  return routes.filter(
+    (route) => route.workspace === workspace && sameWorkspacePath(route.repoPath, worktreePath)
+  );
+}
+function inRepositoryWorkspaceScope(repoPath, worktreePath, livePaths) {
+  if (livePaths.some((candidate) => sameWorkspacePath(candidate, worktreePath))) return true;
+  const comparableRepo = comparableWorkspacePath(repoPath);
+  const comparableWorktree = comparableWorkspacePath(worktreePath);
+  const localRoot = import_node_path11.default.join(comparableRepo, "trees") + import_node_path11.default.sep;
+  if (comparableWorktree.startsWith(localRoot)) return true;
+  const legacyPrefix = `${import_node_path11.default.basename(comparableRepo)}-`;
+  return import_node_path11.default.dirname(comparableWorktree) === import_node_path11.default.dirname(comparableRepo) && import_node_path11.default.basename(comparableWorktree).startsWith(legacyPrefix);
+}
+function previewActions(devpodStatus, routeCount, includeRecord) {
+  const actions = [
+    {
+      resource: "devpod",
+      status: devpodStatus === "owned" ? "would-delete" : "already-absent"
+    },
+    {
+      resource: "routes",
+      status: routeCount > 0 ? "would-delete" : "already-absent",
+      count: routeCount
+    }
+  ];
+  if (includeRecord) actions.push({ resource: "record", status: "would-delete" });
+  return actions;
+}
+function ownedReason(ownerStatus) {
+  switch (ownerStatus) {
+    case "missing":
+      return "Ownership record is missing from live Git registration or marked prunable.";
+    case "present":
+      return "Registered worktree is present.";
+    case "locked":
+      return "Git worktree is locked and protected from garbage collection.";
+    case "conflict":
+      return "Ownership conflicts with live Git, persisted token, or DevPod source evidence.";
+  }
+}
+function ownedCandidate(record, worktrees, devpods, routes) {
+  const status = inspectWorkspaceOwnership(record, worktrees, devpods);
+  const routeCount = routesForOwner(routes, record.workspace, record.worktreePath).length;
+  const eligible = status.ownerStatus === "missing" && status.devpodStatus !== "conflict";
+  return {
+    kind: "owned",
+    workspace: record.workspace,
+    devpodId: record.devpodId,
+    worktreePath: record.worktreePath,
+    ownerStatus: status.ownerStatus,
+    devpodStatus: status.devpodStatus,
+    routeCount,
+    eligible,
+    reason: ownedReason(status.ownerStatus),
+    actions: eligible ? previewActions(status.devpodStatus, routeCount, true) : [
+      { resource: "devpod", status: "skipped" },
+      { resource: "routes", status: "skipped", count: routeCount },
+      { resource: "record", status: "skipped" }
+    ]
+  };
+}
+function legacyCandidates(repoPath, records, worktrees, devpods, routes) {
+  const livePaths = worktrees.map((worktree) => worktree.path);
+  const evidence = /* @__PURE__ */ new Map();
+  const isRecordedRoute = (workspace, worktreePath) => records.some(
+    (record) => record.workspace === workspace && sameWorkspacePath(record.worktreePath, worktreePath)
+  );
+  const isRecordedDevpod = (devpodId, worktreePath) => records.some(
+    (record) => record.devpodId === devpodId && sameWorkspacePath(record.worktreePath, worktreePath)
+  );
+  const key = (workspace, worktreePath) => `${workspace}\0${comparableWorkspacePath(worktreePath)}`;
+  for (const devpod of devpods) {
+    if (isRecordedDevpod(devpod.id, devpod.source.localFolder) || !inRepositoryWorkspaceScope(repoPath, devpod.source.localFolder, livePaths)) {
+      continue;
+    }
+    evidence.set(key(devpod.id, devpod.source.localFolder), {
+      workspace: devpod.id,
+      worktreePath: comparableWorkspacePath(devpod.source.localFolder),
+      devpodStatus: "owned",
+      routeCount: 0
+    });
+  }
+  for (const route of routes) {
+    if (!route.workspace || isRecordedRoute(route.workspace, route.repoPath) || !inRepositoryWorkspaceScope(repoPath, route.repoPath, livePaths)) {
+      continue;
+    }
+    const evidenceKey = key(route.workspace, route.repoPath);
+    const existing = evidence.get(evidenceKey);
+    evidence.set(evidenceKey, {
+      workspace: route.workspace,
+      worktreePath: comparableWorkspacePath(route.repoPath),
+      devpodStatus: existing?.devpodStatus ?? "absent",
+      routeCount: (existing?.routeCount ?? 0) + 1
+    });
+  }
+  return Array.from(evidence.values()).map((entry) => ({
+    kind: "legacy",
+    ...entry,
+    eligible: false,
+    reason: "Legacy workspace has no ownership record; use explicit workspace down or manual cleanup.",
+    actions: [
+      { resource: "devpod", status: "skipped" },
+      { resource: "routes", status: "skipped", count: entry.routeCount }
+    ]
+  }));
+}
+function revalidateCandidate(candidate, repoPath, transaction) {
+  const record = transaction.list().find((entry) => entry.workspace === candidate.workspace);
+  if (!record || !sameWorkspacePath(record.worktreePath, candidate.worktreePath) || record.devpodId !== candidate.devpodId) {
+    return {
+      status: "blocked",
+      candidate: {
+        ...candidate,
+        eligible: false,
+        reason: "Ownership record disappeared or changed before cleanup.",
+        actions: [
+          { resource: "devpod", status: "skipped" },
+          { resource: "routes", status: "skipped", count: candidate.routeCount },
+          { resource: "record", status: "skipped" }
+        ]
+      }
+    };
+  }
+  const fresh = ownedCandidate(
+    record,
+    listGitWorktrees(repoPath),
+    listDevpodWorkspaces(),
+    listHostRouteState()
+  );
+  if (fresh.eligible) return { status: "ready", candidate: fresh, record };
+  return {
+    status: "blocked",
+    candidate: {
+      ...fresh,
+      reason: `Ownership changed before cleanup: ${fresh.reason}`
+    }
+  };
+}
+function recheckDevpodOwnership(record) {
+  const ownership = inspectDevpodWorkspaceOwnership(
+    listDevpodWorkspaces(),
+    record.devpodId,
+    record.worktreePath
+  );
+  if (ownership.status === "conflict") {
+    throw new Error(ownership.reason);
+  }
+  return ownership.status;
+}
+function failedAction(resource, error) {
+  return {
+    resource,
+    status: "failed",
+    error: error instanceof Error ? error.message : String(error)
+  };
+}
+function applyCandidate(candidate, repoPath) {
+  try {
+    return withWorkspaceOwnershipTransaction(repoPath, (transaction) => {
+      let revalidated;
+      try {
+        revalidated = revalidateCandidate(candidate, repoPath, transaction);
+      } catch (error) {
+        return {
+          ...candidate,
+          actions: [
+            failedAction(
+              "record",
+              `Ownership revalidation failed: ${error instanceof Error ? error.message : String(error)}`
+            )
+          ]
+        };
+      }
+      if (revalidated.status === "blocked") return revalidated.candidate;
+      const { candidate: fresh, record } = revalidated;
+      const actions = [];
+      let devpodStatus;
+      try {
+        devpodStatus = recheckDevpodOwnership(record);
+        if (devpodStatus === "owned") runDevpodWorkspaceAction("delete", record.devpodId);
+      } catch (error) {
+        return { ...fresh, actions: [failedAction("devpod", error)] };
+      }
+      actions.push({
+        resource: "devpod",
+        status: devpodStatus === "owned" ? "deleted" : "already-absent"
+      });
+      try {
+        const routes = removeWorkspaceRoutesForWorktree(fresh.workspace, fresh.worktreePath);
+        actions.push({
+          resource: "routes",
+          status: routes.length > 0 ? "deleted" : "already-absent",
+          count: routes.length
+        });
+      } catch (error) {
+        return { ...fresh, actions: [...actions, failedAction("routes", error)] };
+      }
+      try {
+        const removal = transaction.removeIfMatches(record);
+        if (removal === "changed") {
+          throw new Error("Ownership record changed during cleanup; record was retained.");
+        }
+        actions.push({
+          resource: "record",
+          status: removal === "removed" ? "deleted" : "already-absent"
+        });
+      } catch (error) {
+        return { ...fresh, actions: [...actions, failedAction("record", error)] };
+      }
+      return { ...fresh, actions };
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      ...candidate,
+      actions: [failedAction("record", `Ownership transaction failed: ${detail}`)]
+    };
+  }
+}
+function summarizeGc(mode, candidates) {
+  return {
+    total: candidates.length,
+    eligible: candidates.filter((candidate) => candidate.eligible).length,
+    cleaned: mode === "apply" ? candidates.filter(
+      (candidate) => candidate.actions.some(
+        (action2) => action2.resource === "record" && (action2.status === "deleted" || action2.status === "already-absent")
+      )
+    ).length : 0,
+    blocked: candidates.filter((candidate) => !candidate.eligible).length,
+    errors: candidates.filter(
+      (candidate) => candidate.actions.some((action2) => action2.status === "failed")
+    ).length
+  };
+}
+function inspectWorkspaceGc(repo) {
+  const repoPath = comparableWorkspacePath(resolveRepoPath(repo));
+  const worktrees = listGitWorktrees(repoPath);
+  const records = listWorkspaceOwnership(repoPath);
+  const devpods = listDevpodWorkspaces();
+  const routes = listHostRouteState();
+  const candidates = [
+    ...records.map((record) => ownedCandidate(record, worktrees, devpods, routes)),
+    ...legacyCandidates(repoPath, records, worktrees, devpods, routes)
+  ];
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repoPath,
+    mode: "dry-run",
+    summary: summarizeGc("dry-run", candidates),
+    candidates
+  };
+}
+function applyWorkspaceGc(plan) {
+  const candidates = plan.candidates.map(
+    (candidate) => candidate.eligible ? applyCandidate(candidate, plan.repoPath) : candidate
+  );
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    repoPath: plan.repoPath,
+    mode: "apply",
+    summary: summarizeGc("apply", candidates),
+    candidates
+  };
+}
+var import_node_path11;
+var init_workspace_gc = __esm({
+  "src/core/workspace-gc.ts"() {
+    "use strict";
+    import_node_path11 = __toESM(require("path"));
+    init_devpod_workspaces();
+    init_host_routes();
+    init_repo_config();
+    init_route_state();
+    init_workspace();
+    init_workspace_ownership();
+  }
+});
+
 // src/core/doctor.ts
 function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -4123,11 +4759,11 @@ function inspectPostgresCredentials(repoPath, config) {
         parseErrors.push(`${app.name}: ${composeFile} (${message})`);
         continue;
       }
-      if (!import_node_fs13.default.existsSync(absolutePath)) {
+      if (!import_node_fs14.default.existsSync(absolutePath)) {
         continue;
       }
       try {
-        const raw = import_node_fs13.default.readFileSync(absolutePath, "utf-8");
+        const raw = import_node_fs14.default.readFileSync(absolutePath, "utf-8");
         const parsed = import_yaml4.default.parse(raw);
         const root = asRecord2(parsed);
         const services = asRecord2(root?.services);
@@ -4390,7 +5026,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.29" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.31" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -4420,9 +5056,9 @@ async function buildDoctorReport(options = {}) {
         (app) => app.docker.composeFiles.map((filePath) => ({
           app: app.name,
           filePath,
-          absolutePath: import_node_path10.default.resolve(repo.path, filePath)
+          absolutePath: import_node_path12.default.resolve(repo.path, filePath)
         }))
-      ).filter((entry) => !import_node_fs13.default.existsSync(entry.absolutePath));
+      ).filter((entry) => !import_node_fs14.default.existsSync(entry.absolutePath));
       addCheck(checks, {
         id: "repo.compose-files",
         level: missingComposeFiles.length === 0 ? "ok" : "error",
@@ -4465,8 +5101,8 @@ async function buildDoctorReport(options = {}) {
       const missingHostCwds = config.apps.filter((app) => app.runtime === "host").map((app) => ({
         app: app.name,
         cwd: app.hostRun.cwd,
-        absolutePath: import_node_path10.default.resolve(repo.path, app.hostRun.cwd)
-      })).filter((entry) => !import_node_fs13.default.existsSync(entry.absolutePath));
+        absolutePath: import_node_path12.default.resolve(repo.path, app.hostRun.cwd)
+      })).filter((entry) => !import_node_fs14.default.existsSync(entry.absolutePath));
       addCheck(checks, {
         id: "repo.host-cwd",
         level: missingHostCwds.length === 0 ? "ok" : "error",
@@ -4569,13 +5205,37 @@ async function buildDoctorReport(options = {}) {
     summary: staleCount === 0 ? "No stale host route entries detected." : `${staleCount} stale host route entr${staleCount === 1 ? "y" : "ies"} detected (dead PID).`,
     suggestion: staleCount === 0 ? void 0 : "Re-run the affected host app(s) or remove routes with: dev app rm <name> --repo <path> --keep-config"
   });
-  const orphanedWorkspaceRoutes = findOrphanedWorkspaceProxyRoutes();
-  addCheck(checks, {
-    id: "routes.orphaned-workspace-routes",
-    level: orphanedWorkspaceRoutes.length === 0 ? "ok" : "warn",
-    summary: orphanedWorkspaceRoutes.length === 0 ? "No orphaned workspace proxy routes detected." : `${orphanedWorkspaceRoutes.length} orphaned workspace proxy route entr${orphanedWorkspaceRoutes.length === 1 ? "y" : "ies"} detected (worktree removed without 'dev workspace down').`,
-    suggestion: orphanedWorkspaceRoutes.length === 0 ? void 0 : "Run: dev workspace down <workspace>"
-  });
+  let gitWorkspaceRepo = false;
+  try {
+    resolveGitCommonDir(resolvedRepoPath);
+    gitWorkspaceRepo = true;
+  } catch {
+  }
+  if (gitWorkspaceRepo) {
+    try {
+      const gc = inspectWorkspaceGc(resolvedRepoPath);
+      const needsAttention = gc.candidates.filter(
+        (candidate) => candidate.eligible || candidate.kind === "legacy" || candidate.ownerStatus === "conflict"
+      );
+      addCheck(checks, {
+        id: "workspace.ownership-cleanup",
+        level: needsAttention.length === 0 ? "ok" : "warn",
+        summary: needsAttention.length === 0 ? "No missing or legacy workspace ownership detected." : `${needsAttention.length} workspace ownership entr${needsAttention.length === 1 ? "y needs" : "ies need"} explicit cleanup review.`,
+        details: needsAttention.length === 0 ? void 0 : needsAttention.map(
+          (candidate) => `${candidate.workspace}: ${candidate.worktreePath} (${candidate.reason})`
+        ).join("\n"),
+        suggestion: needsAttention.length === 0 ? void 0 : `Run: dev workspace gc --repo ${resolvedRepoPath}`
+      });
+    } catch (error) {
+      addCheck(checks, {
+        id: "workspace.ownership-cleanup",
+        level: "warn",
+        summary: "Could not inspect workspace ownership cleanup state.",
+        details: error instanceof Error ? error.message : String(error),
+        suggestion: `Run: dev workspace gc --repo ${resolvedRepoPath}`
+      });
+    }
+  }
   const summary = collectSummary(checks);
   const nextSteps = collectNextSteps(checks, statusNextSteps);
   return {
@@ -4586,12 +5246,12 @@ async function buildDoctorReport(options = {}) {
     nextSteps
   };
 }
-var import_node_fs13, import_node_path10, import_yaml4, POSTGRES_DEFAULTS;
+var import_node_fs14, import_node_path12, import_yaml4, POSTGRES_DEFAULTS;
 var init_doctor = __esm({
   "src/core/doctor.ts"() {
     "use strict";
-    import_node_fs13 = __toESM(require("fs"));
-    import_node_path10 = __toESM(require("path"));
+    import_node_fs14 = __toESM(require("fs"));
+    import_node_path12 = __toESM(require("path"));
     import_yaml4 = __toESM(require("yaml"));
     init_docker();
     init_host_routes();
@@ -4604,6 +5264,8 @@ var init_doctor = __esm({
     init_status();
     init_tls();
     init_tool_diagnostics();
+    init_workspace_gc();
+    init_workspace_ownership();
     POSTGRES_DEFAULTS = {
       POSTGRES_USER: "prisma",
       POSTGRES_PASSWORD: "prisma",
@@ -4840,12 +5502,12 @@ function parseSsPortListeners(stdout, port) {
   return listeners;
 }
 function findPortListeners(port) {
-  const result = (0, import_node_child_process6.spawnSync)("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], {
+  const result = (0, import_node_child_process8.spawnSync)("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], {
     encoding: "utf-8"
   });
   if (result.error && result.error.code === "ENOENT") {
     if (process.platform === "linux") {
-      const ssResult = (0, import_node_child_process6.spawnSync)("ss", ["-H", "-lntp", "-p"], { encoding: "utf-8" });
+      const ssResult = (0, import_node_child_process8.spawnSync)("ss", ["-H", "-lntp", "-p"], { encoding: "utf-8" });
       if (ssResult.status === 0 && ssResult.stdout) {
         return parseSsPortListeners(ssResult.stdout, port);
       }
@@ -4874,11 +5536,11 @@ function findPortListeners(port) {
     };
   });
 }
-var import_node_child_process6;
+var import_node_child_process8;
 var init_ports = __esm({
   "src/util/ports.ts"() {
     "use strict";
-    import_node_child_process6 = require("child_process");
+    import_node_child_process8 = require("child_process");
   }
 });
 
@@ -5074,7 +5736,7 @@ async function runOpenCommand(name) {
     );
     return;
   }
-  const result = (0, import_node_child_process7.spawnSync)("open", [url], { encoding: "utf-8" });
+  const result = (0, import_node_child_process9.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"}`);
@@ -5082,11 +5744,11 @@ async function runOpenCommand(name) {
   process.stdout.write(`Opened ${url}
 `);
 }
-var import_node_child_process7;
+var import_node_child_process9;
 var init_open = __esm({
   "src/commands/open.ts"() {
     "use strict";
-    import_node_child_process7 = require("child_process");
+    import_node_child_process9 = require("child_process");
     init_docker();
     init_host_routes();
     init_repo_config();
@@ -5109,7 +5771,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_process8.spawn)("docker", args, { stdio: "inherit" });
+    const child = (0, import_node_child_process10.spawn)("docker", args, { stdio: "inherit" });
     const onSignal = () => {
       child.kill("SIGTERM");
     };
@@ -5123,17 +5785,17 @@ async function runLogsCommand(options) {
       });
     });
   } else {
-    const result = (0, import_node_child_process8.spawnSync)("docker", args, { stdio: "inherit" });
+    const result = (0, import_node_child_process10.spawnSync)("docker", args, { stdio: "inherit" });
     if (result.status !== 0) {
       throw new Error("Failed to retrieve router logs.");
     }
   }
 }
-var import_node_child_process8;
+var import_node_child_process10;
 var init_logs = __esm({
   "src/commands/logs.ts"() {
     "use strict";
-    import_node_child_process8 = require("child_process");
+    import_node_child_process10 = require("child_process");
     init_docker();
     init_router();
   }
@@ -5173,17 +5835,17 @@ function asRecord3(value) {
   return value;
 }
 function readJson(filePath) {
-  if (!import_node_fs14.default.existsSync(filePath)) {
+  if (!import_node_fs15.default.existsSync(filePath)) {
     return void 0;
   }
   try {
-    return JSON.parse(import_node_fs14.default.readFileSync(filePath, "utf-8"));
+    return JSON.parse(import_node_fs15.default.readFileSync(filePath, "utf-8"));
   } catch {
     return void 0;
   }
 }
 function relative(repoPath, filePath) {
-  return import_node_path11.default.relative(repoPath, filePath) || ".";
+  return import_node_path13.default.relative(repoPath, filePath) || ".";
 }
 function redactEnvAssignments(value) {
   return value.replace(
@@ -5224,7 +5886,7 @@ function inspectPackageManager(repoPath, pkg) {
     ["bun.lock", "bun"]
   ];
   for (const [fileName, name] of lockfiles) {
-    if (import_node_fs14.default.existsSync(import_node_path11.default.join(repoPath, fileName))) {
+    if (import_node_fs15.default.existsSync(import_node_path13.default.join(repoPath, fileName))) {
       return { name, source: fileName };
     }
   }
@@ -5239,9 +5901,9 @@ function inspectNode(repoPath, pkg) {
   if (typeof engines?.node === "string") {
     return { version: engines.node, source: "package.json:engines.node" };
   }
-  const nvmrc = import_node_path11.default.join(repoPath, ".nvmrc");
-  if (import_node_fs14.default.existsSync(nvmrc)) {
-    const version = import_node_fs14.default.readFileSync(nvmrc, "utf-8").trim();
+  const nvmrc = import_node_path13.default.join(repoPath, ".nvmrc");
+  if (import_node_fs15.default.existsSync(nvmrc)) {
+    const version = import_node_fs15.default.readFileSync(nvmrc, "utf-8").trim();
     return { version, source: ".nvmrc" };
   }
   return void 0;
@@ -5302,7 +5964,7 @@ function configuredComposeFiles(repoPath) {
     const files = config.apps.filter(
       (app) => app.runtime === "docker"
     ).flatMap((app) => app.docker.composeFiles).filter(
-      (fileName) => !import_node_path11.default.isAbsolute(fileName) && !import_node_path11.default.normalize(fileName).startsWith("..")
+      (fileName) => !import_node_path13.default.isAbsolute(fileName) && !import_node_path13.default.normalize(fileName).startsWith("..")
     );
     return Array.from(new Set(files));
   } catch {
@@ -5320,7 +5982,7 @@ function composeFiles(repoPath) {
     ...configuredComposeFiles(repoPath)
   ];
   return Array.from(new Set(candidates)).filter(
-    (fileName) => import_node_fs14.default.existsSync(import_node_path11.default.join(repoPath, fileName))
+    (fileName) => import_node_fs15.default.existsSync(import_node_path13.default.join(repoPath, fileName))
   );
 }
 function stringArray(value) {
@@ -5358,7 +6020,7 @@ function inspectServices(repoPath) {
   const services = [];
   for (const fileName of composeFiles(repoPath)) {
     try {
-      const parsed = import_yaml5.default.parse(import_node_fs14.default.readFileSync(import_node_path11.default.join(repoPath, fileName), "utf-8"));
+      const parsed = import_yaml5.default.parse(import_node_fs15.default.readFileSync(import_node_path13.default.join(repoPath, fileName), "utf-8"));
       const serviceMap = asRecord3(asRecord3(parsed)?.services);
       for (const [name, value] of Object.entries(serviceMap ?? {})) {
         const service = asRecord3(value);
@@ -5393,8 +6055,8 @@ function inspectServices(repoPath) {
   return services;
 }
 function inspectEnvFiles(repoPath) {
-  const files = import_node_fs14.default.readdirSync(repoPath).filter((fileName) => /^\.env(\.|$)/.test(fileName)).sort().map((fileName) => {
-    const content = import_node_fs14.default.readFileSync(import_node_path11.default.join(repoPath, fileName), "utf-8");
+  const files = import_node_fs15.default.readdirSync(repoPath).filter((fileName) => /^\.env(\.|$)/.test(fileName)).sort().map((fileName) => {
+    const content = import_node_fs15.default.readFileSync(import_node_path13.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 };
   });
@@ -5408,18 +6070,18 @@ function inspectEnvFiles(repoPath) {
   };
 }
 function inspectDevcontainer(repoPath) {
-  const dir = import_node_path11.default.join(repoPath, ".devcontainer");
-  if (!import_node_fs14.default.existsSync(dir)) {
+  const dir = import_node_path13.default.join(repoPath, ".devcontainer");
+  if (!import_node_fs15.default.existsSync(dir)) {
     return { exists: false, files: [] };
   }
   return {
     exists: true,
-    files: import_node_fs14.default.readdirSync(dir).filter((fileName) => import_node_fs14.default.statSync(import_node_path11.default.join(dir, fileName)).isFile()).sort().map((fileName) => `.devcontainer/${fileName}`)
+    files: import_node_fs15.default.readdirSync(dir).filter((fileName) => import_node_fs15.default.statSync(import_node_path13.default.join(dir, fileName)).isFile()).sort().map((fileName) => `.devcontainer/${fileName}`)
   };
 }
 function inspectDevrouter(repoPath) {
   const configPath = getRepoConfigPath(repoPath);
-  if (!import_node_fs14.default.existsSync(configPath)) {
+  if (!import_node_fs15.default.existsSync(configPath)) {
     return {
       exists: false,
       configPath,
@@ -5463,15 +6125,15 @@ function inspectAgentGuidance(repoPath) {
     ["AGENTS.md", "agents"],
     ["CLAUDE.md", "claude"]
   ]) {
-    if (import_node_fs14.default.existsSync(import_node_path11.default.join(repoPath, fileName))) {
+    if (import_node_fs15.default.existsSync(import_node_path13.default.join(repoPath, fileName))) {
       results.push({ path: fileName, kind });
     }
   }
-  const skillsDir = import_node_path11.default.join(repoPath, ".agents", "skills");
-  if (import_node_fs14.default.existsSync(skillsDir)) {
-    for (const name of import_node_fs14.default.readdirSync(skillsDir).sort()) {
-      const skillPath = import_node_path11.default.join(skillsDir, name, "SKILL.md");
-      if (import_node_fs14.default.existsSync(skillPath)) {
+  const skillsDir = import_node_path13.default.join(repoPath, ".agents", "skills");
+  if (import_node_fs15.default.existsSync(skillsDir)) {
+    for (const name of import_node_fs15.default.readdirSync(skillsDir).sort()) {
+      const skillPath = import_node_path13.default.join(skillsDir, name, "SKILL.md");
+      if (import_node_fs15.default.existsSync(skillPath)) {
         results.push({ path: relative(repoPath, skillPath), kind: "skill" });
       }
     }
@@ -5514,7 +6176,7 @@ function buildIssues(report) {
 }
 function inspectRepo(options = {}) {
   const repoPath = resolveRepoPath(options.repo);
-  const pkg = readJson(import_node_path11.default.join(repoPath, "package.json"));
+  const pkg = readJson(import_node_path13.default.join(repoPath, "package.json"));
   const scripts = inspectScripts(pkg);
   const reportWithoutIssues = {
     repoPath,
@@ -5533,12 +6195,12 @@ function inspectRepo(options = {}) {
     issues: buildIssues(reportWithoutIssues)
   };
 }
-var import_node_fs14, import_node_path11, import_yaml5;
+var import_node_fs15, import_node_path13, import_yaml5;
 var init_repo_inspect = __esm({
   "src/core/repo-inspect.ts"() {
     "use strict";
-    import_node_fs14 = __toESM(require("fs"));
-    import_node_path11 = __toESM(require("path"));
+    import_node_fs15 = __toESM(require("fs"));
+    import_node_path13 = __toESM(require("path"));
     import_yaml5 = __toESM(require("yaml"));
     init_repo_config();
   }
@@ -5716,7 +6378,7 @@ function requiredFileChecks(repoPath) {
     ".devcontainer/docker-compose.yml",
     ".devrouter.yml"
   ];
-  const missing = required.filter((fileName) => !import_node_fs15.default.existsSync(import_node_path12.default.join(repoPath, fileName)));
+  const missing = required.filter((fileName) => !import_node_fs16.default.existsSync(import_node_path14.default.join(repoPath, fileName)));
   return {
     id: "repo.devcontainer.verify-files",
     level: missing.length === 0 ? "ok" : "error",
@@ -5781,7 +6443,7 @@ function routeUrl2(host) {
   return `${isTLSEnabled() ? "https" : "http"}://${host}`;
 }
 function curlRoute(host) {
-  const result = (0, import_node_child_process9.spawnSync)("curl", ["-k", "-fsS", "--max-time", "5", routeUrl2(host)], {
+  const result = (0, import_node_child_process11.spawnSync)("curl", ["-k", "-fsS", "--max-time", "5", routeUrl2(host)], {
     encoding: "utf-8"
   });
   if (result.status === 0) {
@@ -5955,13 +6617,13 @@ async function verifyDevcontainer(options = {}) {
     nextSteps: collectNextSteps3(checks)
   };
 }
-var import_node_child_process9, import_node_fs15, import_node_path12;
+var import_node_child_process11, import_node_fs16, import_node_path14;
 var init_devcontainer_verify = __esm({
   "src/core/devcontainer-verify.ts"() {
     "use strict";
-    import_node_child_process9 = require("child_process");
-    import_node_fs15 = __toESM(require("fs"));
-    import_node_path12 = __toESM(require("path"));
+    import_node_child_process11 = require("child_process");
+    import_node_fs16 = __toESM(require("fs"));
+    import_node_path14 = __toESM(require("path"));
     init_capabilities();
     init_concurrency();
     init_doctor();
@@ -5984,27 +6646,39 @@ function majorVersion(value, fallback) {
 function devrouterVersion(value) {
   return value && /^\d+\.\d+\.\d+$/.test(value) ? value : DEFAULT_DEVROUTER_VERSION;
 }
-function inferDevScript(repo) {
+function escapeExtendedRegex(value) {
+  return value.replace(/[\\.^$|?*+()[\]{}]/g, "\\$&");
+}
+function inferDevProcess(repo) {
   const script = repo.scripts.find((entry) => entry.name === "dev") ?? repo.scripts.find((entry) => entry.name.endsWith(":dev"));
-  if (!script) {
-    return "pnpm dev";
-  }
-  return script.name === "dev" ? "pnpm dev" : `pnpm run -- ${shellSingleQuote(script.name)}`;
+  const scriptName = script?.name ?? "dev";
+  return {
+    command: scriptName === "dev" ? "pnpm dev" : `pnpm run -- ${shellSingleQuote(scriptName)}`,
+    match: `pnpm(\\.cjs)? .*${escapeExtendedRegex(scriptName)}`
+  };
 }
 function inferPort2(repo) {
   return repo.apps.find((app) => app.port)?.port ?? 3e3;
 }
-function renderDockerfile(nodeMajor, pnpmVersion) {
+function renderDockerfile(nodeMajor, pnpmVersion, version) {
   const pnpmPackageSpec = `pnpm@${pnpmVersion}`;
+  const devrouterPackageSpec = `@devrouter/cli@${version}`;
+  const devrouterTarball = `devrouter-cli-${version}.tgz`;
   return `# ${MANAGED_MARKER}
 FROM node:${nodeMajor}-bookworm-slim
 
 RUN apt-get update \\
-  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl \\
+  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl tar 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
 `;
 }
@@ -6140,7 +6814,7 @@ fi
 function shellSingleQuote(value) {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
-function renderPostStart(devCommand) {
+function renderPostStart(devProcess) {
   return `#!/usr/bin/env bash
 # ${MANAGED_MARKER}
 set -euo pipefail
@@ -6151,11 +6825,11 @@ set -a
 . .devcontainer/devcontainer.env
 set +a
 
-if pgrep -f ${shellSingleQuote(devCommand)} >/dev/null 2>&1; then
-  exit 0
-fi
-
-setsid bash -lc ${shellSingleQuote(devCommand)} >/tmp/devrouter-app.log 2>&1 </dev/null &
+devrouter-process ensure \\
+  --name app \\
+  --match ${shellSingleQuote(devProcess.match)} \\
+  --log /tmp/devrouter-app.log \\
+  -- bash -lc ${shellSingleQuote(devProcess.command)}
 `;
 }
 function renderDevrouter(projectName, port, version) {
@@ -6268,11 +6942,11 @@ function packageManagerIssues(repo) {
 }
 function plannedFiles(repoPath, version) {
   const repo = inspectRepo({ repo: repoPath });
-  const projectName = sanitizeProjectName(import_node_path13.default.basename(repo.repoPath));
+  const projectName = sanitizeProjectName(import_node_path15.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);
-  const devCommand = inferDevScript(repo);
+  const devProcess = inferDevProcess(repo);
   const issues = packageManagerIssues(repo);
   return {
     projectName,
@@ -6280,7 +6954,7 @@ function plannedFiles(repoPath, version) {
     files: [
       {
         relativePath: ".devcontainer/Dockerfile",
-        content: renderDockerfile(nodeMajor, pnpmVersion)
+        content: renderDockerfile(nodeMajor, pnpmVersion, version)
       },
       { relativePath: ".devcontainer/docker-compose.yml", content: renderCompose(projectName) },
       {
@@ -6304,7 +6978,7 @@ function plannedFiles(repoPath, version) {
       },
       {
         relativePath: ".devcontainer/post-start.sh",
-        content: renderPostStart(devCommand),
+        content: renderPostStart(devProcess),
         executable: true
       },
       { relativePath: ".devcontainer/README.md", content: renderReadme(projectName) },
@@ -6313,8 +6987,8 @@ function plannedFiles(repoPath, version) {
   };
 }
 function classifyFile(repoPath, file) {
-  const absolutePath = import_node_path13.default.join(repoPath, file.relativePath);
-  if (!import_node_fs16.default.existsSync(absolutePath)) {
+  const absolutePath = import_node_path15.default.join(repoPath, file.relativePath);
+  if (!import_node_fs17.default.existsSync(absolutePath)) {
     return {
       path: file.relativePath,
       action: "create",
@@ -6322,7 +6996,7 @@ function classifyFile(repoPath, file) {
       bytes: Buffer.byteLength(file.content)
     };
   }
-  const current = import_node_fs16.default.readFileSync(absolutePath, "utf-8");
+  const current = import_node_fs17.default.readFileSync(absolutePath, "utf-8");
   if (!current.includes(MANAGED_MARKER)) {
     return {
       path: file.relativePath,
@@ -6379,11 +7053,11 @@ function buildPlan(repoPath, dryRun, version) {
   };
 }
 function writeFile(repoPath, file) {
-  const absolutePath = import_node_path13.default.join(repoPath, file.relativePath);
-  import_node_fs16.default.mkdirSync(import_node_path13.default.dirname(absolutePath), { recursive: true });
-  import_node_fs16.default.writeFileSync(absolutePath, file.content, "utf-8");
+  const absolutePath = import_node_path15.default.join(repoPath, file.relativePath);
+  import_node_fs17.default.mkdirSync(import_node_path15.default.dirname(absolutePath), { recursive: true });
+  import_node_fs17.default.writeFileSync(absolutePath, file.content, "utf-8");
   if (file.executable) {
-    import_node_fs16.default.chmodSync(absolutePath, 493);
+    import_node_fs17.default.chmodSync(absolutePath, 493);
   }
 }
 function writeDevcontainer(options = {}) {
@@ -6421,12 +7095,12 @@ function writeDevcontainer(options = {}) {
     nextSteps: postWriteNextSteps(repoPath)
   };
 }
-var import_node_fs16, import_node_path13, MANAGED_MARKER, DEFAULT_DEVROUTER_VERSION, DEFAULT_PNPM_VERSION, VALID_PACKAGE_VERSION_RE;
+var import_node_fs17, import_node_path15, MANAGED_MARKER, DEFAULT_DEVROUTER_VERSION, DEFAULT_PNPM_VERSION, VALID_PACKAGE_VERSION_RE;
 var init_devcontainer_write = __esm({
   "src/core/devcontainer-write.ts"() {
     "use strict";
-    import_node_fs16 = __toESM(require("fs"));
-    import_node_path13 = __toESM(require("path"));
+    import_node_fs17 = __toESM(require("fs"));
+    import_node_path15 = __toESM(require("path"));
     init_repo_config();
     init_repo_inspect();
     init_workspace();
@@ -6753,7 +7427,7 @@ function sanitizeRouterId(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function repoHash(repoPath) {
-  return (0, import_node_crypto3.createHash)("sha1").update(import_node_path14.default.resolve(repoPath)).digest("hex").slice(0, 12);
+  return (0, import_node_crypto4.createHash)("sha1").update(import_node_path16.default.resolve(repoPath)).digest("hex").slice(0, 12);
 }
 function asDockerApp(app) {
   return app.runtime === "docker";
@@ -6832,11 +7506,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_path14.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
-  import_node_fs17.default.mkdirSync(cachePath, { recursive: true });
-  const overlayPath = import_node_path14.default.join(cachePath, "compose.devrouter.yml");
+  const cachePath = import_node_path16.default.join(CACHE_DIR, repoHash(repoPath), sanitizeRouterId(appName));
+  import_node_fs18.default.mkdirSync(cachePath, { recursive: true });
+  const overlayPath = import_node_path16.default.join(cachePath, "compose.devrouter.yml");
   const overlayDocument = buildOverlayDocument(dockerApps, publishTcpPorts);
-  import_node_fs17.default.writeFileSync(overlayPath, import_yaml6.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
+  import_node_fs18.default.writeFileSync(overlayPath, import_yaml6.default.stringify(overlayDocument, { lineWidth: 0 }), "utf-8");
   return {
     overlayPath,
     composeFiles: ensureComposeFiles(dockerApps),
@@ -6850,7 +7524,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_process10.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process12.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -6878,7 +7552,7 @@ function queryRunningComposeServices(repoPath, composeFiles2, overlayPath, servi
     "--services",
     ...services
   ];
-  const result = (0, import_node_child_process10.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process12.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -6904,7 +7578,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_process10.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process12.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -6930,7 +7604,7 @@ function runDockerComposeLogs(repoPath, composeFiles2, overlayPath, services, ta
     String(tail),
     ...services
   ];
-  (0, import_node_child_process10.spawnSync)("docker", args, {
+  (0, import_node_child_process12.spawnSync)("docker", args, {
     stdio: "inherit",
     cwd: repoPath
   });
@@ -6942,7 +7616,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_process10.spawnSync)("docker", args, {
+  const result = (0, import_node_child_process12.spawnSync)("docker", args, {
     encoding: "utf-8",
     cwd: repoPath
   });
@@ -6956,14 +7630,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_process10, import_node_crypto3, import_node_fs17, import_node_path14, import_yaml6;
+var import_node_child_process12, import_node_crypto4, import_node_fs18, import_node_path16, import_yaml6;
 var init_docker_run = __esm({
   "src/core/docker-run.ts"() {
     "use strict";
-    import_node_child_process10 = require("child_process");
-    import_node_crypto3 = require("crypto");
-    import_node_fs17 = __toESM(require("fs"));
-    import_node_path14 = __toESM(require("path"));
+    import_node_child_process12 = require("child_process");
+    import_node_crypto4 = require("crypto");
+    import_node_fs18 = __toESM(require("fs"));
+    import_node_path16 = __toESM(require("path"));
     import_yaml6 = __toESM(require("yaml"));
     init_docker_error_guidance();
     init_paths();
@@ -7053,7 +7727,7 @@ function isProcessRunning(pid) {
   }
 }
 function readProcessTree(rootPid) {
-  const result = (0, import_node_child_process11.spawnSync)("ps", ["-ax", "-o", "pid=,ppid="], { encoding: "utf-8" });
+  const result = (0, import_node_child_process13.spawnSync)("ps", ["-ax", "-o", "pid=,ppid="], { encoding: "utf-8" });
   if (result.status !== 0) {
     return [rootPid];
   }
@@ -7164,12 +7838,12 @@ function detectListeningPorts(pids) {
   if (pids.length === 0) {
     return [];
   }
-  const result = (0, import_node_child_process11.spawnSync)("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-a", "-p", pids.join(",")], {
+  const result = (0, import_node_child_process13.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_process11.spawnSync)("ss", ["-H", "-lntp", "-p"], { encoding: "utf-8" });
+      const ssResult = (0, import_node_child_process13.spawnSync)("ss", ["-H", "-lntp", "-p"], { encoding: "utf-8" });
       if (ssResult.status === 0 && ssResult.stdout) {
         return parseSsListeningPorts(ssResult.stdout, new Set(pids));
       }
@@ -7228,7 +7902,7 @@ async function runHostApp(repoPath, app, extraEnv = {}, secretManager, env, work
     app.hostRun.command,
     true
   ) : app.hostRun.command;
-  const child = (0, import_node_child_process11.spawn)(spawnCommand, {
+  const child = (0, import_node_child_process13.spawn)(spawnCommand, {
     cwd: commandCwd,
     stdio: "inherit",
     shell: true,
@@ -7611,7 +8285,7 @@ async function execWithAppEnv(options) {
           options.command[0],
           true
         );
-        child = (0, import_node_child_process11.spawn)(wrapped, {
+        child = (0, import_node_child_process13.spawn)(wrapped, {
           cwd: deps.repoPath,
           stdio: "inherit",
           shell: true,
@@ -7625,7 +8299,7 @@ async function execWithAppEnv(options) {
           false
         );
         const [cmd, ...wrappedArgs] = wrapped;
-        child = (0, import_node_child_process11.spawn)(cmd, wrappedArgs, {
+        child = (0, import_node_child_process13.spawn)(cmd, wrappedArgs, {
           cwd: deps.repoPath,
           stdio: "inherit",
           shell: false,
@@ -7633,7 +8307,7 @@ async function execWithAppEnv(options) {
         });
       }
     } else if (options.shell) {
-      child = (0, import_node_child_process11.spawn)(options.command[0], {
+      child = (0, import_node_child_process13.spawn)(options.command[0], {
         cwd: deps.repoPath,
         stdio: "inherit",
         shell: true,
@@ -7641,7 +8315,7 @@ async function execWithAppEnv(options) {
       });
     } else {
       const [command, ...args] = options.command;
-      child = (0, import_node_child_process11.spawn)(command, args, {
+      child = (0, import_node_child_process13.spawn)(command, args, {
         cwd: deps.repoPath,
         stdio: "inherit",
         shell: false,
@@ -7662,11 +8336,11 @@ async function execWithAppEnv(options) {
     deps.stopDeps();
   }
 }
-var import_node_child_process11, import_node_net, import_node_process, import_promises, POLL_INTERVAL_MS, DEFAULT_PORT_TIMEOUT_MS, PROCESS_TERMINATION_GRACE_MS;
+var import_node_child_process13, import_node_net, import_node_process, import_promises, POLL_INTERVAL_MS, DEFAULT_PORT_TIMEOUT_MS, PROCESS_TERMINATION_GRACE_MS;
 var init_app_run = __esm({
   "src/core/app-run.ts"() {
     "use strict";
-    import_node_child_process11 = require("child_process");
+    import_node_child_process13 = require("child_process");
     import_node_net = __toESM(require("net"));
     import_node_process = require("process");
     import_promises = require("readline/promises");
@@ -7796,47 +8470,13 @@ var init_tls2 = __esm({
 });
 
 // src/core/workspace-ensure.ts
-function selectDevpodWorkspace(workspaces, repoPath) {
-  const matches = workspaces.filter(
-    (workspace) => sameWorkspacePath(workspace.source.localFolder, repoPath)
-  );
-  if (matches.length > 1) {
-    throw new Error(
-      `Multiple DevPod workspaces reference '${repoPath}': ${matches.map((match) => match.id).join(", ")}`
-    );
-  }
-  return matches[0];
-}
-function listDevpodWorkspaces() {
-  const result = (0, import_node_child_process12.spawnSync)("devpod", ["list", "--output", "json"], { encoding: "utf-8" });
-  if (result.status !== 0) {
-    const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
-    throw new Error(`devpod list failed: ${details || "devpod is not installed or unavailable"}`);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(result.stdout);
-  } catch {
-    throw new Error("devpod list returned invalid JSON.");
-  }
-  if (!Array.isArray(parsed)) {
-    throw new Error("devpod list returned an unexpected response.");
-  }
-  return parsed.map((entry) => {
-    const candidate = entry;
-    if (typeof candidate.id !== "string" || !candidate.source || typeof candidate.source.localFolder !== "string") {
-      throw new Error("devpod list returned a workspace without id/source.localFolder.");
-    }
-    return candidate;
-  });
-}
 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_path17.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_path17.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}.`);
   }
@@ -7854,7 +8494,7 @@ function validateWorkspaceContainers(containers, options) {
   const owned = containers.filter((container) => {
     const workingDir = container.labels["com.docker.compose.project.working_dir"];
     return Boolean(
-      workingDir && sameWorkspacePath(workingDir, import_node_path15.default.join(options.repoPath, ".devcontainer"))
+      workingDir && sameWorkspacePath(workingDir, import_node_path17.default.join(options.repoPath, ".devcontainer"))
     );
   });
   const appContainers = owned.filter(
@@ -7902,7 +8542,7 @@ function validateWorkspaceContainers(containers, options) {
   return { id: appContainer.id, workspacePath: repoMount.Destination };
 }
 function inspectWorkspaceContainers() {
-  const listed = (0, import_node_child_process12.spawnSync)("docker", ["ps", "-a", "--format", "{{.ID}}"], {
+  const listed = (0, import_node_child_process14.spawnSync)("docker", ["ps", "-a", "--format", "{{.ID}}"], {
     encoding: "utf-8"
   });
   if (listed.status !== 0) {
@@ -7914,7 +8554,7 @@ function inspectWorkspaceContainers() {
   if (ids.length === 0) {
     return [];
   }
-  const inspected = (0, import_node_child_process12.spawnSync)("docker", ["inspect", "--format", SAFE_INSPECT_TEMPLATE, ...ids], {
+  const inspected = (0, import_node_child_process14.spawnSync)("docker", ["inspect", "--format", SAFE_INSPECT_TEMPLATE, ...ids], {
     encoding: "utf-8"
   });
   if (inspected.status !== 0) {
@@ -7927,18 +8567,18 @@ function inspectWorkspaceContainers() {
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function waitForContainerPreflight(repoPath, gitCommonDir2, workspace, upstreamHosts, timeoutMs) {
+async function waitForContainerPreflight(repoPath, gitCommonDir, workspace, upstreamHosts, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let lastError;
   do {
     try {
       const appContainer = validateWorkspaceContainers(inspectWorkspaceContainers(), {
         repoPath,
-        gitCommonDir: gitCommonDir2,
+        gitCommonDir,
         workspace,
         upstreamHosts
       });
-      const workspaceEnv = (0, import_node_child_process12.spawnSync)("docker", ["exec", appContainer.id, "printenv", "WORKSPACE"], {
+      const workspaceEnv = (0, import_node_child_process14.spawnSync)("docker", ["exec", appContainer.id, "printenv", "WORKSPACE"], {
         encoding: "utf-8"
       });
       if (workspaceEnv.status !== 0 || workspaceEnv.stdout.trim() !== workspace) {
@@ -7946,7 +8586,7 @@ async function waitForContainerPreflight(repoPath, gitCommonDir2, workspace, ups
           `Workspace app container must expose WORKSPACE='${workspace}' (got '${workspaceEnv.stdout.trim() || "(empty)"}').`
         );
       }
-      const devrouterWorkspaceEnv = (0, import_node_child_process12.spawnSync)(
+      const devrouterWorkspaceEnv = (0, import_node_child_process14.spawnSync)(
         "docker",
         ["exec", appContainer.id, "printenv", "DEVROUTER_WORKSPACE"],
         { encoding: "utf-8" }
@@ -7954,7 +8594,7 @@ async function waitForContainerPreflight(repoPath, gitCommonDir2, workspace, ups
       if (devrouterWorkspaceEnv.status !== 0 || devrouterWorkspaceEnv.stdout.trim() !== workspace) {
         throw new Error(`Workspace app container must expose DEVROUTER_WORKSPACE='${workspace}'.`);
       }
-      const gitCheck = (0, import_node_child_process12.spawnSync)(
+      const gitCheck = (0, import_node_child_process14.spawnSync)(
         "docker",
         [
           "exec",
@@ -8020,7 +8660,7 @@ async function waitForHttpRoutes(apps, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   do {
     for (const [name, app] of pending) {
-      const result = (0, import_node_child_process12.spawnSync)(
+      const result = (0, import_node_child_process14.spawnSync)(
         "curl",
         [
           "-k",
@@ -8079,17 +8719,6 @@ function resolveIdentity(repoPath) {
     hadExactDevpod: Boolean(existingDevpod)
   };
 }
-function gitCommonDir(repoPath) {
-  const result = (0, import_node_child_process12.spawnSync)(
-    "git",
-    ["-C", repoPath, "rev-parse", "--path-format=absolute", "--git-common-dir"],
-    { encoding: "utf-8" }
-  );
-  if (result.status !== 0 || !result.stdout.trim()) {
-    throw new Error(`Could not resolve the Git common directory for '${repoPath}'.`);
-  }
-  return comparableWorkspacePath(result.stdout.trim());
-}
 function startDevpod(repoPath, workspace, commonDir, recreate = false) {
   const args = [
     "up",
@@ -8105,7 +8734,7 @@ function startDevpod(repoPath, workspace, commonDir, recreate = false) {
   if (recreate) {
     args.push("--recreate");
   }
-  const result = (0, import_node_child_process12.spawnSync)("devpod", args, {
+  const result = (0, import_node_child_process14.spawnSync)("devpod", args, {
     stdio: "inherit",
     env: {
       ...process.env,
@@ -8127,7 +8756,7 @@ function assertDevpodAttachment(repoPath, workspace) {
 }
 function openUrls(urls) {
   for (const url of urls) {
-    const opened = (0, import_node_child_process12.spawnSync)("open", [url], { encoding: "utf-8" });
+    const opened = (0, import_node_child_process14.spawnSync)("open", [url], { encoding: "utf-8" });
     if (opened.status !== 0) {
       process.stderr.write(`Warning: could not open '${url}'.
 `);
@@ -8139,12 +8768,19 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
   if (!isLinkedWorktree(repoPath)) {
     throw new Error(`workspace ensure requires a linked Git worktree (got '${repoPath}').`);
   }
+  const missingOwners = listMissingWorkspaceOwnership(repoPath);
+  if (missingOwners.length > 0) {
+    process.stderr.write(
+      `Warning: ${missingOwners.length} managed workspace owner${missingOwners.length === 1 ? " is" : "s are"} missing. Review: dev workspace gc --repo ${repoPath}
+`
+    );
+  }
   return withWorkspaceLifecycleLock(repoPath, async () => {
     let environmentStarted = false;
     try {
       const { workspace, hadExactDevpod } = resolveIdentity(repoPath);
-      const overlayPath = import_node_path15.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
-      if (!import_node_fs18.default.existsSync(overlayPath)) {
+      const overlayPath = import_node_path17.default.join(repoPath, ".devcontainer", DEVCONTAINER_OVERLAY);
+      if (!import_node_fs19.default.existsSync(overlayPath)) {
         throw new Error(`Missing required DevPod compose overlay: ${overlayPath}`);
       }
       const runtime = loadRuntimeConfig(repoPath, workspace);
@@ -8157,12 +8793,20 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           );
         }
       }
-      const commonDir = gitCommonDir(repoPath);
+      const commonDir = resolveGitCommonDir(repoPath);
       const upstreamHosts = parsedUpstreams.map((upstream) => upstream.host);
+      const ownership = {
+        workspace,
+        worktreePath: repoPath,
+        branch: currentBranch(repoPath),
+        devpodId: workspace
+      };
+      writeWorkspaceOwnership(repoPath, ownership);
       const startAndProveAttachment = (recreate = false) => {
         startDevpod(repoPath, workspace, commonDir, recreate);
         environmentStarted = true;
         assertDevpodAttachment(repoPath, workspace);
+        writeWorkspaceOwnership(repoPath, ownership);
       };
       const recreateAndWait = async () => {
         startAndProveAttachment(true);
@@ -8240,19 +8884,21 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
     }
   });
 }
-var import_node_child_process12, import_node_fs18, import_node_path15, DEVCONTAINER_OVERLAY, DEFAULT_READINESS_TIMEOUT_MS, POLL_INTERVAL_MS2, SAFE_INSPECT_TEMPLATE;
+var import_node_child_process14, import_node_fs19, import_node_path17, DEVCONTAINER_OVERLAY, DEFAULT_READINESS_TIMEOUT_MS, POLL_INTERVAL_MS2, SAFE_INSPECT_TEMPLATE;
 var init_workspace_ensure = __esm({
   "src/core/workspace-ensure.ts"() {
     "use strict";
-    import_node_child_process12 = require("child_process");
-    import_node_fs18 = __toESM(require("fs"));
-    import_node_path15 = __toESM(require("path"));
+    import_node_child_process14 = require("child_process");
+    import_node_fs19 = __toESM(require("fs"));
+    import_node_path17 = __toESM(require("path"));
+    init_devpod_workspaces();
     init_docker();
     init_host_routes();
     init_repo_config();
     init_router();
     init_tls();
     init_workspace();
+    init_workspace_ownership();
     DEVCONTAINER_OVERLAY = "docker-compose.devrouter.yml";
     DEFAULT_READINESS_TIMEOUT_MS = 12e4;
     POLL_INTERVAL_MS2 = 1e3;
@@ -8261,49 +8907,29 @@ var init_workspace_ensure = __esm({
 });
 
 // src/core/workspace-lifecycle.ts
-function hasDevpod() {
-  const result = (0, import_node_child_process13.spawnSync)("devpod", ["version"], { encoding: "utf-8" });
-  return result.status === 0;
-}
-function listGitWorktrees(repoPath) {
-  const result = (0, import_node_child_process13.spawnSync)("git", ["-C", repoPath, "worktree", "list", "--porcelain"], {
-    encoding: "utf-8"
-  });
-  if (result.status !== 0) {
-    return [];
-  }
-  const worktrees = [];
-  let current = {};
-  for (const line of result.stdout.split("\n")) {
-    if (line.startsWith("worktree ")) {
-      current = { path: line.slice("worktree ".length).trim() };
-    } else if (line.startsWith("branch ")) {
-      current.branch = line.slice("branch ".length).trim().replace(/^refs\/heads\//, "");
-    } else if (line.trim() === "" && current.path) {
-      worktrees.push({ path: current.path, branch: current.branch });
-      current = {};
-    }
-  }
-  if (current.path) {
-    worktrees.push({ path: current.path, branch: current.branch });
-  }
-  return worktrees;
+function warnMissingWorkspaceOwnership(repoPath) {
+  const missing = listMissingWorkspaceOwnership(repoPath);
+  if (missing.length === 0) return;
+  process.stderr.write(
+    `Warning: ${missing.length} managed workspace owner${missing.length === 1 ? " is" : "s are"} missing. Review: dev workspace gc --repo ${repoPath}
+`
+  );
 }
 function defaultWorktreePath(mainRepo, ws) {
-  return import_node_path16.default.join(mainRepo, "trees", ws);
+  return import_node_path18.default.join(mainRepo, "trees", ws);
 }
 function assertDefaultWorktreeRootIgnored(mainRepo) {
-  const ignored = (0, import_node_child_process13.spawnSync)("git", ["-C", mainRepo, "check-ignore", "-q", "--no-index", "trees/"], {
+  const ignored = (0, import_node_child_process15.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_path18.default.join(mainRepo, "trees")}' is not ignored. Add 'trees/' to '${import_node_path18.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_path18.default.join(import_node_path18.default.dirname(mainRepo), `${import_node_path18.default.basename(mainRepo)}-${ws}`);
 }
 function teardownFallbackPath(mainRepo, workspace) {
   const candidates = [
@@ -8332,14 +8958,119 @@ function oneWorkspaceMatch(target, matches) {
   }
   return matches[0];
 }
+function oneRecordMatch(target, matches) {
+  if (matches.length > 1) {
+    throw new Error(
+      `Workspace target '${target}' is ambiguous: ${matches.map((match) => match.worktreePath).join(", ")}`
+    );
+  }
+  return matches[0];
+}
+function resolveWorkspaceTarget(mainRepo, target, worktrees, records) {
+  const requestedWorkspace = wsFromBranch(target);
+  if (!requestedWorkspace) {
+    throw new Error(`'${target}' does not yield a valid workspace token.`);
+  }
+  const liveBranchWorktree = oneWorkspaceMatch(
+    target,
+    worktrees.filter((worktree2) => worktree2.workspace !== void 0 && worktree2.branch === target)
+  );
+  if (liveBranchWorktree) {
+    const liveWorkspace = liveBranchWorktree.workspace;
+    if (!liveWorkspace) {
+      throw new Error(`Live branch '${target}' is not an isolated workspace.`);
+    }
+    const liveRecord = oneRecordMatch(
+      target,
+      records.filter((record2) => sameWorkspacePath(record2.worktreePath, liveBranchWorktree.path))
+    );
+    return {
+      workspace: liveRecord?.workspace ?? liveWorkspace,
+      worktreePath: liveBranchWorktree.path,
+      worktree: liveBranchWorktree,
+      record: liveRecord
+    };
+  }
+  const record = records.find((candidate) => candidate.workspace === requestedWorkspace);
+  if (record) {
+    return {
+      workspace: record.workspace,
+      worktreePath: record.worktreePath,
+      worktree: worktreeForRecord(worktrees, record),
+      record
+    };
+  }
+  const linked = worktrees.filter((worktree2) => worktree2.workspace !== void 0);
+  const worktree = oneWorkspaceMatch(
+    target,
+    linked.filter((candidate) => candidate.workspace === requestedWorkspace)
+  ) ?? oneWorkspaceMatch(
+    target,
+    linked.filter(
+      (candidate) => candidate.branch !== void 0 && wsFromBranch(candidate.branch) === requestedWorkspace
+    )
+  );
+  const workspace = worktree?.workspace ?? requestedWorkspace;
+  return {
+    workspace,
+    worktreePath: worktree?.path ?? teardownFallbackPath(mainRepo, workspace),
+    worktree,
+    record: void 0
+  };
+}
+function worktreeForRecord(worktrees, record) {
+  return worktrees.find((candidate) => sameWorkspacePath(candidate.path, record.worktreePath));
+}
+function devpodForTarget(target, worktrees, devpods) {
+  if (target.record) {
+    const status = inspectWorkspaceOwnership(target.record, worktrees, devpods);
+    if (status.ownerStatus === "conflict") {
+      throw new Error(
+        `Workspace '${target.workspace}' ownership conflicts with live Git or DevPod evidence; no resources were changed.`
+      );
+    }
+    return status.devpodStatus === "owned" ? devpods.find((devpod) => devpod.id === target.record?.devpodId) : void 0;
+  }
+  const devpodId = target.workspace;
+  const ownership = inspectDevpodWorkspaceOwnership(devpods, devpodId, target.worktreePath);
+  if (ownership.status === "conflict") {
+    throw new Error(ownership.reason);
+  }
+  return ownership.status === "owned" ? ownership.workspace : void 0;
+}
+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_fs20.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_process15.spawnSync)(
+    "git",
+    ["-C", target.worktreePath, "status", "--porcelain", "--untracked-files=normal"],
+    { encoding: "utf-8" }
+  );
+  if (status.status !== 0) {
+    const detail = [status.error?.message, status.stderr].filter(Boolean).join("\n").trim();
+    throw new Error(`git status failed for '${target.worktreePath}': ${detail || "unknown error"}`);
+  }
+  if (status.stdout.trim()) {
+    throw new Error(
+      `Worktree '${target.worktreePath}' has uncommitted changes; use --keep-worktree or clean it before workspace down.`
+    );
+  }
+}
 async function workspaceUp(branch, opts = {}) {
   const mainRepo = resolveRepoPath(opts.repoPath);
   const ws = wsFromBranch(branch);
   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_fs19.default.existsSync(worktreePath)) {
+  const worktreePath = opts.path ? import_node_path18.default.resolve(opts.path) : defaultWorktreePath(mainRepo, ws);
+  if (import_node_fs20.default.existsSync(worktreePath)) {
     const registered = listGitWorktrees(mainRepo).find(
       (worktree) => sameWorkspacePath(worktree.path, worktreePath)
     );
@@ -8357,11 +9088,11 @@ async function workspaceUp(branch, opts = {}) {
     if (!opts.path) {
       assertDefaultWorktreeRootIgnored(mainRepo);
     }
-    const add = (0, import_node_child_process13.spawnSync)("git", ["-C", mainRepo, "worktree", "add", worktreePath, branch], {
+    const add = (0, import_node_child_process15.spawnSync)("git", ["-C", mainRepo, "worktree", "add", worktreePath, branch], {
       encoding: "utf-8"
     });
     if (add.status !== 0) {
-      const addNew = (0, import_node_child_process13.spawnSync)(
+      const addNew = (0, import_node_child_process15.spawnSync)(
         "git",
         ["-C", mainRepo, "worktree", "add", "-b", branch, worktreePath],
         {
@@ -8377,6 +9108,7 @@ async function workspaceUp(branch, opts = {}) {
 `);
   }
   if (opts.noDevpod) {
+    warnMissingWorkspaceOwnership(mainRepo);
     process.stdout.write("Skipped environment startup; no routes were changed.\n");
     return;
   }
@@ -8393,79 +9125,104 @@ ${ensured.urls.map((url) => `  ${url}`).join("\n")}
 function workspaceLs(repoPath) {
   const mainRepo = resolveRepoPath(repoPath);
   const worktrees = identifyGitWorktrees(mainRepo);
-  const routesByWorktreePath = listRoutesForWorktreePaths(
-    worktrees.map((worktree) => worktree.path)
+  const records = listWorkspaceOwnership(mainRepo);
+  let devpods;
+  try {
+    devpods = listDevpodWorkspaces();
+  } catch {
+    devpods = void 0;
+  }
+  const paths = Array.from(
+    /* @__PURE__ */ new Set([
+      ...worktrees.map((worktree) => worktree.path),
+      ...records.map((record) => record.worktreePath)
+    ])
   );
-  return worktrees.map((wt) => {
-    const wsRoutes = routesByWorktreePath.get(wt.path) ?? [];
+  const routesByWorktreePath = listRoutesForWorktreePaths(paths);
+  const worktreesByPath = new Map(worktrees.map((worktree) => [worktree.path, worktree]));
+  const recordsByPath = new Map(records.map((record) => [record.worktreePath, record]));
+  return paths.map((worktreePath) => {
+    const worktree = worktreesByPath.get(worktreePath);
+    const record = recordsByPath.get(worktreePath);
+    const status = record ? inspectWorkspaceOwnership(record, worktrees, devpods) : void 0;
+    const matchingDevpods = devpods?.filter(
+      (devpod) => sameWorkspacePath(devpod.source.localFolder, worktreePath)
+    );
+    const wsRoutes = routesByWorktreePath.get(worktreePath) ?? [];
     return {
-      workspace: wt.workspace,
-      branch: wt.branch,
-      worktreePath: wt.path,
+      workspace: record?.workspace ?? worktree?.workspace,
+      branch: worktree?.branch ?? record?.branch ?? void 0,
+      worktreePath,
+      legacy: !record && worktree?.workspace !== void 0,
+      ownerStatus: status?.ownerStatus,
+      devpodStatus: status?.devpodStatus ?? (devpods === void 0 ? "unknown" : matchingDevpods?.length === 0 ? "absent" : matchingDevpods?.length === 1 ? "owned" : "conflict"),
       routeCount: wsRoutes.length,
       hosts: wsRoutes.map((route) => route.host)
     };
   });
 }
-async function workspaceDown(target, opts = {}) {
-  const requestedWorkspace = wsFromBranch(target);
-  if (!requestedWorkspace) {
-    throw new Error(`'${target}' does not yield a valid workspace token.`);
-  }
+async function runWorkspaceLifecycle(action2, target, opts = {}) {
   const mainRepo = resolveRepoPath(opts.repoPath);
-  const worktrees = identifyGitWorktrees(mainRepo).filter(
-    (worktree) => worktree.workspace !== void 0
-  );
-  const exactBranchMatch = worktrees.find((worktree) => worktree.branch === target);
-  const match = exactBranchMatch ?? oneWorkspaceMatch(
-    target,
-    worktrees.filter((worktree) => worktree.workspace === requestedWorkspace)
-  ) ?? oneWorkspaceMatch(
-    target,
-    worktrees.filter(
-      (worktree) => worktree.branch !== void 0 && wsFromBranch(worktree.branch) === requestedWorkspace
-    )
-  );
-  const workspace = match?.workspace ?? requestedWorkspace;
-  const worktreePath = match?.path ?? teardownFallbackPath(mainRepo, workspace);
-  const teardown = async () => {
-    const routes = removeWorkspaceRoutesForWorktree(workspace, worktreePath);
-    process.stdout.write(`Freed ${routes.length} route(s) for workspace '${workspace}'.
-`);
-    if (!opts.keepDevpod && hasDevpod()) {
-      (0, import_node_child_process13.spawnSync)("devpod", ["stop", workspace], { stdio: "inherit" });
-    }
-    if (!opts.keepWorktree) {
-      if (import_node_fs19.default.existsSync(worktreePath) && worktreePath !== mainRepo) {
-        const rm = (0, import_node_child_process13.spawnSync)("git", ["-C", mainRepo, "worktree", "remove", worktreePath], {
+  const worktrees = identifyGitWorktrees(mainRepo);
+  const records = listWorkspaceOwnership(mainRepo);
+  const resolved = resolveWorkspaceTarget(mainRepo, target, worktrees, records);
+  const operation = async () => {
+    const removeWorktree = action2 === "down" && !opts.keepWorktree;
+    const devpodAction = action2 === "stop" ? "stop" : "delete";
+    if (removeWorktree) {
+      assertFullDownPreflight(mainRepo, resolved);
+    }
+    const devpods = listDevpodWorkspaces();
+    const devpod = devpodForTarget(resolved, worktrees, devpods);
+    if (devpod) {
+      runDevpodWorkspaceAction(devpodAction, devpod.id);
+    }
+    const routes = removeWorkspaceRoutesForWorktree(resolved.workspace, resolved.worktreePath);
+    process.stdout.write(
+      `Freed ${routes.length} route(s) for workspace '${resolved.workspace}'.
+`
+    );
+    if (removeWorktree) {
+      if (resolved.worktree && !resolved.worktree.prunable && import_node_fs20.default.existsSync(resolved.worktreePath)) {
+        const rm = (0, import_node_child_process15.spawnSync)("git", ["-C", mainRepo, "worktree", "remove", resolved.worktreePath], {
           encoding: "utf-8"
         });
-        if (rm.status === 0) {
-          process.stdout.write(`Removed worktree ${worktreePath}.
-`);
-        } else {
-          process.stderr.write(
-            `Warning: could not remove worktree ${worktreePath}: ${rm.stderr || "unknown error"}
-`
+        if (rm.status !== 0) {
+          const detail = [rm.error?.message, rm.stderr].filter(Boolean).join("\n").trim();
+          throw new Error(
+            `git worktree remove failed for '${resolved.worktreePath}': ${detail || "unknown error"}`
           );
         }
+        process.stdout.write(`Removed worktree ${resolved.worktreePath}.
+`);
+      }
+      if (resolved.record) {
+        removeWorkspaceOwnership(mainRepo, resolved.workspace);
       }
     }
-    return { freedRoutes: routes.length, workspace };
+    return { freedRoutes: routes.length, workspace: resolved.workspace };
   };
-  return match && import_node_fs19.default.existsSync(worktreePath) ? withWorkspaceLifecycleLock(worktreePath, teardown) : teardown();
+  return resolved.worktree && !resolved.worktree.prunable && import_node_fs20.default.existsSync(resolved.worktreePath) ? withWorkspaceLifecycleLock(resolved.worktreePath, operation) : operation();
+}
+async function workspaceStop(target, opts = {}) {
+  return runWorkspaceLifecycle("stop", target, opts);
+}
+async function workspaceDown(target, opts = {}) {
+  return runWorkspaceLifecycle("down", target, opts);
 }
-var import_node_child_process13, import_node_fs19, import_node_path16;
+var import_node_child_process15, import_node_fs20, import_node_path18;
 var init_workspace_lifecycle = __esm({
   "src/core/workspace-lifecycle.ts"() {
     "use strict";
-    import_node_child_process13 = require("child_process");
-    import_node_fs19 = __toESM(require("fs"));
-    import_node_path16 = __toESM(require("path"));
+    import_node_child_process15 = require("child_process");
+    import_node_fs20 = __toESM(require("fs"));
+    import_node_path18 = __toESM(require("path"));
+    init_devpod_workspaces();
     init_repo_config();
     init_route_state();
     init_workspace();
     init_workspace_ensure();
+    init_workspace_ownership();
   }
 });
 
@@ -8474,19 +9231,34 @@ var workspace_exports = {};
 __export(workspace_exports, {
   runWorkspaceDownCommand: () => runWorkspaceDownCommand,
   runWorkspaceEnsureCommand: () => runWorkspaceEnsureCommand,
+  runWorkspaceGcCommand: () => runWorkspaceGcCommand,
   runWorkspaceLsCommand: () => runWorkspaceLsCommand,
+  runWorkspaceStopCommand: () => runWorkspaceStopCommand,
   runWorkspaceUpCommand: () => runWorkspaceUpCommand
 });
+function resolveGitWorkspaceRepo(repoPath) {
+  const resolved = resolveRepoPath(repoPath);
+  try {
+    resolveGitCommonDir(resolved);
+  } catch (error) {
+    throw new Error(`Workspace commands require a Git repository: '${resolved}'.`, {
+      cause: error
+    });
+  }
+  return resolved;
+}
 async function runWorkspaceUpCommand(branch, options) {
+  const repoPath = resolveGitWorkspaceRepo(options.repo);
   await workspaceUp(branch, {
     path: options.path,
     noDevpod: options.noDevpod,
     open: options.open,
-    repoPath: options.repo
+    repoPath
   });
 }
 async function runWorkspaceEnsureCommand(options) {
-  const result = await workspaceEnsure(options.path, { open: options.open });
+  const repoPath = resolveGitWorkspaceRepo(options.path);
+  const result = await workspaceEnsure(repoPath, { open: options.open });
   process.stdout.write(
     `Workspace '${result.workspace}' is ready (${result.devpodId}).
 ${result.urls.map((url) => `  ${url}`).join("\n")}
@@ -8494,7 +9266,8 @@ ${result.urls.map((url) => `  ${url}`).join("\n")}
   );
 }
 function runWorkspaceLsCommand(options) {
-  const rows = workspaceLs(options.repo);
+  const repoPath = resolveGitWorkspaceRepo(options.repo);
+  const rows = workspaceLs(repoPath);
   if (options.json) {
     process.stdout.write(`${JSON.stringify(rows, null, 2)}
 `);
@@ -8506,24 +9279,56 @@ function runWorkspaceLsCommand(options) {
   }
   for (const row of rows) {
     const label = row.workspace ?? "(primary)";
+    const ownership = row.ownerStatus ?? (row.legacy ? "legacy" : "unmanaged");
     process.stdout.write(
-      `${label}	${row.branch ?? "-"}	${row.routeCount} route(s)	${row.worktreePath}
+      `${label}	${row.branch ?? "-"}	${ownership}	devpod:${row.devpodStatus}	${row.routeCount} route(s)	${row.worktreePath}
 `
     );
   }
 }
 async function runWorkspaceDownCommand(target, options) {
+  const repoPath = resolveGitWorkspaceRepo(options.repo);
   await workspaceDown(target, {
     keepWorktree: options.keepWorktree,
-    keepDevpod: options.keepDevpod,
-    repoPath: options.repo
+    repoPath
   });
 }
+async function runWorkspaceStopCommand(target, options) {
+  const repoPath = resolveGitWorkspaceRepo(options.repo);
+  await workspaceStop(target, { repoPath });
+}
+function runWorkspaceGcCommand(options) {
+  const repoPath = resolveGitWorkspaceRepo(options.repo);
+  const plan = inspectWorkspaceGc(repoPath);
+  const report = options.yes ? applyWorkspaceGc(plan) : plan;
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+  } else {
+    process.stdout.write(
+      `Workspace GC ${report.mode}: ${report.summary.eligible} eligible, ${report.summary.blocked} blocked, ${report.summary.cleaned} cleaned, ${report.summary.errors} error(s).
+`
+    );
+    for (const candidate of report.candidates) {
+      process.stdout.write(
+        `${candidate.workspace}	${candidate.kind}	${candidate.ownerStatus ?? "legacy"}	${candidate.eligible ? "eligible" : "blocked"}	${candidate.worktreePath}
+`
+      );
+    }
+    if (!options.yes && report.summary.eligible > 0) {
+      process.stdout.write("Dry run only. Re-run with --yes to apply eligible cleanup.\n");
+    }
+  }
+  if (report.summary.errors > 0) process.exitCode = 1;
+}
 var init_workspace2 = __esm({
   "src/commands/workspace.ts"() {
     "use strict";
+    init_repo_config();
     init_workspace_ensure();
+    init_workspace_gc();
     init_workspace_lifecycle();
+    init_workspace_ownership();
   }
 });
 
@@ -8565,7 +9370,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.29" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.31" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {
@@ -8805,7 +9610,21 @@ workspaceCommand.command("ls").description("List git worktrees with their worksp
     runWorkspaceLsCommand2(options);
   })
 );
-workspaceCommand.command("down").description("Free a workspace's routes, stop its devpod, and remove its worktree").argument("<workspace>", "Workspace token or branch name").option("--keep-worktree", "Leave the git worktree in place").option("--keep-devpod", "Leave the devpod workspace running").option("--repo <path>", "Main repository path (defaults to current directory)").action(
+workspaceCommand.command("gc").description("Report or clean missing ledger-owned workspace resources").option("--repo <path>", "Main repository path (defaults to current directory)").option("--json", "Output JSON").option("--yes", "Delete eligible DevPod, route, and ownership resources").action(
+  withErrorHandling(async (_options, command) => {
+    const options = command.opts();
+    const { runWorkspaceGcCommand: runWorkspaceGcCommand2 } = await Promise.resolve().then(() => (init_workspace2(), workspace_exports));
+    runWorkspaceGcCommand2(options);
+  })
+);
+workspaceCommand.command("stop").description("Stop a workspace's DevPod and free routes while preserving its worktree and data").argument("<workspace>", "Workspace token or live branch name").option("--repo <path>", "Main repository path (defaults to current directory)").action(
+  withErrorHandling(async (target, _options, command) => {
+    const options = command.opts();
+    const { runWorkspaceStopCommand: runWorkspaceStopCommand2 } = await Promise.resolve().then(() => (init_workspace2(), workspace_exports));
+    await runWorkspaceStopCommand2(target, options);
+  })
+);
+workspaceCommand.command("down").description("Delete a workspace's DevPod and routes, then remove its clean Git worktree").argument("<workspace>", "Workspace token or live branch name").option("--keep-worktree", "Delete runtime resources but preserve the Git worktree and record").option("--repo <path>", "Main repository path (defaults to current directory)").action(
   withErrorHandling(async (target, _options, command) => {
     const options = command.opts();
     const { runWorkspaceDownCommand: runWorkspaceDownCommand2 } = await Promise.resolve().then(() => (init_workspace2(), workspace_exports));