@tdk-landscape/tdk-cli-core 1.3.155 → 1.3.156

package/cli/dist/commands/doctor.js

@@ -6,24 +6,29 @@ import { join, normalize, relative } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 import { hasVerdaccioLicense } from "../generator/extension-fetch.js";
+import { readProjectConfig } from "../generator/template-engine.js";
 import { DEVCONTAINER_DOCKER_FIX, detectHost, isContainerHost, WEBCONTAINER_DOCS, WEBCONTAINER_UP_MESSAGE, } from "../utils/agent-host.js";
 import { projectNeedsBun } from "../utils/bun-requirement.js";
 import { AUTOGENERATED_DIR, CONTAINER_RUNTIME_CHECK, MASTER_CONFIG_FILES, PACKAGE_JSON, REQUIRED_PACKAGE_SCRIPTS, } from "../utils/constants.js";
 import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.js";
+import { checkCrashLoopingContainers } from "../utils/doctor-crashloop.js";
+import { applyDoctorFixes, checkDuplicateTdkInstalls, hasFailedActions, planDoctorFixes, } from "../utils/doctor-fix.js";
 import { checkDiskSpace, dockerDesktopStuck } from "../utils/doctor-host.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeAdvertisedProbes, summarizeServiceProbes, summarizeSmokeResults, } from "../utils/doctor-runtime.js";
 import { checkStarlarkLoadExports } from "../utils/doctor-starlark.js";
 import { checkDockerNetworkCapacity, checkDuplicateResourceNames, checkDuplicateResourcePorts, checkFrontendBackendUrls, checkMigrationsInApi, checkNatsBroker, checkPrismaConsistency, checkResourcePackageJson, checkServiceUrlPorts, checkSharedPlatformPostgres, checkSharedStackRoutes, checkTiltInstances, } from "../utils/doctor-wiring.js";
+import { findProjectTiltUpPids } from "../utils/down-cleanup.js";
 import { validateEnvFile } from "../utils/env-validator.js";
 import { execAsync, isExecTimeout } from "../utils/exec-async.js";
 import { formatCount } from "../utils/formatting.js";
 import { getHostPortPlan, resolveRuntimeIngressPort } from "../utils/host-port-config.js";
 import { createHostPortPlan } from "../utils/host-port-plan.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
+import { promptConfirm } from "../utils/prompt.js";
 import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
 import { checkCircularDependencies, checkDependsOnShape, checkSchemaVersions, checkServicePorts, } from "../utils/service-config-checks.js";
-import { buildAdvertisedTargets, buildHealthTargets, pingHealthTargets, } from "../utils/service-urls.js";
+import { buildAdvertisedTargets, buildHealthTargets, getProjectName, pingHealthTargets, } from "../utils/service-urls.js";
 import { discoverResourcesFromRoot } from "../utils/services.js";
 import { buildSmokePlans, readOnlySmokePlans, runSmokePlans } from "../utils/smoke.js";
 import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
@@ -978,6 +983,26 @@ async function checkAdvertisedEndpoints(timeoutMs, ingressPort) {
     }
     return summarizeAdvertisedProbes(await pingHealthTargets(targets, timeoutMs));
 }
+function printFixActions(actions, dryRun) {
+    if (actions.length === 0) {
+        console.log(`${chalk.green("✓")} Nothing to repair\n`);
+        return;
+    }
+    for (const action of actions) {
+        const label = action.status === "planned"
+            ? `${chalk.cyan("would run")}`
+            : action.status === "applied"
+                ? chalk.green("ran")
+                : action.status === "failed"
+                    ? chalk.red("failed")
+                    : chalk.gray("skipped");
+        const detail = action.status === "planned" ? "" : ` (${action.reason})`;
+        console.log(`${label}: ${action.command}${detail}`);
+    }
+    if (dryRun)
+        console.log(chalk.gray("\nDry run: nothing was changed."));
+    console.log("");
+}
 export const doctorCommand = new Command("doctor")
     .description("Check environment readiness for TDK")
     .option("--json", "Output a versioned JSON readiness report", false)
