@getmonoceros/workbench 1.20.2 → 1.21.1

package/dist/bin.js

@@ -1415,6 +1415,12 @@ var init_global = __esm({
         hostPort: z2.number().int().min(1).max(65535).optional().describe(
           "Host port the Traefik singleton binds. Default 80. Set this when 80 is held by another service on your machine \u2014 URLs then become http://<name>.localhost:<port>/."
         )
+      }).nullish(),
+      // Tool-freshness settings (ADR 0018). One machine-global knob.
+      upgrade: z2.object({
+        staleDays: z2.number().int().min(1).optional().describe(
+          "Days after the last `monoceros upgrade` before `apply` nudges you to refresh tooling. Default 30."
+        )
       }).nullish()
     });
     DEFAULT_PROXY_HOST_PORT = 80;
@@ -2098,9 +2104,84 @@ var init_service_doc = __esm({
   }
 });
 
-// src/create/scaffold.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4, promises as fs7 } from "fs";
+// src/create/claude-settings.ts
+import { existsSync as existsSync5, promises as fsp2 } from "fs";
 import path8 from "path";
+function resolveClaudeDefaultMode(raw) {
+  switch ((raw ?? "auto").trim()) {
+    case "ask":
+    case "default":
+      return "default";
+    case "edits":
+    case "acceptEdits":
+      return "acceptEdits";
+    case "plan":
+      return "plan";
+    case "bypass":
+    case "bypassPermissions":
+      return "bypassPermissions";
+    case "auto":
+    case "":
+      return "auto";
+    default:
+      return "auto";
+  }
+}
+async function writeClaudePermissionMode(targetDir, features) {
+  if (!features) return;
+  const entry2 = Object.entries(features).find(
+    ([ref]) => matchMonocerosFeature(ref)?.name === "claude-code"
+  );
+  if (!entry2) return;
+  const raw = entry2[1]?.permissionMode;
+  const mode = resolveClaudeDefaultMode(
+    typeof raw === "string" ? raw : void 0
+  );
+  const file = path8.join(targetDir, "home", ".claude", "settings.json");
+  await fsp2.mkdir(path8.dirname(file), { recursive: true });
+  let config = {};
+  if (existsSync5(file)) {
+    try {
+      const txt = await fsp2.readFile(file, "utf8");
+      if (txt.trim()) {
+        const parsed = JSON.parse(txt);
+        if (typeof parsed === "object" && parsed !== null) {
+          config = parsed;
+        }
+      }
+    } catch {
+      config = {};
+    }
+  }
+  const permissions = typeof config.permissions === "object" && config.permissions !== null ? config.permissions : {};
+  permissions.defaultMode = mode;
+  config.permissions = permissions;
+  const env = typeof config.env === "object" && config.env !== null ? config.env : {};
+  if (mode === "auto") {
+    env.CLAUDE_CODE_ENABLE_AUTO_MODE = "1";
+  } else {
+    delete env.CLAUDE_CODE_ENABLE_AUTO_MODE;
+  }
+  if (Object.keys(env).length > 0) config.env = env;
+  else delete config.env;
+  if (mode === "bypassPermissions") {
+    config.skipDangerousModePermissionPrompt = true;
+  } else {
+    delete config.skipDangerousModePermissionPrompt;
+  }
+  await fsp2.writeFile(file, `${JSON.stringify(config, null, 2)}
+`);
+}
+var init_claude_settings = __esm({
+  "src/create/claude-settings.ts"() {
+    "use strict";
+    init_ref();
+  }
+});
+
+// src/create/scaffold.ts
+import { existsSync as existsSync6, readFileSync as readFileSync4, promises as fs7 } from "fs";
+import path9 from "path";
 function deriveRepoName(url) {
   const lastSep = Math.max(url.lastIndexOf("/"), url.lastIndexOf(":"));
   const tail = url.slice(lastSep + 1);
@@ -2230,7 +2311,7 @@ function featuresSourceRoot() {
   const override2 = process.env.MONOCEROS_FEATURES_DIR_OVERRIDE?.trim();
   if (override2 && override2.length > 0) return override2;
   const checkout = workbenchCheckoutRoot();
-  return checkout ? path8.join(checkout, "images", "features") : null;
+  return checkout ? path9.join(checkout, "images", "features") : null;
 }
 function resolveFeatures(opts) {
   const resolved = [];
@@ -2265,8 +2346,8 @@ function resolveFeatures(opts) {
       if (match) {
         const name = match.name;
         const sourceRoot = featuresSourceRoot();
-        const localSourceDir = sourceRoot ? path8.join(sourceRoot, name) : null;
-        if (localSourceDir && existsSync5(localSourceDir)) {
+        const localSourceDir = sourceRoot ? path9.join(sourceRoot, name) : null;
+        if (localSourceDir && existsSync6(localSourceDir)) {
           const { paths: paths2, files: files2 } = readPersistentHomeEntries(localSourceDir);
           resolved.push({
             devcontainerKey: `./features/${name}`,
@@ -2298,7 +2379,7 @@ function resolveFeatures(opts) {
   return resolved;
 }
 function readPersistentHomeEntries(localSourceDir) {
-  const manifestPath = path8.join(localSourceDir, "devcontainer-feature.json");
+  const manifestPath = path9.join(localSourceDir, "devcontainer-feature.json");
   try {
     const text = readFileSync4(manifestPath, "utf8");
     const parsed = JSON.parse(text);
@@ -2312,7 +2393,7 @@ function readPersistentHomeEntries(localSourceDir) {
 }
 function readBundledPersistentHomeEntries(name) {
   try {
-    return readPersistentHomeEntries(path8.join(bundledFeaturesDir(), name));
+    return readPersistentHomeEntries(path9.join(bundledFeaturesDir(), name));
   } catch {
     return { paths: [], files: [] };
   }
@@ -2718,7 +2799,7 @@ function buildPostCreateScript(opts) {
   return lines.join("\n") + "\n";
 }
 async function writePostCreateScript(devcontainerDir, opts) {
-  const dest = path8.join(devcontainerDir, "post-create.sh");
+  const dest = path9.join(devcontainerDir, "post-create.sh");
   await fs7.writeFile(dest, buildPostCreateScript(opts));
   await fs7.chmod(dest, 493);
 }
@@ -2732,11 +2813,11 @@ async function writeIfChanged(filePath, content) {
 }
 async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   const dockerMode = scaffoldOpts.dockerMode ?? "rootful";
-  const devcontainerDir = path8.join(targetDir, ".devcontainer");
-  const monocerosDir = path8.join(targetDir, ".monoceros");
-  const projectsDir = path8.join(targetDir, "projects");
-  const homeDir = path8.join(targetDir, "home");
-  const dataDir = path8.join(targetDir, "data");
+  const devcontainerDir = path9.join(targetDir, ".devcontainer");
+  const monocerosDir = path9.join(targetDir, ".monoceros");
+  const projectsDir = path9.join(targetDir, "projects");
+  const homeDir = path9.join(targetDir, "home");
+  const dataDir = path9.join(targetDir, "data");
   await fs7.mkdir(devcontainerDir, { recursive: true });
   await fs7.mkdir(monocerosDir, { recursive: true });
   await fs7.mkdir(projectsDir, { recursive: true });
@@ -2746,59 +2827,60 @@ async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
     for (const svc of opts.services) {
       const hasDataVolume = svc.volumes.some((v) => v.split(":")[0] === "data");
       if (hasDataVolume) {
-        await fs7.mkdir(path8.join(dataDir, svc.name), { recursive: true });
+        await fs7.mkdir(path9.join(dataDir, svc.name), { recursive: true });
       }
     }
   }
-  const containerGitignore = path8.join(targetDir, ".gitignore");
+  const containerGitignore = path9.join(targetDir, ".gitignore");
   await fs7.writeFile(
     containerGitignore,
     "/home/\n/.monoceros/\n/data/\n/AGENTS.md\n/CLAUDE.md\n"
   );
-  const gitkeep = path8.join(projectsDir, ".gitkeep");
-  if (!existsSync5(gitkeep)) {
+  const gitkeep = path9.join(projectsDir, ".gitkeep");
+  if (!existsSync6(gitkeep)) {
     await fs7.writeFile(gitkeep, "");
   }
   await fs7.writeFile(
-    path8.join(monocerosDir, ".gitignore"),
+    path9.join(monocerosDir, ".gitignore"),
     "git-credentials*\ngitconfig\n"
   );
   const devcontainerJson = buildDevcontainerJson(opts, dockerMode);
   await writeIfChanged(
-    path8.join(devcontainerDir, "devcontainer.json"),
+    path9.join(devcontainerDir, "devcontainer.json"),
     JSON.stringify(devcontainerJson, null, 2) + "\n"
   );
-  const featuresDir = path8.join(devcontainerDir, "features");
-  if (existsSync5(featuresDir)) {
+  const featuresDir = path9.join(devcontainerDir, "features");
+  if (existsSync6(featuresDir)) {
     await fs7.rm(featuresDir, { recursive: true, force: true });
   }
   const resolvedFeatures = resolveFeatures(opts);
   for (const f of resolvedFeatures) {
     if (!f.localSourceDir || !f.localName) continue;
-    const dest = path8.join(featuresDir, f.localName);
+    const dest = path9.join(featuresDir, f.localName);
     await fs7.mkdir(dest, { recursive: true });
     await fs7.cp(f.localSourceDir, dest, { recursive: true });
   }
   for (const f of resolvedFeatures) {
     for (const sub of f.persistentHomePaths) {
-      await fs7.mkdir(path8.join(homeDir, sub), { recursive: true });
+      await fs7.mkdir(path9.join(homeDir, sub), { recursive: true });
     }
     for (const entry2 of f.persistentHomeFiles) {
-      const filePath = path8.join(homeDir, entry2.path);
-      await fs7.mkdir(path8.dirname(filePath), { recursive: true });
-      if (!existsSync5(filePath)) {
+      const filePath = path9.join(homeDir, entry2.path);
+      await fs7.mkdir(path9.dirname(filePath), { recursive: true });
+      if (!existsSync6(filePath)) {
         await fs7.writeFile(filePath, entry2.initialContent);
       }
     }
   }
+  await writeClaudePermissionMode(targetDir, opts.features);
   await writePostCreateScript(devcontainerDir, opts);
-  const composePath = path8.join(devcontainerDir, "compose.yaml");
+  const composePath = path9.join(devcontainerDir, "compose.yaml");
   if (needsCompose(opts)) {
     await writeIfChanged(composePath, buildComposeYaml(opts, dockerMode));
-  } else if (existsSync5(composePath)) {
+  } else if (existsSync6(composePath)) {
     await fs7.rm(composePath);
   }
-  const workspacePath = path8.join(targetDir, `${opts.name}.code-workspace`);
+  const workspacePath = path9.join(targetDir, `${opts.name}.code-workspace`);
   let existingWorkspace;
   try {
     const raw = await fs7.readFile(workspacePath, "utf8");
@@ -2809,8 +2891,8 @@ async function writeScaffold(opts, targetDir, scaffoldOpts = {}) {
   const generated = buildCodeWorkspaceJson(opts);
   const merged = mergeCodeWorkspace(existingWorkspace, generated);
   await fs7.writeFile(workspacePath, JSON.stringify(merged, null, 2) + "\n");
-  const vscodeDir = path8.join(targetDir, ".vscode");
-  const settingsPath = path8.join(vscodeDir, "settings.json");
+  const vscodeDir = path9.join(targetDir, ".vscode");
+  const settingsPath = path9.join(vscodeDir, "settings.json");
   let existingSettings;
   try {
     existingSettings = JSON.parse(await fs7.readFile(settingsPath, "utf8"));
@@ -2829,6 +2911,7 @@ var init_scaffold = __esm({
     "use strict";
     init_paths();
     init_ref();
+    init_claude_settings();
     init_catalog();
     APT_PACKAGE_NAME_RE2 = /^[a-z0-9][a-z0-9.+-]*$/;
     FEATURE_REF_RE2 = /^[a-z0-9.-]+(\/[a-z0-9._-]+)+:[a-z0-9._-]+$/;
@@ -3259,8 +3342,8 @@ function removeRepoFromDoc(doc, urlOrPath) {
     if (!isMap2(item)) return false;
     const url = item.get("url");
     if (url === urlOrPath) return true;
-    const path25 = item.get("path");
-    const effectivePath = typeof path25 === "string" ? path25 : typeof url === "string" ? deriveRepoName(url) : void 0;
+    const path27 = item.get("path");
+    const effectivePath = typeof path27 === "string" ? path27 : typeof url === "string" ? deriveRepoName(url) : void 0;
     return effectivePath === urlOrPath;
   });
   if (idx < 0) return false;
@@ -3297,7 +3380,7 @@ var init_yml = __esm({
 import { promises as fs8 } from "fs";
 import { consola } from "consola";
 import { createPatch } from "diff";
-import path9 from "path";
+import path10 from "path";
 function runAddLanguage(input) {
   if (!BUILTIN_LANGUAGES.has(input.language) && !LANGUAGE_CATALOG[input.language]) {
     throw new Error(
@@ -3372,7 +3455,7 @@ async function runAddRepo(input) {
       "Missing repo URL. Usage: monoceros add-repo <containername> <url>."
     );
   }
-  const path25 = (input.path ?? deriveRepoName(url)).trim();
+  const path27 = (input.path ?? deriveRepoName(url)).trim();
   const hasName = typeof input.gitName === "string" && input.gitName.trim().length > 0;
   const hasEmail = typeof input.gitEmail === "string" && input.gitEmail.trim().length > 0;
   if (hasName !== hasEmail) {
@@ -3409,7 +3492,7 @@ async function runAddRepo(input) {
   const providerToWrite = !canonical && explicitProvider ? explicitProvider : void 0;
   const entry2 = {
     url,
-    path: path25,
+    path: path27,
     ...hasName && hasEmail ? {
       gitUser: {
         name: input.gitName.trim(),
@@ -3541,7 +3624,7 @@ async function tryCloneInRunningContainer(input, entry2) {
   logger.info(
     `Cloned ${entry2.url} into /workspaces/${containerName2}/${targetRel} inside the running container.`
   );
-  void path9;
+  void path10;
 }
 function shquote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -4323,7 +4406,7 @@ var init_add_service = __esm({
 
 // src/config/state.ts
 import { promises as fs9 } from "fs";
-import path10 from "path";
+import path11 from "path";
 function buildStateFile(opts) {
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
@@ -4334,7 +4417,7 @@ function buildStateFile(opts) {
   };
 }
 function stateFilePath(targetDir) {
-  return path10.join(targetDir, ".monoceros", "state.json");
+  return path11.join(targetDir, ".monoceros", "state.json");
 }
 async function readStateFile(targetDir) {
   try {
@@ -4345,7 +4428,7 @@ async function readStateFile(targetDir) {
   }
 }
 async function writeStateFile(targetDir, state) {
-  const monocerosDir = path10.join(targetDir, ".monoceros");
+  const monocerosDir = path11.join(targetDir, ".monoceros");
   await fs9.mkdir(monocerosDir, { recursive: true });
   await fs9.writeFile(
     stateFilePath(targetDir),
@@ -4436,7 +4519,7 @@ var init_transform = __esm({
 
 // src/apply/apply-log.ts
 import { createWriteStream, mkdirSync } from "fs";
-import path11 from "path";
+import path12 from "path";
 import { Writable } from "stream";
 function safeIsoStamp(d) {
   return d.toISOString().replace(/[:.]/g, "-");
@@ -4446,7 +4529,7 @@ function createApplyLog(opts) {
   const dir = containerLogsDir(opts.name, opts.home);
   mkdirSync(dir, { recursive: true });
   const file = `apply-${opts.name}-${safeIsoStamp(now)}.log`;
-  const fullPath = path11.join(dir, file);
+  const fullPath = path12.join(dir, file);
   const stream = createWriteStream(fullPath, { flags: "w" });
   const header = [
     `# monoceros apply log`,
@@ -5290,7 +5373,7 @@ var init_markers = __esm({
 
 // src/briefing/index.ts
 import { promises as fs10 } from "fs";
-import path12 from "path";
+import path13 from "path";
 async function writeBriefing(input) {
   const subCommands = input.subCommands ?? await loadSubCommandsDynamic();
   const manifestLoader = input.manifestLoader ?? ((ref) => loadFeatureManifestSummary(ref));
@@ -5303,12 +5386,12 @@ async function writeBriefing(input) {
   );
   const claudeBody = generateClaudeMd();
   const commandsBody = generateCommandsMd(subCommands);
-  await writeMarkerAware(path12.join(input.targetDir, "AGENTS.md"), agentsBody);
-  await writeMarkerAware(path12.join(input.targetDir, "CLAUDE.md"), claudeBody);
-  const monocerosDir = path12.join(input.targetDir, ".monoceros");
+  await writeMarkerAware(path13.join(input.targetDir, "AGENTS.md"), agentsBody);
+  await writeMarkerAware(path13.join(input.targetDir, "CLAUDE.md"), claudeBody);
+  const monocerosDir = path13.join(input.targetDir, ".monoceros");
   await fs10.mkdir(monocerosDir, { recursive: true });
   await fs10.writeFile(
-    path12.join(monocerosDir, "commands.md"),
+    path13.join(monocerosDir, "commands.md"),
     commandsBody,
     "utf8"
   );
@@ -5467,7 +5550,7 @@ var init_runtime_pull_hint = __esm({
 import { spawn as spawn4 } from "child_process";
 import { readFileSync as readFileSync5 } from "fs";
 import { createRequire } from "module";
-import path13 from "path";
+import path14 from "path";
 function devcontainerCliPath() {
   if (cachedBinaryPath) return cachedBinaryPath;
   const pkgJsonPath = require_.resolve("@devcontainers/cli/package.json");
@@ -5476,7 +5559,7 @@ function devcontainerCliPath() {
   if (!binEntry) {
     throw new Error("Could not resolve @devcontainers/cli bin entry.");
   }
-  cachedBinaryPath = path13.resolve(path13.dirname(pkgJsonPath), binEntry);
+  cachedBinaryPath = path14.resolve(path14.dirname(pkgJsonPath), binEntry);
   return cachedBinaryPath;
 }
 var require_, cachedBinaryPath, spawnDevcontainer;
@@ -5550,8 +5633,9 @@ var init_cli = __esm({
 
 // src/devcontainer/compose.ts
 import { spawn as spawn5 } from "child_process";
-import { existsSync as existsSync6 } from "fs";
-import path14 from "path";
+import { existsSync as existsSync7 } from "fs";
+import path15 from "path";
+import { Writable as Writable3 } from "stream";
 import { consola as consola9 } from "consola";
 async function findContainerIds(filters, exec = spawnDocker) {
   const ids = /* @__PURE__ */ new Set();
@@ -5591,16 +5675,16 @@ async function cleanupDockerObjects(opts) {
   return { exitCode: rmExit, removedIds: ids };
 }
 function composeProjectName(root) {
-  return `${path14.basename(root)}_devcontainer`;
+  return `${path15.basename(root)}_devcontainer`;
 }
 function resolveCompose(root) {
-  if (!existsSync6(path14.join(root, ".devcontainer"))) {
+  if (!existsSync7(path15.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );
   }
-  const composeFile = path14.join(root, ".devcontainer", "compose.yaml");
-  if (!existsSync6(composeFile)) {
+  const composeFile = path15.join(root, ".devcontainer", "compose.yaml");
+  if (!existsSync7(composeFile)) {
     throw new Error(
       `No compose.yaml at ${composeFile}. \`start\` / \`stop\` / \`status\` / \`logs\` require services configured via \`monoceros add-service <name> <svc>\`. Use \`monoceros shell <name>\` to enter the container directly.`
     );
@@ -5619,7 +5703,13 @@ async function runStart(opts) {
   const spawnFn = opts.spawn ?? spawnDevcontainer;
   logger.info(`Bringing devcontainer up at ${opts.root}\u2026`);
   return spawnFn(
-    ["up", "--workspace-folder", opts.root, "--mount-workspace-git-root=false"],
+    [
+      "up",
+      "--workspace-folder",
+      opts.root,
+      "--mount-workspace-git-root=false",
+      ...opts.noCache ? ["--build-no-cache"] : []
+    ],
     opts.root,
     buildSpawnOptions(opts)
   );
@@ -5631,14 +5721,62 @@ function buildSpawnOptions(opts) {
   if (opts.silent) out.silent = true;
   return Object.keys(out).length > 0 ? out : void 0;
 }
+async function runUpWithBindRetry(attempt, baseSink, logger, opts = {}) {
+  const delayMs = opts.delayMs ?? BIND_RETRY_DELAY_MS;
+  let code = 0;
+  for (let i = 1; i <= BIND_RETRY_ATTEMPTS; i += 1) {
+    let captured = "";
+    const sink = new Writable3({
+      write(chunk, _enc, cb) {
+        captured += chunk.toString();
+        if (baseSink) baseSink.write(chunk);
+        cb();
+      }
+    });
+    code = await attempt(sink);
+    if (code === 0) return 0;
+    if (i < BIND_RETRY_ATTEMPTS && BIND_SOURCE_MISSING_RE.test(captured)) {
+      logger.info(
+        `Bind source not visible yet (Docker Desktop file sync); nudging + retrying\u2026 (${i}/${BIND_RETRY_ATTEMPTS - 1})`
+      );
+      if (opts.onBindRetry) {
+        try {
+          await opts.onBindRetry();
+        } catch {
+        }
+      }
+      if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+      continue;
+    }
+    return code;
+  }
+  return code;
+}
 async function runContainerCycle(root, opts) {
   const { hasCompose, logger } = opts;
+  const exec = opts.dockerExec ?? spawnDocker;
+  const onBindRetry = opts.prewarmImage ? async () => {
+    await exec([
+      "run",
+      "--rm",
+      "--entrypoint",
+      "sh",
+      "--mount",
+      `source=${root},target=/w,type=bind`,
+      opts.prewarmImage,
+      "-lc",
+      "ls -laR /w/home >/dev/null 2>&1 || true"
+    ]);
+  } : void 0;
+  const bindRetry = {
+    ...opts.bindRetryDelayMs !== void 0 ? { delayMs: opts.bindRetryDelayMs } : {},
+    ...onBindRetry ? { onBindRetry } : {}
+  };
   if (hasCompose) {
     const projectName = composeProjectName(root);
     logger.info(
       `Force-removing existing ${projectName} containers (volumes preserved)\u2026`
     );
-    const exec = opts.dockerExec ?? spawnDocker;
     const filters = [
       `label=com.docker.compose.project=${projectName}`,
       `name=^${projectName}-`
@@ -5663,27 +5801,43 @@ and retry \`monoceros apply\`.`
       );
       return 1;
     }
-    return runStart({
-      root,
-      ...opts.devcontainerSpawn ? { spawn: opts.devcontainerSpawn } : {},
-      ...opts.logSink ? { logSink: opts.logSink } : {},
-      ...opts.progressSink ? { progressSink: opts.progressSink } : {},
-      ...opts.silent ? { silent: true } : {},
-      logger
-    });
+    return runUpWithBindRetry(
+      (logSink) => runStart({
+        root,
+        ...opts.devcontainerSpawn ? { spawn: opts.devcontainerSpawn } : {},
+        logSink,
+        ...opts.progressSink ? { progressSink: opts.progressSink } : {},
+        ...opts.silent ? { silent: true } : {},
+        ...opts.noCache ? { noCache: true } : {},
+        logger
+      }),
+      opts.logSink,
+      logger,
+      bindRetry
+    );
   }
   logger.info(`Recreating image-mode devcontainer at ${root}\u2026`);
   const spawnFn = opts.devcontainerSpawn ?? spawnDevcontainer;
-  return spawnFn(
-    [
-      "up",
-      "--workspace-folder",
+  return runUpWithBindRetry(
+    (logSink) => spawnFn(
+      [
+        "up",
+        "--workspace-folder",
+        root,
+        "--mount-workspace-git-root=false",
+        "--remove-existing-container",
+        ...opts.noCache ? ["--build-no-cache"] : []
+      ],
       root,
-      "--mount-workspace-git-root=false",
-      "--remove-existing-container"
-    ],
-    root,
-    buildSpawnOptions(opts)
+      {
+        logSink,
+        ...opts.progressSink ? { progressSink: opts.progressSink } : {},
+        ...opts.silent ? { silent: true } : {}
+      }
+    ),
+    opts.logSink,
+    logger,
+    bindRetry
   );
 }
 function runStop(opts) {
@@ -5709,7 +5863,7 @@ function runLogs(opts) {
     opts
   );
 }
-var spawnDockerCompose, spawnDocker;
+var spawnDockerCompose, spawnDocker, BIND_SOURCE_MISSING_RE, BIND_RETRY_ATTEMPTS, BIND_RETRY_DELAY_MS;
 var init_compose = __esm({
   "src/devcontainer/compose.ts"() {
     "use strict";
@@ -5749,6 +5903,102 @@ var init_compose = __esm({
         );
       });
     };
+    BIND_SOURCE_MISSING_RE = /bind source path does not exist/i;
+    BIND_RETRY_ATTEMPTS = 3;
+    BIND_RETRY_DELAY_MS = 500;
+  }
+});
+
+// src/devcontainer/images.ts
+async function resolveContainerImageId(root, exec = spawnDocker) {
+  const ids = await findContainerIds(
+    [`label=devcontainer.local_folder=${root}`],
+    exec
+  );
+  const containerId = ids[0];
+  if (!containerId) return null;
+  const res = await exec(["inspect", "--format", "{{.Image}}", containerId]);
+  if (res.exitCode !== 0) return null;
+  const imageId = res.stdout.trim();
+  return imageId || null;
+}
+async function removeImage(imageId, exec = spawnDocker) {
+  try {
+    const res = await exec(["rmi", imageId]);
+    if (res.exitCode === 0) return "removed";
+    const err = (res.stderr ?? "").toLowerCase();
+    if (err.includes("no such image")) return "absent";
+    if (err.includes("is being used") || err.includes("conflict") || err.includes("in use")) {
+      return "in-use";
+    }
+    return "error";
+  } catch {
+    return "error";
+  }
+}
+var init_images = __esm({
+  "src/devcontainer/images.ts"() {
+    "use strict";
+    init_proxy();
+    init_compose();
+  }
+});
+
+// src/config/machine-state.ts
+import { promises as fsp3 } from "fs";
+import path16 from "path";
+function machineStatePath(home = monocerosHome()) {
+  return path16.join(home, ".machine-state.json");
+}
+async function readMachineState(home = monocerosHome()) {
+  try {
+    const raw = await fsp3.readFile(machineStatePath(home), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null) {
+      return parsed;
+    }
+  } catch {
+  }
+  return {};
+}
+async function writeMachineState(state, home = monocerosHome()) {
+  await fsp3.writeFile(
+    machineStatePath(home),
+    `${JSON.stringify(state, null, 2)}
+`
+  );
+}
+async function recordBuiltImage(record, home = monocerosHome()) {
+  const state = await readMachineState(home);
+  const rest = (state.builtImages ?? []).filter(
+    (r) => r.imageId !== record.imageId
+  );
+  state.builtImages = [...rest, record];
+  await writeMachineState(state, home);
+}
+async function markUpgraded(nowIso, home = monocerosHome()) {
+  const state = await readMachineState(home);
+  state.lastUpgradeAt = nowIso;
+  await writeMachineState(state, home);
+}
+function daysBetween(fromIso, now) {
+  const from = new Date(fromIso).getTime();
+  if (!Number.isFinite(from)) return 0;
+  const ms = now.getTime() - from;
+  return Math.max(0, Math.floor(ms / 864e5));
+}
+function upgradeNudge(state, now, thresholdDays = DEFAULT_UPGRADE_STALE_DAYS) {
+  if (!state.lastUpgradeAt) return null;
+  const days = daysBetween(state.lastUpgradeAt, now);
+  if (days < thresholdDays) return null;
+  return `Tools last refreshed ${days} days ago. Run \`monoceros upgrade\` to update them.`;
+}
+var DEFAULT_UPGRADE_STALE_DAYS;
+var init_machine_state = __esm({
+  "src/config/machine-state.ts"() {
+    "use strict";
+    init_paths();
+    DEFAULT_UPGRADE_STALE_DAYS = 30;
   }
 });
 
@@ -5824,7 +6074,7 @@ var init_docker_mode = __esm({
 // src/devcontainer/identity.ts
 import { spawn as spawn7 } from "child_process";
 import { promises as fs11 } from "fs";
-import path15 from "path";
+import path17 from "path";
 import { consola as consola10 } from "consola";
 async function resolveIdentityWithPrompt(options = {}) {
   const spawnFn = options.spawn ?? realGitConfigGet;
@@ -5880,8 +6130,8 @@ async function resolveIdentityWithPrompt(options = {}) {
   };
 }
 async function collectGitIdentity(devContainerRoot, options = {}) {
-  const gitconfigDir = path15.join(devContainerRoot, ".monoceros");
-  const gitconfigPath = path15.join(gitconfigDir, "gitconfig");
+  const gitconfigDir = path17.join(devContainerRoot, ".monoceros");
+  const gitconfigPath = path17.join(gitconfigDir, "gitconfig");
   const logger = options.logger ?? { info: () => {
   }, warn: () => {
   } };
@@ -6015,7 +6265,7 @@ var init_identity = __esm({
 });
 
 // src/apply/index.ts
-import { existsSync as existsSync7, promises as fs12 } from "fs";
+import { existsSync as existsSync8, promises as fs12 } from "fs";
 import { consola as consola11 } from "consola";
 async function runApply(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -6037,7 +6287,7 @@ ${sectionLine(label)}
     );
   }
   const ymlPath = containerConfigPath(opts.name, home);
-  if (!existsSync7(ymlPath)) {
+  if (!existsSync8(ymlPath)) {
     throw new Error(
       `No such config: ${ymlPath}. Run \`monoceros init <template> ${opts.name}\` first.`
     );
@@ -6236,6 +6486,8 @@ Fix the value in the env file (or the yml).`
     }
     exitCode = await runContainerCycle(targetDir, {
       hasCompose: needsCompose(createOpts),
+      ...opts.rebuild ? { noCache: true } : {},
+      prewarmImage: resolveRuntimeImage(createOpts.runtimeVersion),
       ...opts.dockerExec !== void 0 ? { dockerExec: opts.dockerExec } : {},
       ...opts.devcontainerSpawn !== void 0 ? { devcontainerSpawn: opts.devcontainerSpawn } : {},
       logSink: applyLog.sink,
@@ -6267,6 +6519,30 @@ ${formatted}
 `);
         applyLog.stream.write(`
 ${stripAnsi(formatted)}
+`);
+      }
+      const now = opts.now ?? /* @__PURE__ */ new Date();
+      try {
+        const imageId = await resolveContainerImageId(
+          targetDir,
+          opts.dockerExec ?? defaultDockerExec
+        );
+        if (imageId) {
+          await recordBuiltImage(
+            { imageId, container: opts.name, builtAt: now.toISOString() },
+            home
+          );
+        }
+      } catch {
+      }
+      const nudge = upgradeNudge(
+        await readMachineState(home),
+        now,
+        globalConfig?.upgrade?.staleDays ?? DEFAULT_UPGRADE_STALE_DAYS
+      );
+      if (nudge) {
+        progressOut.write(`
+  ${dim(nudge)}
 `);
       }
     }
@@ -6284,7 +6560,7 @@ ${stripAnsi(formatted)}
   return { targetDir, configPath: ymlPath, containerExitCode: exitCode };
 }
 async function assertSafeTargetDir(targetDir, expectedOrigin) {
-  if (!existsSync7(targetDir)) return;
+  if (!existsSync8(targetDir)) return;
   const entries = await fs12.readdir(targetDir);
   if (entries.length === 0) return;
   const state = await readStateFile(targetDir);
@@ -6395,6 +6671,8 @@ var init_apply = __esm({
     init_briefing();
     init_components();
     init_compose();
+    init_images();
+    init_machine_state();
     init_credentials();
     init_docker_mode();
     init_cli();
@@ -6412,7 +6690,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.20.2" : "dev";
+    CLI_VERSION = true ? "1.21.1" : "dev";
   }
 });
 
@@ -6602,8 +6880,8 @@ var init_completion = __esm({
 });
 
 // src/completion/resolve.ts
-import { existsSync as existsSync8, promises as fs13 } from "fs";
-import path16 from "path";
+import { existsSync as existsSync9, promises as fs13 } from "fs";
+import path18 from "path";
 async function resolveCompletions(line, point, opts = {}) {
   const { prev, current } = parseCompletionLine(line, point);
   const ctx = { prev, current, opts };
@@ -6752,8 +7030,8 @@ function filterPrefix(values, fragment) {
 }
 async function listContainerNames(ctx) {
   const home = ctx.opts.monocerosHome ?? monocerosHome();
-  const dir = path16.join(home, "container-configs");
-  if (!existsSync8(dir)) return [];
+  const dir = path18.join(home, "container-configs");
+  if (!existsSync9(dir)) return [];
   const entries = await fs13.readdir(dir);
   return entries.filter((e) => e.endsWith(".yml")).map((e) => e.slice(0, -".yml".length)).sort();
 }
@@ -7043,9 +7321,12 @@ function generateComposedYml(name, composed, lookupManifest, repoUrls = [], port
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
   lines.push(
-    "# Pinned runtime image version. Reused on every apply; change it with"
+    "# Pinned runtime base image, reused on every apply (never auto-bumped)."
+  );
+  lines.push(
+    "# `monoceros upgrade <name>` refreshes the tooling and moves this to the"
   );
-  lines.push("# `monoceros upgrade <name> [version]`.");
+  lines.push("# latest runtime when a newer one exists.");
   lines.push(`runtimeVersion: ${DEFAULT_RUNTIME_VERSION}`);
   lines.push("");
   if (composed.languages.length > 0) {
@@ -7146,9 +7427,12 @@ function generateDocumentedYml(name, catalog, lookupManifest, repoUrls = [], por
   lines.push("schemaVersion: 1");
   lines.push(`name: ${name}`);
   lines.push(
-    "# Pinned runtime image version. Reused on every apply; change it with"
+    "# Pinned runtime base image, reused on every apply (never auto-bumped)."
   );
-  lines.push("# `monoceros upgrade <name> [version]`.");
+  lines.push(
+    "# `monoceros upgrade <name>` refreshes the tooling and moves this to the"
+  );
+  lines.push("# latest runtime when a newer one exists.");
   lines.push(`runtimeVersion: ${DEFAULT_RUNTIME_VERSION}`);
   lines.push("");
   if (byCategory.language.length > 0) {
@@ -7400,8 +7684,8 @@ var init_generator = __esm({
 });
 
 // src/init/index.ts
-import { existsSync as existsSync9, promises as fs14 } from "fs";
-import path17 from "path";
+import { existsSync as existsSync10, promises as fs14 } from "fs";
+import path19 from "path";
 import { consola as consola13 } from "consola";
 async function runInit(opts) {
   const workbench = opts.workbenchRoot ?? workbenchRoot();
@@ -7416,7 +7700,7 @@ async function runInit(opts) {
     );
   }
   const dest = containerConfigPath(opts.name, home);
-  if (existsSync9(dest)) {
+  if (existsSync10(dest)) {
     throw new Error(
       `Config already exists: ${dest}. Delete it manually before re-running \`monoceros init\` \u2014 this protects any hand-edits.`
     );
@@ -7512,8 +7796,8 @@ async function runInit(opts) {
   }
   await ensureEnvVars(envPath, opts.name, seedVars);
   const documented = !anyComposed;
-  const ymlRel = path17.relative(home, dest);
-  const envRel = path17.relative(home, envPath);
+  const ymlRel = path19.relative(home, dest);
+  const envRel = path19.relative(home, envPath);
   if (documented) {
     logger.success(`Wrote documented default to ${ymlRel} and ${envRel}.`);
     logger.info(
@@ -7875,8 +8159,8 @@ var init_list_components = __esm({
 
 // src/commands/logs.ts
 import { spawn as spawn8 } from "child_process";
-import { existsSync as existsSync10 } from "fs";
-import path18 from "path";
+import { existsSync as existsSync11 } from "fs";
+import path20 from "path";
 import { defineCommand as defineCommand13 } from "citty";
 function tailLogFile(file, follow) {
   const [cmd, args] = follow ? ["tail", ["-F", file]] : ["cat", [file]];
@@ -7919,8 +8203,8 @@ var init_logs = __esm({
       run({ args }) {
         const service = typeof args.service === "string" ? args.service : void 0;
         if (service) {
-          const logFile = path18.join(containerLogsDir(args.name), `${service}.log`);
-          if (existsSync10(logFile)) {
+          const logFile = path20.join(containerLogsDir(args.name), `${service}.log`);
+          if (existsSync11(logFile)) {
             return dispatch(() => tailLogFile(logFile, args.follow));
           }
         }
@@ -8127,8 +8411,8 @@ var init_remove_feature = __esm({
 });
 
 // src/remove/index.ts
-import { existsSync as existsSync11, promises as fs15 } from "fs";
-import path19 from "path";
+import { existsSync as existsSync12, promises as fs15 } from "fs";
+import path21 from "path";
 import { consola as consola19 } from "consola";
 async function runRemove(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -8145,9 +8429,9 @@ async function runRemove(opts) {
   const ymlPath = containerConfigPath(opts.name, home);
   const envPath = containerEnvPath(opts.name, home);
   const containerPath = containerDir(opts.name, home);
-  const hasYml = existsSync11(ymlPath);
-  const hasEnv = existsSync11(envPath);
-  const hasContainer = existsSync11(containerPath);
+  const hasYml = existsSync12(ymlPath);
+  const hasEnv = existsSync12(envPath);
+  const hasContainer = existsSync12(containerPath);
   if (!hasYml && !hasContainer) {
     throw new Error(
       `Nothing to remove for '${opts.name}': neither ${ymlPath} nor ${containerPath} exists.`
@@ -8173,16 +8457,16 @@ async function runRemove(opts) {
   let backupPath = null;
   if (!opts.noBackup && (hasYml || hasContainer)) {
     const ts = (opts.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    backupPath = path19.join(home, "container-backups", `${opts.name}-${ts}`);
+    backupPath = path21.join(home, "container-backups", `${opts.name}-${ts}`);
     await fs15.mkdir(backupPath, { recursive: true });
     if (hasYml) {
-      await fs15.copyFile(ymlPath, path19.join(backupPath, `${opts.name}.yml`));
+      await fs15.copyFile(ymlPath, path21.join(backupPath, `${opts.name}.yml`));
     }
     if (hasEnv) {
-      await fs15.copyFile(envPath, path19.join(backupPath, `${opts.name}.env`));
+      await fs15.copyFile(envPath, path21.join(backupPath, `${opts.name}.env`));
     }
     if (hasContainer) {
-      await fs15.cp(containerPath, path19.join(backupPath, "container"), {
+      await fs15.cp(containerPath, path21.join(backupPath, "container"), {
         recursive: true
       });
     }
@@ -8342,8 +8626,8 @@ var init_remove2 = __esm({
 });
 
 // src/restore/index.ts
-import { existsSync as existsSync12, promises as fs16 } from "fs";
-import path20 from "path";
+import { existsSync as existsSync13, promises as fs16 } from "fs";
+import path22 from "path";
 import { consola as consola21 } from "consola";
 async function runRestore(opts) {
   const home = opts.monocerosHome ?? monocerosHome();
@@ -8351,8 +8635,8 @@ async function runRestore(opts) {
     info: (msg) => consola21.info(msg),
     success: (msg) => consola21.success(msg)
   };
-  const backup = path20.resolve(opts.backupPath);
-  if (!existsSync12(backup)) {
+  const backup = path22.resolve(opts.backupPath);
+  if (!existsSync13(backup)) {
     throw new Error(`Backup not found: ${backup}.`);
   }
   const stat = await fs16.stat(backup);
@@ -8373,24 +8657,24 @@ async function runRestore(opts) {
   }
   const ymlFile = ymlFiles[0];
   const name = ymlFile.replace(/\.yml$/, "");
-  const containerInBackup = path20.join(backup, "container");
-  const hasContainer = existsSync12(containerInBackup);
-  const envInBackup = path20.join(backup, `${name}.env`);
-  const hasEnv = existsSync12(envInBackup);
+  const containerInBackup = path22.join(backup, "container");
+  const hasContainer = existsSync13(containerInBackup);
+  const envInBackup = path22.join(backup, `${name}.env`);
+  const hasEnv = existsSync13(envInBackup);
   const destYml = containerConfigPath(name, home);
   const destContainer = containerDir(name, home);
-  if (existsSync12(destYml)) {
+  if (existsSync13(destYml)) {
     throw new Error(
       `Refusing to restore: ${destYml} already exists. Remove the current container first (\`monoceros remove ${name}\`) or rename the existing config.`
     );
   }
-  if (hasContainer && existsSync12(destContainer)) {
+  if (hasContainer && existsSync13(destContainer)) {
     throw new Error(
       `Refusing to restore: ${destContainer} already exists. Remove the current container first (\`monoceros remove ${name}\`).`
     );
   }
   await fs16.mkdir(containerConfigsDir(home), { recursive: true });
-  await fs16.copyFile(path20.join(backup, ymlFile), destYml);
+  await fs16.copyFile(path22.join(backup, ymlFile), destYml);
   if (hasEnv) {
     await fs16.copyFile(envInBackup, containerEnvPath(name, home));
   }
@@ -8701,9 +8985,9 @@ var init_remove_service = __esm({
 
 // src/devcontainer/browser-bridge.ts
 import { spawn as spawn9 } from "child_process";
-import { existsSync as existsSync13, promises as fsp2, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync14, promises as fsp4, readFileSync as readFileSync6 } from "fs";
 import http from "http";
-import path21 from "path";
+import path23 from "path";
 function parseCallbackTarget(authUrl) {
   try {
     const u = new URL(authUrl);
@@ -8733,12 +9017,12 @@ function openInBrowser(url) {
   }
 }
 async function startBrowserBridge(opts) {
-  const relayDir = path21.join(opts.root, RELAY_DIRNAME);
-  const relayScript = path21.join(relayDir, "xdg-open");
-  const urlFile = path21.join(relayDir, "url");
-  await fsp2.mkdir(relayDir, { recursive: true });
-  await fsp2.rm(urlFile, { force: true });
-  await fsp2.writeFile(
+  const relayDir = path23.join(opts.root, RELAY_DIRNAME);
+  const relayScript = path23.join(relayDir, "xdg-open");
+  const urlFile = path23.join(relayDir, "url");
+  await fsp4.mkdir(relayDir, { recursive: true });
+  await fsp4.rm(urlFile, { force: true });
+  await fsp4.writeFile(
     relayScript,
     `#!/bin/sh
 printf '%s\\n' "$1" > "$(dirname "$0")/url"
@@ -8746,7 +9030,7 @@ exit 0
 `,
     { mode: 493 }
   );
-  await fsp2.chmod(relayScript, 493);
+  await fsp4.chmod(relayScript, 493);
   const servers = [];
   let handled = false;
   const onUrl = (url) => {
@@ -8779,7 +9063,7 @@ exit 0
     servers.push(server);
   };
   const poll = setInterval(() => {
-    if (handled || !existsSync13(urlFile)) return;
+    if (handled || !existsSync14(urlFile)) return;
     let content = "";
     try {
       content = readFileSync6(urlFile, "utf8");
@@ -8795,7 +9079,7 @@ exit 0
     async dispose() {
       clearInterval(poll);
       for (const s of servers) s.close();
-      await fsp2.rm(relayDir, { recursive: true, force: true });
+      await fsp4.rm(relayDir, { recursive: true, force: true });
     }
   };
 }
@@ -8808,18 +9092,18 @@ var init_browser_bridge = __esm({
 });
 
 // src/devcontainer/claude-trust.ts
-import { existsSync as existsSync14, promises as fsp3 } from "fs";
-import path22 from "path";
+import { existsSync as existsSync15, promises as fsp5 } from "fs";
+import path24 from "path";
 function resolveContainerCwd(name, cwd) {
   const workspace = `/workspaces/${name}`;
   if (!cwd) return workspace;
-  return path22.posix.isAbsolute(cwd) ? cwd : path22.posix.join(workspace, cwd);
+  return path24.posix.isAbsolute(cwd) ? cwd : path24.posix.join(workspace, cwd);
 }
 async function preApproveClaudeProject(opts) {
-  const file = path22.join(opts.root, "home", ".claude.json");
-  if (!existsSync14(file)) return;
+  const file = path24.join(opts.root, "home", ".claude.json");
+  if (!existsSync15(file)) return;
   try {
-    const raw = await fsp3.readFile(file, "utf8");
+    const raw = await fsp5.readFile(file, "utf8");
     const config = raw.trim() ? JSON.parse(raw) : {};
     if (typeof config !== "object" || config === null) return;
     const dir = resolveContainerCwd(opts.name, opts.cwd);
@@ -8839,7 +9123,7 @@ async function preApproveClaudeProject(opts) {
     if (typeof entry2.projectOnboardingSeenCount !== "number") {
       entry2.projectOnboardingSeenCount = 1;
     }
-    await fsp3.writeFile(file, `${JSON.stringify(config, null, 2)}
+    await fsp5.writeFile(file, `${JSON.stringify(config, null, 2)}
 `);
   } catch {
   }
@@ -8851,8 +9135,8 @@ var init_claude_trust = __esm({
 });
 
 // src/devcontainer/shell.ts
-import { existsSync as existsSync15 } from "fs";
-import path23 from "path";
+import { existsSync as existsSync16 } from "fs";
+import path25 from "path";
 async function runShell(opts) {
   assertContainerExists(opts.root);
   const spawnFn = opts.spawn ?? spawnDevcontainer;
@@ -8875,7 +9159,7 @@ async function runShell(opts) {
   );
 }
 function assertContainerExists(root) {
-  if (!existsSync15(path23.join(root, ".devcontainer"))) {
+  if (!existsSync16(path25.join(root, ".devcontainer"))) {
     throw new Error(
       `No .devcontainer/ at ${root}. Run \`monoceros apply <name>\` first.`
     );
@@ -9193,11 +9477,11 @@ var init_stop = __esm({
 });
 
 // src/tunnel/resolve.ts
-import { existsSync as existsSync16 } from "fs";
-import path24 from "path";
+import { existsSync as existsSync17 } from "fs";
+import path26 from "path";
 async function resolveTunnelTarget(opts) {
   const ymlPath = containerConfigPath(opts.name, opts.monocerosHome);
-  if (!existsSync16(ymlPath)) {
+  if (!existsSync17(ymlPath)) {
     throw new Error(
       `No yml profile for '${opts.name}' at ${ymlPath}. Run \`monoceros init ${opts.name}\` first.`
     );
@@ -9205,13 +9489,13 @@ async function resolveTunnelTarget(opts) {
   const parsed = await readConfig(ymlPath);
   const config = parsed.config;
   const containerRoot = containerDir(opts.name, opts.monocerosHome);
-  if (!existsSync16(containerRoot)) {
+  if (!existsSync17(containerRoot)) {
     throw new Error(
       `Container '${opts.name}' is not materialised at ${containerRoot}. Run \`monoceros apply ${opts.name}\` first.`
     );
   }
-  const composePath = path24.join(containerRoot, ".devcontainer", "compose.yaml");
-  const isCompose = existsSync16(composePath);
+  const composePath = path26.join(containerRoot, ".devcontainer", "compose.yaml");
+  const isCompose = existsSync17(composePath);
   const parsedTarget = parseTargetArg(opts.target, config);
   const docker = opts.docker ?? defaultDockerExec;
   if (isCompose) {
@@ -9629,8 +9913,69 @@ var init_tunnel = __esm({
   }
 });
 
+// src/upgrade/prune.ts
+function selectStaleImages(registry, currentContainerNames) {
+  const byContainer = /* @__PURE__ */ new Map();
+  for (const rec of registry) {
+    const list = byContainer.get(rec.container) ?? [];
+    list.push(rec);
+    byContainer.set(rec.container, list);
+  }
+  const stale = [];
+  const keep = [];
+  for (const [container, records] of byContainer) {
+    if (!currentContainerNames.has(container)) {
+      stale.push(...records);
+      continue;
+    }
+    const sorted = [...records].sort(
+      (a, b) => a.builtAt < b.builtAt ? 1 : a.builtAt > b.builtAt ? -1 : 0
+    );
+    keep.push(sorted[0]);
+    stale.push(...sorted.slice(1));
+  }
+  return { stale, keep };
+}
+async function pruneStaleImages(opts) {
+  const exec = opts.exec ?? spawnDocker;
+  const state = await readMachineState(opts.home);
+  const registry = state.builtImages ?? [];
+  const { stale, keep } = selectStaleImages(
+    registry,
+    opts.currentContainerNames
+  );
+  const survivors = [...keep];
+  let removed = 0;
+  for (const rec of stale) {
+    const outcome = await removeImage(rec.imageId, exec);
+    if (outcome === "removed") {
+      removed += 1;
+    } else if (outcome === "absent") {
+    } else {
+      survivors.push(rec);
+    }
+  }
+  state.builtImages = survivors;
+  await writeMachineState(state, opts.home);
+  if (removed > 0) {
+    opts.logger?.info(
+      `Pruned ${removed} stale Monoceros image${removed === 1 ? "" : "s"}.`
+    );
+  }
+  return { removed, attempted: stale.length };
+}
+var init_prune = __esm({
+  "src/upgrade/prune.ts"() {
+    "use strict";
+    init_machine_state();
+    init_proxy();
+    init_compose();
+    init_images();
+  }
+});
+
 // src/upgrade/index.ts
-import { existsSync as existsSync17, promises as fs17 } from "fs";
+import { existsSync as existsSync18, promises as fs17 } from "fs";
 import { consola as consola34 } from "consola";
 async function fetchRuntimeVersions() {
   const tokenUrl = `https://ghcr.io/token?service=ghcr.io&scope=repository:${RUNTIME_REPO}:pull`;
@@ -9683,53 +10028,113 @@ async function runUpgrade(opts) {
     );
     return 0;
   }
-  if (!opts.name) {
-    throw new Error(
-      "Usage: `monoceros upgrade <name> [version]` (or `monoceros upgrade --list`)."
-    );
+  if (opts.version !== void 0) {
+    if (!opts.name) {
+      throw new Error(
+        "A specific version can only be pinned for one container: `monoceros upgrade <name> <version>`."
+      );
+    }
+    if (!VERSION_RE.test(opts.version)) {
+      throw new Error(
+        `Invalid version ${JSON.stringify(opts.version)}. Expected an exact version like '1.1.0'.`
+      );
+    }
   }
-  const ymlPath = containerConfigPath(opts.name, home);
-  if (!existsSync17(ymlPath)) {
+  if (opts.name && !existsSync18(containerConfigPath(opts.name, home))) {
     throw new Error(
-      `No such config: ${ymlPath}. Run \`monoceros init <template> ${opts.name}\` first.`
+      `No such config: ${containerConfigPath(opts.name, home)}. Run \`monoceros init <template> ${opts.name}\` first.`
     );
   }
-  let target = opts.version;
-  if (target !== void 0 && !VERSION_RE.test(target)) {
-    throw new Error(
-      `Invalid version ${JSON.stringify(target)}. Expected an exact version like '1.1.0'.`
-    );
+  const targets = opts.name ? [opts.name] : await listContainerNames2(home);
+  const apply = opts.applyRunner ?? runApply;
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  const pruneAndStamp = async () => {
+    const result = await pruneStaleImages({
+      home,
+      currentContainerNames: new Set(await listContainerNames2(home)),
+      ...opts.dockerExec ? { exec: opts.dockerExec } : {}
+    });
+    await markUpgraded(now.toISOString(), home);
+    return result;
+  };
+  if (targets.length === 0) {
+    logger.info("No containers to upgrade.");
+    await pruneAndStamp();
+    return 0;
   }
-  if (target === void 0) {
+  let pinVersion = opts.version;
+  if (pinVersion === void 0) {
     const versions = await fetchVersions();
-    target = versions[versions.length - 1];
-    if (!target) {
+    pinVersion = versions[versions.length - 1];
+    if (!pinVersion) {
       throw new Error("Could not determine the latest runtime version.");
     }
-    logger.info(`Latest published runtime version: ${target}`);
+    logger.info(`Latest published runtime version: ${pinVersion}`);
+  }
+  let worstExit = 0;
+  let bumped = 0;
+  for (const name of targets) {
+    const ymlPath = containerConfigPath(name, home);
+    if (!existsSync18(ymlPath)) continue;
+    const raw = await fs17.readFile(ymlPath, "utf8");
+    const updated = setRuntimeVersion(raw, pinVersion);
+    if (updated !== raw) {
+      await fs17.writeFile(ymlPath, updated);
+      bumped += 1;
+      logger.info(`Pinned '${name}' to runtime ${pinVersion}.`);
+    }
+    logger.info(`Refreshing '${name}' (rebuild \u2014 latest tools)\u2026`);
+    const result = await apply({
+      name,
+      cliVersion: opts.cliVersion,
+      monocerosHome: home,
+      rebuild: true
+    });
+    if (result.containerExitCode !== 0) {
+      worstExit = result.containerExitCode;
+      logger.warn?.(
+        `Upgrade of '${name}' failed (exit ${result.containerExitCode}).`
+      );
+    }
   }
-  const raw = await fs17.readFile(ymlPath, "utf8");
-  const updated = setRuntimeVersion(raw, target);
-  if (updated === raw) {
-    logger.info(`'${opts.name}' is already pinned to runtime ${target}.`);
-  } else {
-    await fs17.writeFile(ymlPath, updated);
-    logger.success(`Pinned '${opts.name}' to runtime ${target}. Re-applying\u2026`);
+  if (worstExit === 0) {
+    const prune = await pruneAndStamp();
+    logger.success(
+      `Upgraded ${opts.name ? `'${opts.name}'` : `${targets.length} container${targets.length === 1 ? "" : "s"}`}
+  tools     rebuilt \u2014 latest pulled
+  base      ${pinVersion} ${bumped > 0 ? `(${bumped} bumped)` : "(already latest)"}
+  pruned    ${formatPruneLine(prune)}
+  recorded  ${now.toISOString().slice(0, 16).replace("T", " ")} UTC`
+    );
+  }
+  return worstExit;
+}
+function formatPruneLine(prune) {
+  const gone = prune.attempted - prune.removed;
+  if (prune.attempted === 0) return "nothing stale";
+  if (prune.removed === 0) {
+    return `0 removed (${gone} stale ${gone === 1 ? "entry" : "entries"} already gone)`;
+  }
+  const base = `${prune.removed} image${prune.removed === 1 ? "" : "s"} removed`;
+  return gone > 0 ? `${base}, ${gone} stale ${gone === 1 ? "entry" : "entries"} cleared` : base;
+}
+async function listContainerNames2(home) {
+  try {
+    const entries = await fs17.readdir(containerConfigsDir(home));
+    return entries.filter((e) => e.endsWith(".yml")).map((e) => e.slice(0, -".yml".length));
+  } catch {
+    return [];
   }
-  const apply = opts.applyRunner ?? runApply;
-  const result = await apply({
-    name: opts.name,
-    cliVersion: opts.cliVersion,
-    monocerosHome: home
-  });
-  return result.containerExitCode;
 }
 var RUNTIME_REPO, VERSION_RE;
 var init_upgrade = __esm({
   "src/upgrade/index.ts"() {
     "use strict";
     init_paths();
+    init_machine_state();
     init_catalog();
+    init_proxy();
+    init_prune();
     init_apply();
     RUNTIME_REPO = "getmonoceros/monoceros-runtime";
     VERSION_RE = /^\d+\.\d+\.\d+$/;
@@ -9749,7 +10154,7 @@ var init_upgrade2 = __esm({
       meta: {
         name: "upgrade",
         group: "lifecycle",
-        description: "Pin a container to a newer runtime image version and re-apply. `monoceros upgrade <name>` pins to the latest published version; `monoceros upgrade <name> <version>` pins to an exact one; `monoceros upgrade --list` lists available versions."
+        description: "Refresh tooling to the latest (rebuilds feature layers, bumps the runtime base when newer) and prune stale Monoceros images. `monoceros upgrade` refreshes all containers; `monoceros upgrade <name>` one; `monoceros upgrade <name> <version>` pins that base version; `monoceros upgrade --list` lists runtime versions."
       },
       args: {
         name: {
@@ -10119,25 +10524,25 @@ function detectHelpRequest(argv, main2) {
   const separatorIdx = argv.indexOf("--");
   if (helpIdx === -1) return null;
   if (separatorIdx !== -1 && separatorIdx < helpIdx) return null;
-  const path25 = [];
+  const path27 = [];
   const tokens = argv.slice(
     0,
     separatorIdx === -1 ? argv.length : separatorIdx
   );
   let cursor = main2;
   const mainName = (main2.meta ?? {}).name ?? "monoceros";
-  path25.push(mainName);
+  path27.push(mainName);
   for (const tok of tokens) {
     if (tok.startsWith("-")) continue;
     const subs = cursor.subCommands ?? {};
     if (tok in subs) {
       cursor = subs[tok];
-      path25.push(tok);
+      path27.push(tok);
       continue;
     }
     break;
   }
-  return { path: path25, cmd: cursor };
+  return { path: path27, cmd: cursor };
 }
 async function maybeRenderHelp(argv, main2) {
   const hit = detectHelpRequest(argv, main2);