@@ -991,6 +1016,9 @@ export const doctorCommand = new Command("doctor")
 })
     .option("--no-ping", "Skip pinging running services' /health endpoints")
     .option("--strict", "Fail warnings such as a WSL project under /mnt/c")
+    .option("--fix", "Repair this project's unused Docker networks and leftover doctor probes", false)
+    .option("--dry-run", "With --fix: list the repairs without changing anything", false)
+    .option("-y, --yes", "With --fix: apply every repair without asking", false)
     .option("--ping-timeout <ms>", "Per-service ping timeout in milliseconds", String(DEFAULT_PING_TIMEOUT_MS))
     .action(async (options) => {
     // Validate before running any probe; parseInt would silently accept "100ms" or "1.5".
@@ -1005,6 +1033,14 @@ export const doctorCommand = new Command("doctor")
         process.exit(2);
         return;
     }
+    if ((options.dryRun || options.yes) && !options.fix) {
+        const message = `${options.dryRun ? "--dry-run" : "--yes"} only applies with --fix`;
+        if (options.json)
+            console.log(JSON.stringify(createDoctorReport([], false, [{ code: "USAGE", message }])));
+        console.error(message);
+        process.exit(2);
+        return;
+    }
     if (!options.json) {
         console.log("TDK doctor checks your local Docker + Tilt development environment; it does not check cluster deployments.");
     }
@@ -1051,6 +1087,51 @@ export const doctorCommand = new Command("doctor")
         console.log("Checking environment...\n");
     }
     const projectRoot = findProjectRoot();
+    // Repairs run before the checks so the checks report the state after the fix.
+    let fixActions;
+    if (options.fix) {
+        try {
+            let projectName;
+            if (projectRoot) {
+                try {
+                    projectName = readProjectConfig(projectRoot).project.name;
+                }
+                catch {
+                    // An unreadable config is reported by the project checks below.
+                }
+            }
+            const tiltPids = projectRoot
+                ? findProjectTiltUpPids(join(projectRoot, ".tdk", ".tdk-out", "Tiltfile"))
+                : [];
+            const planned = await planDoctorFixes(projectName, undefined, tiltPids.length > 0
+                ? `Tilt is running for this project (pid ${tiltPids.join(", ")}); run tdk down first`
+                : undefined);
+            fixActions = await applyDoctorFixes(planned, {
+                dryRun: options.dryRun,
+                confirm: options.yes || (!options.json && process.stdin.isTTY)
+                    ? async (action) => options.yes ||
+                        (await promptConfirm({
+                            message: `Run \`${action.command}\` (${action.check}, ${action.reason})?`,
+                        }))
+                    : undefined,
+            });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            fixActions = [
+                {
+                    id: "plan-fixes",
+                    check: "Docker networks",
+                    scope: "project",
+                    command: "docker network ls",
+                    status: "failed",
+                    reason: `could not list Docker networks: ${reason.split(/\r?\n/)[0]}`,
+                },
+            ];
+        }
+        if (!options.json)
+            printFixActions(fixActions, options.dryRun);
+    }
     let hostPortPlan;
     let portPlanError;
     try {
@@ -1094,6 +1175,7 @@ export const doctorCommand = new Command("doctor")
         () => checkPublishedBindAddress(process.env, options.strict),
         // Each project needs several networks; a full address pool fails `tdk up` late.
         () => checkDockerNetworkCapacity(),
+        () => checkDuplicateTdkInstalls(),
     ];
     const projectChecks = [
         () => checkTdkVersion(),
@@ -1134,6 +1216,24 @@ export const doctorCommand = new Command("doctor")
         },
         // Runtime checks: skip gracefully if the stack isn't started yet.
         checkContainerResourceHealth,
+        // A container restarted thousands of times is invisible in `docker ps` until someone looks.
+        () => {
+            const root = findProjectRoot() ?? process.cwd();
+            let secrets = [];
+            try {
+                secrets = envSecretValues(root);
+            }
+            catch {
+                // Without the secret values, log lines cannot be shown safely.
+                return {
+                    name: "Crash-looping containers",
+                    didPass: true,
+                    isSkipped: true,
+                    message: "Could not read .env - skipped crash-loop check",
+                };
+            }
+            return checkCrashLoopingContainers(getProjectName(), secrets);
+        },
         // When Tilt is up, surface red resources (Traefik/apps never started).
         checkTiltResourceHealth,
     ];
@@ -1160,6 +1260,11 @@ export const doctorCommand = new Command("doctor")
         }
     }
     const report = createDoctorReport(orderDoctorResults(results), inProject, errors, hostPortPlan, host);
+    if (fixActions)
+        report.data.actions = fixActions;
+    const fixFailed = fixActions ? hasFailedActions(fixActions) : false;
+    if (fixFailed)
+        report.data.ready = false;
     const exitCode = getDoctorExitCode(report);
     const allPassed = report.data.ready;
     if (options.json) {

package/cli/dist/commands/up.js

@@ -29,6 +29,7 @@ import { buildSmokePlans, formatSmokeFailure, runSmokePlans } from "../utils/smo
 import { buildStartupReport, formatStartupReport, isStartupStalled, } from "../utils/startup-report.js";
 import { evaluateTdkVersionFloor } from "../utils/tdk-version.js";
 import { buildTiltUpArgs, runTilt } from "../utils/tilt.js";
+import { findTiltPortOwner, isForeignTilt } from "../utils/tilt-port-owner.js";
 import { stopTiltOnPort } from "../utils/tilt-process.js";
 import { parseTiltPort, resolveTiltPort, secondUpAction, stopTiltForUp, } from "../utils/tilt-startup.js";
 import { findUnknownServices, resolveOnlySelection } from "../utils/up-only.js";
@@ -369,13 +370,35 @@ export const upCommand = new Command("up")
         const watchedPort = configuredTiltPort ?? basePort;
         const candidatePorts = options.only ? [...new Set([basePort, watchedPort])] : [watchedPort];
         const running = [];
+        const foreign = [];
         for (const candidate of candidatePorts) {
-            if ((await tiltGetUiResources(candidate)) !== null)
+            if ((await tiltGetUiResources(candidate)) === null)
+                continue;
+            // A Tilt on this port may belong to another project; that is not "this environment is running".
+            const owner = findTiltPortOwner(candidate);
+            if (owner && isForeignTilt(owner, projectRoot)) {
+                foreign.push({ port: candidate, root: owner.root });
+            }
+            else {
                 running.push(candidate);
+            }
         }
+        if (foreign.length > 0 && configuredTiltPort !== undefined) {
+            const other = foreign[0];
+            const message = `TILT_PORT=${other?.port} is used by another project's Tilt (${other?.root}). Choose a free port, or run tdk down in that project.`;
+            emit?.({ ok: false }, [{ code: "TILT_PORT_IN_USE", message }]);
+            showErrorAndExit(message);
+        }
+        if (!options.quiet) {
+            for (const other of foreign) {
+                console.log(chalk.yellow(`⚠️  Tilt on port ${other.port} belongs to another project (${other.root}); this project will use another port.`));
+            }
+        }
+        // --force replaces this project's Tilt; it must never stop another project's.
+        const force = options.force && foreign.length === 0;
         const decision = secondUpAction({
             runningPorts: running,
-            force: options.force,
+            force,
             only: Boolean(options.only),
         });
         if (decision.action === "already-running") {
@@ -400,7 +423,7 @@ export const upCommand = new Command("up")
         }
         const resolution = await resolveTiltPort({
             configuredPort: configuredTiltPort,
-            force: options.force,
+            force,
             basePort,
             findAvailablePort,
         });
@@ -410,7 +433,7 @@ export const upCommand = new Command("up")
             console.log(chalk.blue(`🔄 Auto-switching to port ${port}\n`));
         }
         process.env.TILT_PORT = port.toString();
-        await stopTiltForUp({ force: options.force, quiet: options.quiet, port }, {
+        await stopTiltForUp({ force, quiet: options.quiet, port }, {
             stop: stopTiltOnPort,
             log: (message) => console.log(chalk.yellow(message)),
             wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),

package/cli/dist/generator/template-engine.js

@@ -505,6 +505,26 @@ export async function generateMasterConfigs(projectRoot, options = {}) {
 // vendor a working copy into .tdk/.tdk-out/tdk-cli-ext/ at generation time.
 // This makes `tdk up` work offline and on any machine - no hardcoded paths,
 // no dependency on a private GitHub repo.
+// The engine's own unit tests (for example wake-gateway/decide.test.ts, which imports bun:test) are
+// not needed to run a stack. Vendoring them under .tdk/.tdk-out makes a Node project's test runner
+// (Vitest, Jest) discover them and fail, so they are left out of the vendored copy.
+const TEST_FILE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+export function isTestFile(filePath) {
+    return TEST_FILE_PATTERN.test(filePath);
+}
+function removeVendoredTestFiles(dir) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            removeVendoredTestFiles(entryPath);
+        }
+        else if (isTestFile(entryPath)) {
+            fs.rmSync(entryPath, { force: true });
+        }
+    }
+}
 const TDK_EXTENSION_DIRS = ["engine", "discovery", "specs", "ext"];
 const PROJECT_RUNTIME_ASSET_DIRS = [["shared-platform-engineering", "docker-templates"]];
 const REQUIRED_DOCKER_TEMPLATE_FILES = [
@@ -618,8 +638,11 @@ async function vendorTdkExtension(projectRoot) {
     }
     fs.copyFileSync(path.join(sourceRoot, "Tiltfile"), path.join(vendoredDir, "Tiltfile"));
     for (const dir of TDK_EXTENSION_DIRS) {
+        // A project vendored by an older TDK already holds test files; cpSync only adds, so drop them.
+        removeVendoredTestFiles(path.join(vendoredDir, dir));
         fs.cpSync(path.join(sourceRoot, dir), path.join(vendoredDir, dir), {
             recursive: true,
+            filter: (source) => !isTestFile(source),
         });
     }
     console.log(`✓ Vendored TDK extension → .tdk/.tdk-out/tdk-cli-ext/`);

package/cli/dist/utils/doctor-crashloop.js

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { toComposeProjectPrefix } from "./doctor-runtime.js";
+import { redactSecrets } from "./secret-redaction.js";
+const execFilePromise = promisify(execFile);
+const DOCKER_TIMEOUT_MS = 10_000;
+/** Restarts that make a container a crash loop rather than a one-off. */
+export const CRASH_LOOP_RESTARTS = 5;
+/** A container that restarted this recently is still looping; an old count on a healthy container is history. */
+const RECENT_START_MS = 10 * 60_000;
+const LOG_LINES = 3;
+const LOG_LINE_MAX = 200;
+const runDocker = async (args) => {
+    const { stdout, stderr } = await execFilePromise("docker", args, {
+        encoding: "utf-8",
+        timeout: DOCKER_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    return `${stdout}${stderr}`;
+};
+/** Whether this container's compose project belongs to the TDK project, however the engine spelled the separator. */
+export function belongsToProject(composeProject, projectName) {
+    const prefix = toComposeProjectPrefix(projectName).toLowerCase();
+    const label = composeProject.replace(/-/g, "_").toLowerCase();
+    return label === prefix || label.startsWith(`${prefix}_`);
+}
+export function isCrashLooping(state, now = Date.now()) {
+    if (state.status === "restarting")
+        return true;
+    if (state.restartCount < CRASH_LOOP_RESTARTS)
+        return false;
+    if (state.status === "running") {
+        const started = Date.parse(state.startedAt);
+        return Number.isNaN(started) || now - started < RECENT_START_MS;
+    }
+    // Stopped: only a recent failure is a loop that gave up (restart policy exhausted). A container stopped by hand
+    // keeps its old restart count, and that is history.
+    const finished = Date.parse(state.finishedAt ?? "");
+    return state.exitCode !== 0 && !Number.isNaN(finished) && now - finished < RECENT_START_MS;
+}
+/** A hint for a cause that the last log lines name. Null when they do not say. */
+export function crashLoopHint(logs, state) {
+    const database = /database "([^"]+)" does not exist/i.exec(logs);
+    if (database) {
+        return `database "${database[1]}" does not exist: re-run the project's database provisioning (tdk up) or create it`;
+    }
+    if (/Cannot find module|MODULE_NOT_FOUND|module not found/i.test(logs)) {
+        return "a module is missing from the image: rebuild it (tdk up --force) after checking the resource's dependencies";
+    }
+    if (/EADDRINUSE|address already in use/i.test(logs)) {
+        return "the port inside the container is already in use: check for two processes started by the same command";
+    }
+    if (/ECONNREFUSED|connection refused|could not connect/i.test(logs)) {
+        return "a dependency is not reachable: check that the service it connects to is running and healthy";
+    }
+    if (/(is not set|is required|missing required|undefined).*(env|environment|variable)|environment variable.*(missing|not set|required)/i.test(logs)) {
+        return "a required environment variable is missing: check the project's .env";
+    }
+    if (state.exitCode === 137)
+        return "killed (exit 137), usually out of memory: raise the container's memory limit";
+    return null;
+}
+function parseStates(output) {
+    const states = [];
+    for (const line of output.split(/\r?\n/)) {
+        const [name, restarts, status, startedAt, exitCode, finishedAt] = line.split("\t");
+        if (!name || restarts === undefined)
+            continue;
+        states.push({
+            name: name.replace(/^\//, ""),
+            restartCount: Number(restarts) || 0,
+            status: status ?? "",
+            startedAt: startedAt ?? "",
+            exitCode: Number(exitCode) || 0,
+            finishedAt: finishedAt ?? "",
+        });
+    }
+    return states;
+}
+/** Containers of this project that keep restarting, with their last log lines and a cause hint when one is clear. */
+export async function checkCrashLoopingContainers(projectName, secrets = [], run = runDocker, now = Date.now()) {
+    const name = "Crash-looping containers";
+    let candidates;
+    try {
+        const listing = await run([
+            "ps",
+            "-a",
+            "--format",
+            '{{.ID}}\t{{.Label "com.docker.compose.project"}}',
+        ]);
+        candidates = listing
+            .split(/\r?\n/)
+            .map((line) => line.split("\t"))
+            .filter(([id, project]) => id && project && belongsToProject(project, projectName))
+            .map(([id]) => id);
+    }
+    catch {
+        return {
+            name,
+            didPass: true,
+            isSkipped: true,
+            message: "Docker not available - skipped crash-loop check",
+        };
+    }
+    if (candidates.length === 0) {
+        return { name, didPass: true, isSkipped: true, message: "No project containers to check" };
+    }
+    let states;
+    try {
+        states = parseStates(await run([
+            "inspect",
+            "--format",
+            "{{.Name}}\t{{.RestartCount}}\t{{.State.Status}}\t{{.State.StartedAt}}\t{{.State.ExitCode}}\t{{.State.FinishedAt}}",
+            ...candidates,
+        ]));
+    }
+    catch {
+        // A container removed between ps and inspect fails the whole batch; that is not a finding.
+        return {
+            name,
+            didPass: true,
+            isSkipped: true,
+            message: "Containers changed while checking - skipped crash-loop check",
+        };
+    }
+    const looping = states.filter((state) => isCrashLooping(state, now));
+    if (looping.length === 0) {
+        return { name, didPass: true, message: "No project container is crash-looping" };
+    }
+    const details = [];
+    const hints = new Set();
+    for (const state of looping) {
+        let logs = "";
+        try {
+            logs = await run(["logs", "--tail", String(LOG_LINES), state.name]);
+        }
+        catch {
+            // The container may have just been removed; report it without logs.
+        }
+        const lines = redactSecrets(logs, secrets)
+            .split(/\r?\n/)
+            .map((line) => line.trim().slice(0, LOG_LINE_MAX))
+            .filter(Boolean);
+        const hint = crashLoopHint(logs, state);
+        if (hint)
+            hints.add(hint);
+        details.push([
+            `${state.name}: ${state.status}, restarted ${state.restartCount} times`,
+            ...lines.map((line) => `  | ${line}`),
+        ].join("\n    "));
+    }
+    return {
+        name,
+        didPass: false,
+        message: `${looping.length} container${looping.length === 1 ? " is" : "s are"} crash-looping:\n    ${details.join("\n    ")}`,
+        fix: [...hints, "Read the full log: docker logs <container>"].join("; "),
+    };
+}

package/cli/dist/utils/doctor-fix.js

@@ -0,0 +1,211 @@
+// Copyright (c) 2026 TDK Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { promisify } from "node:util";
+import { projectNetworkNames } from "./down-cleanup.js";
+import { findAllOnPath } from "./which.js";
+const execFilePromise = promisify(execFile);
+const DOCKER_TIMEOUT_MS = 15_000;
+/** The networks `tdk doctor` creates to test capacity; an interrupted run leaves one behind. */
+const PROBE_NETWORK = /^tdk_doctor_probe_(\d+)$/;
+const runDocker = async (args) => {
+    const { stdout } = await execFilePromise("docker", args, {
+        encoding: "utf-8",
+        timeout: DOCKER_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    return stdout;
+};
+function firstLine(error) {
+    const stderr = String(error.stderr ?? error).trim();
+    return stderr.split(/\r?\n/)[0] ?? "";
+}
+export function createDockerFixDeps(run = runDocker) {
+    return {
+        async listNetworks() {
+            const names = (await run(["network", "ls", "--format", "{{.Name}}"]))
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean);
+            // One inspect per network: another process (a doctor probe, `tdk down`) can remove one mid-listing, and a
+            // batched inspect would then fail for all of them.
+            const inspected = await Promise.all(names.map(async (name) => {
+                try {
+                    const count = await run([
+                        "network",
+                        "inspect",
+                        "--format",
+                        "{{len .Containers}}",
+                        name,
+                    ]);
+                    return { name, containers: Number(count.trim()) || 0 };
+                }
+                catch (error) {
+                    if (/no such network|not found/i.test(String(error)))
+                        return null;
+                    throw error;
+                }
+            }));
+            return inspected.filter((network) => network !== null);
+        },
+        async removeNetwork(name) {
+            try {
+                await run(["network", "rm", name]);
+            }
+            catch (error) {
+                throw new Error(firstLine(error));
+            }
+        },
+        isProcessAlive(pid) {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                // EPERM means the process exists but belongs to someone else.
+                return error.code === "EPERM";
+            }
+        },
+    };
+}
+export const dockerFixDeps = createDockerFixDeps();
+/**
+ * What `--fix` would do. Only unused networks that are either a leftover doctor probe or one of this project's own
+ * (the exact names the engine creates, and only while `projectBusy` is unset) are planned; another project's networks are never listed here.
+ */
+export async function planDoctorFixes(projectName, deps = dockerFixDeps, projectBusy) {
+    const networks = await deps.listNetworks();
+    const actions = [];
+    const own = new Set(projectName ? projectNetworkNames(projectName) : []);
+    for (const network of networks) {
+        const probe = PROBE_NETWORK.exec(network.name);
+        let scope;
+        let check;
+        if (probe) {
+            scope = "probe";
+            check = "Orphaned probe networks";
+        }
+        else if (own.has(network.name)) {
+            scope = "project";
+            check = "Docker networks";
+        }
+        else {
+            continue;
+        }
+        const action = {
+            id: `remove-network:${network.name}`,
+            check,
+            scope,
+            command: `docker network rm ${network.name}`,
+            status: "planned",
+            reason: "unused network",
+        };
+        if (network.containers > 0) {
+            action.status = "skipped";
+            action.reason = `${network.containers} container(s) still attached`;
+        }
+        else if (scope === "project" && projectBusy) {
+            // A starting stack creates its networks before any container joins them, so "unused" is not safe to remove.
+            action.status = "skipped";
+            action.reason = projectBusy;
+        }
+        else if (probe && deps.isProcessAlive(Number(probe[1]))) {
+            // The doctor run that created it may still be using it.
+            action.status = "skipped";
+            action.reason = `probe of a running process (pid ${probe[1]})`;
+        }
+        actions.push(action);
+    }
+    return actions;
+}
+/** Run the planned actions in order. A declined or failed action never stops the rest, so a re-run converges. */
+export async function applyDoctorFixes(actions, options, deps = dockerFixDeps) {
+    const results = [];
+    for (const action of actions) {
+        if (action.status !== "planned" || options.dryRun) {
+            results.push(action);
+            continue;
+        }
+        if (!options.confirm) {
+            results.push({
+                ...action,
+                status: "skipped",
+                reason: "confirmation required; run in a terminal or pass --yes",
+            });
+            continue;
+        }
+        let confirmed = false;
+        try {
+            confirmed = await options.confirm(action);
+        }
+        catch {
+            // No terminal to ask on.
+        }
+        if (!confirmed) {
+            results.push({ ...action, status: "skipped", reason: "not confirmed" });
+            continue;
+        }
+        const name = action.id.slice("remove-network:".length);
+        try {
+            await deps.removeNetwork(name);
+            results.push({ ...action, status: "applied", reason: "removed" });
+        }
+        catch (error) {
+            results.push({ ...action, status: "failed", reason: firstLine(error) });
+        }
+    }
+    return results;
+}
+/** Whether any action leaves a problem behind that a re-run could still repair. */
+export function hasFailedActions(actions) {
+    return actions.some((action) => action.status === "failed");
+}
+async function readTdkVersion(path) {
+    try {
+        const { stdout } = await execFilePromise(path, ["--version"], {
+            encoding: "utf-8",
+            timeout: 5000,
+            windowsHide: true,
+        });
+        return stdout.trim().split(/\r?\n/)[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every distinct `tdk` on PATH (symlinks to one binary count once), in PATH order. */
+export async function findTdkInstalls(paths = findAllOnPath("tdk"), readVersion = readTdkVersion) {
+    const seen = new Set();
+    const installs = [];
+    for (const path of paths) {
+        let real = path;
+        try {
+            real = realpathSync(path);
+        }
+        catch {
+            // Keep the PATH entry as is.
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        installs.push({ path, version: await readVersion(path) });
+    }
+    return installs;
+}
+/** Two `tdk` binaries can disagree (a dashboard or MCP client may launch the older one), so say which is which. */
+export async function checkDuplicateTdkInstalls(installs) {
+    const found = installs ?? (await findTdkInstalls());
+    if (found.length <= 1) {
+        return { name: "TDK installs", didPass: true, message: "One tdk install on PATH" };
+    }
+    const list = found.map((i) => `${i.path} (${i.version ?? "version unknown"})`).join(", ");
+    const versions = new Set(found.map((i) => i.version));
+    return {
+        name: "TDK installs",
+        didPass: false,
+        isWarning: true,
+        message: `${found.length} tdk installs on PATH${versions.size > 1 ? " with different versions" : ""}: ${list}`,
+        fix: "Keep one: remove the others, or run tdk upgrade. The first on PATH is the one your shell runs; tools that launch /usr/local/bin/tdk directly may use another",
+    };
+}