@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/src/commands/dev.js

@@ -1,8 +1,9 @@
 /**
  * mesh dev — Pulumi-output-driven local development orchestrator
  *
- * Reads `pulumi stack output dev --json` to discover services and tunnels,
+ * Reads `pulumi stack output dev --json` to discover services and VPC endpoints,
  * then launches each service's dev command in a tmux window.
+ * Requires VPN connection for direct access to VPC resources.
  *
  * Usage:
  *   mesh dev                  Start all services, attach tmux
@@ -12,15 +13,82 @@
  *   mesh dev logs <service>   Tail a service's output
  *   mesh dev restart <svc>    Restart a single service
  */
-import { execFileSync, spawnSync } from "child_process";
-import * as fs from "fs";
-import * as net from "net";
-import * as os from "os";
-import * as path from "path";
-import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
-import { logInfo, logSuccess, logError, logWarn } from "../utils/index.js";
+import { execFileSync, spawn, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as net from 'net';
+import * as os from 'os';
+import * as path from 'path';
+import { Option } from 'commander';
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
+import { logInfo, logSuccess, logError, logWarn, isVpnConnected, getTailscaleInfo, headscaleDnsConfig, registerDnsRecords, unregisterDnsRecords, readDnsRecords, getPlatformBastionInfo, } from '../utils/index.js';
+import { derivePlatformContext, renderCredentialProcessProfile, resolveAwsCredentials, resolveStableMeshBin, selectRoleForCaller, } from '../utils/aws-auth.js';
+import { readCredentials, getContextConfig, probeCredentials, getValidToken } from './login.js';
+import { resolveVpnJoinBroker, mintPreAuthKey } from '../utils/vpn-join.js';
+import { credProbeToPreflightError } from '../utils/pulumi-run.js';
+import { startTailscaleTunnels, tailscaleAvailable, daemonState as tailscaleDaemonState, readTunnelState as readTailscaleState, readDaemonMeta as readTailscaleDaemonMeta, } from '../utils/tailscale.js';
+import { pulumiStackOutput, readStackConfig } from '../utils/pulumi.js';
+import { ensureKubeconfig, resolveHubPlatformName, sessionKubeconfigPath, } from '../utils/kubeconfig.js';
+import { resolveTemporalAuth } from '../utils/temporal-auth.js';
+import { probeTcpReachable, probeConnectionHolds } from '../utils/reachability.js';
+import { fingerprintWorkflowSource } from '../utils/workflow-fingerprint.js';
+import { buildLaunchCommand, envFileName, waitForPort, writeEnvFile } from './dev-launch.js';
+import { buildLocalDevOutput, detectLocalTenant, ensureLocalPlatformRunning, hasStackBacking, localAppNamespace } from './local/dev-local.js';
+import { ensureAppTenantAuth, registerLocalApp } from './local/auth-provision.js';
+import { localAwsEnv, ensureTemporalNamespace } from './local/seed.js';
+import { composeExternalUp, composeExternalsDown, externalMode, localProbesRemove, parseExternalsSelection, readLocalMocks, seedLocalMock, } from './local/mocks.js';
+import { logShipperPath } from './local/dev-local.js';
+import { writeDevCompose, dockerDevUp, dockerDevDown, dockerDevPs, dockerDevLogs, dockerDevRestart } from './local/docker-runner.js';
+import { MeshCliError } from '../utils/errors.js';
+import { resolveStackOption } from '../utils/stack-flag.js';
+import { rewriteClusterHostsToLocal } from './peer-addressing.js';
+import { ALL_CHECKS, aggregateStatus, renderHuman, runChecks, runDoctor, } from './dev-doctor.js';
+import { resolveWorktreeIdentity, withAppScopedPortBlock, blockBasePort, PORT_BLOCK_SERVICE_SUBRANGE, } from '../utils/worktree-identity.js';
+/**
+ * tmux session name for a dev launch. The primary checkout keeps the historical
+ * `${projectName}-dev`; linked worktrees get a `${projectName}-${slug}` so two
+ * worktrees of the same app don't share (and kill) each other's session, state,
+ * and env-file dir (MESH-2013).
+ */
+function deriveSessionName(projectName, wt) {
+    return wt.isPrimary ? `${projectName}-dev` : `${projectName}-${wt.slug}`;
+}
+/**
+ * Render the resolved per-worktree plan (`mesh dev --dry-run`): identity,
+ * session/state/env paths, and the port assignment — everything that must be
+ * collision-free across concurrent worktrees, without launching anything.
+ */
+function printDevPlan(sessionName, appRoot, wt, devOutput) {
+    const kind = wt.isPrimary ? 'primary checkout' : `linked worktree (block ${wt.portBlock})`;
+    console.log(`\nmesh dev plan — ${kind}\n`);
+    console.log(`  worktree root : ${wt.worktreeRoot}`);
+    console.log(`  app root      : ${appRoot}`);
+    console.log(`  token         : ${wt.token || '(none — primary)'}`);
+    console.log(`  tmux session  : ${sessionName}`);
+    console.log(`  session state : ${getSessionStatePath(sessionName)}`);
+    console.log(`  env dir       : ${getSessionEnvDir(sessionName)}`);
+    const tq = wt.taskQueueSuffix
+        ? `<app-task-queue>${wt.taskQueueSuffix}`
+        : '<app-task-queue> (primary — unchanged)';
+    console.log(`  task queue    : ${tq}`);
+    console.log(`\n  services (port · resolved source dir):`);
+    const locals = Object.entries(devOutput.services).filter(([, s]) => (s.port ?? 0) >= 0 && s.command && s.command.length > 0);
+    if (locals.length === 0) {
+        console.log(`    (none — all services are deployed/K8s)`);
+    }
+    else {
+        const monorepoRoot = findMonorepoRoot();
+        const wtWithSep = wt.worktreeRoot.endsWith(path.sep) ? wt.worktreeRoot : wt.worktreeRoot + path.sep;
+        for (const [name, s] of locals) {
+            const dir = path.resolve(appRoot, rebaseServiceSrc(s.src, monorepoRoot));
+            const outside = dir !== wt.worktreeRoot && !dir.startsWith(wtWithSep);
+            const port = s.port > 0 ? `:${s.port}` : '(no port)';
+            console.log(`    ${name.padEnd(18)} ${port.padEnd(7)} ${dir}${outside ? '  ⚠ OUTSIDE worktree' : ''}`);
+        }
+    }
+    console.log('');
+}
 function getSessionStatePath(sessionName) {
-    const dir = path.join(os.tmpdir(), "mesh-dev-sessions");
+    const dir = path.join(os.tmpdir(), 'mesh-dev-sessions');
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
     return path.join(dir, `${sessionName}.json`);
@@ -33,44 +101,101 @@ function loadSessionState(sessionName) {
     if (!fs.existsSync(filePath))
         return null;
     try {
-        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
     }
     catch {
         return null;
     }
 }
+/**
+ * Relaunch safety (MESH-2017): if the workflow source changed since this session
+ * launched, restarting the worker replays any in-flight conversations against the
+ * NEW code — a replay-incompatible change strands them. Warn and require `--force`.
+ *
+ * Silent no-op when there's no prior session, no stored fingerprint (pre-feature
+ * session), or nothing changed — so a restart of unchanged code never nags.
+ * Returns `true` if the caller should ABORT (changed && !force).
+ */
+/** Pure: did the workflow source change since launch (→ risk of stranding)? */
+export function workflowChanged(prior, current) {
+    return Boolean(prior) && Boolean(current) && current !== prior;
+}
+function workflowChangeWouldStrand(priorState, appRoot, force) {
+    const prior = priorState?.workflowFingerprint;
+    if (!prior)
+        return false;
+    const current = fingerprintWorkflowSource(appRoot, priorState?.devOutput?.services);
+    if (!workflowChanged(prior, current))
+        return false;
+    logWarn('Workflow code changed since this session started.\n' +
+        '  Restarting the worker replays any in-flight conversations against the NEW code —\n' +
+        '  a replay-incompatible change strands them (they get stuck and become unviewable).\n' +
+        '  Keep it replay-compatible: gate the change with wf.patched() and regenerate the replay\n' +
+        '  goldens (see the temporal-workflow-safety skill), or accept the risk.');
+    if (force) {
+        logWarn('  Proceeding anyway (--force).');
+        return false;
+    }
+    logError('  Refusing to restart the worker. Re-run with --force once the change is replay-safe.');
+    return true;
+}
+/**
+ * Per-session directory holding one sourceable env file per service
+ * (`<service>.env.sh`, mode 0600). Written at launch; `mesh dev restart`
+ * sources the same file so a restarted service gets a byte-identical env.
+ */
+function getSessionEnvDir(sessionName) {
+    return path.join(os.tmpdir(), 'mesh-dev-sessions', sessionName);
+}
+function getServiceEnvFilePath(sessionName, serviceName) {
+    return path.join(getSessionEnvDir(sessionName), envFileName(serviceName));
+}
 function removeSessionState(sessionName) {
     try {
         fs.unlinkSync(getSessionStatePath(sessionName));
     }
     catch { }
+    try {
+        fs.rmSync(getSessionEnvDir(sessionName), { recursive: true, force: true });
+    }
+    catch { }
 }
 /**
- * Check whether a TCP port is available on localhost.
+ * Check whether a TCP port is available — probing the way services actually bind.
+ *
+ * This used to bind `127.0.0.1` only, and that made it blind to exactly the
+ * processes it exists to find. Node's `listen(port)` (and `@hono/node-server`,
+ * which every agent-api uses) binds the WILDCARD address `::` in dual-stack mode,
+ * holding the port on every interface — yet a probe bound to `127.0.0.1` still
+ * succeeds against such a holder. So the check returned `true` for a port already
+ * held by a prior `mesh dev` service, `allocatePorts` kept the preferred port, and
+ * the service then died on `EADDRINUSE` at its real bind.
+ *
+ * Observed 2026-07-31: the `studio-api` pane died on `EADDRINUSE :::40161` while a
+ * stale agent-api from an earlier boot kept serving on the same port, so the Studio
+ * UI drove a process from a previous session's configuration and the conversation
+ * list came back empty. Reproduced in isolation — holder on `::`, loopback probe
+ * reports free, real bind fails (MESH-2590).
+ *
+ * Both addresses are probed: the wildcard catches all-interface holders, and the
+ * loopback probe still catches a loopback-only squatter. A false "busy" is cheap —
+ * `allocatePorts` simply picks another port — while a false "free" crashes the
+ * service, so this deliberately errs toward busy.
  */
-async function isPortFree(port) {
-    return new Promise((resolve) => {
+export async function isPortFree(port) {
+    const bindSucceeds = (host) => new Promise((resolve) => {
         const server = net.createServer();
-        server.once("error", () => resolve(false));
-        server.listen(port, "127.0.0.1", () => {
-            server.close(() => resolve(true));
-        });
+        server.once('error', () => resolve(false));
+        const onListening = () => server.close(() => resolve(true));
+        if (host === undefined)
+            server.listen(port, onListening);
+        else
+            server.listen(port, host, onListening);
     });
-}
-/**
- * Check if a port is being listened on (synchronous, for status display).
- */
-function isPortListeningSync(port) {
-    try {
-        execFileSync("bash", ["-c", `echo >/dev/tcp/127.0.0.1/${port}`], {
-            timeout: 500,
-            stdio: "ignore",
-        });
-        return true;
-    }
-    catch {
+    // Wildcard first: it is how the services bind, so it is the probe that matters.
+    if (!(await bindSucceeds()))
         return false;
-    }
+    return bindSucceeds('127.0.0.1');
 }
 /**
  * Ask the OS for an ephemeral free port.
@@ -78,79 +203,203 @@ function isPortListeningSync(port) {
 async function findFreePort() {
     return new Promise((resolve, reject) => {
         const server = net.createServer();
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
             const { port } = server.address();
             server.close(() => resolve(port));
         });
     });
 }
+/** Resolve true if something is accepting connections on 127.0.0.1:port. */
+function isPortListening(port) {
+    return new Promise((resolve) => {
+        const s = new net.Socket();
+        let done = false;
+        const fin = (ok) => {
+            if (done)
+                return;
+            done = true;
+            s.destroy();
+            resolve(ok);
+        };
+        s.setTimeout(300);
+        s.once('connect', () => fin(true));
+        s.once('timeout', () => fin(false));
+        s.once('error', () => fin(false));
+        s.connect(port, '127.0.0.1');
+    });
+}
 /**
- * Clone devOutput and replace any colliding ports with dynamically
- * allocated free ports.  Preferred ports are kept when available.
+ * Rewrite a service's OWN listen-port env var(s) from `oldPort` to `newPort`
+ * when `allocatePorts` reassigns its port (e.g. a worktree block). Matches any
+ * port-ish var (`PORT` or `*_PORT`, e.g. `VCS_PORT`/`AGENT_API_PORT`) whose value
+ * is exactly the old port — so a service that reads its own env var still binds
+ * the reassigned port instead of its deploy-time default (which would collide
+ * with another worktree/session on that default). The name + exact-value match
+ * keeps this from touching cross-service references or unrelated vars.
+ * Mutates `service.env`. Pure otherwise — exported for unit testing. (MESH-2088)
  */
-async function allocatePorts(devOutput) {
-    const allocated = JSON.parse(JSON.stringify(devOutput));
-    const usedPorts = new Set();
-    // Tunnels first (services may depend on them)
-    for (const [name, tunnel] of Object.entries(allocated.tunnels)) {
-        const preferred = tunnel.localPort;
-        if (preferred > 0 &&
-            !usedPorts.has(preferred) &&
-            (await isPortFree(preferred))) {
-            usedPorts.add(preferred);
-        }
-        else {
-            const newPort = await findFreePort();
-            if (preferred > 0)
-                logWarn(`Port ${preferred} busy for tunnel '${name}', using ${newPort}`);
-            tunnel.localPort = newPort;
-            usedPorts.add(newPort);
+export function rewriteOwnServicePort(service, oldPort, newPort) {
+    for (const [key, spec] of Object.entries(service.env ?? {})) {
+        if ((key === 'PORT' || key.endsWith('_PORT')) && spec.value === String(oldPort)) {
+            spec.value = String(newPort);
         }
     }
-    // Service ports — track remappings for cross-service URL rewriting
+}
+/**
+ * Clone devOutput and assign each service a local port.
+ *
+ * The PRIMARY checkout keeps the app's preferred ports (falling back to an
+ * OS-ephemeral port only if one is busy). LINKED worktrees draw from a reserved
+ * port block keyed on (worktree, app) — MESH-2013 for the worktree axis, #2889
+ * for the app axis — so concurrent sessions don't collide, where the
+ * `EADDRINUSE on 8080/8081/9000` class only happened because every worktree
+ * reused the same preferred ports.
+ *
+ * Disjoint by DEFAULT, not by construction: the block is a hash bucket, so two
+ * (worktree, app) pairs can share one. The in-block scan below plus the
+ * ephemeral fallback are the backstop; MESH-2375 tracks making it deterministic.
+ */
+async function allocatePorts(devOutput, worktree) {
+    const allocated = JSON.parse(JSON.stringify(devOutput));
+    const usedPorts = new Set();
     const portRemaps = new Map();
+    const blockBase = worktree.isPrimary ? 0 : blockBasePort(worktree.portBlock);
+    let blockCursor = 0; // next unused index within the service sub-range
     for (const [name, service] of Object.entries(allocated.services)) {
         if (service.port <= 0)
             continue;
-        // Skip port allocation for deployed services (no dev command).
-        // They run in K8s and are accessed via tunnels, not local ports.
+        // Skip deployed services (no dev command) — they run in K8s, no local port.
         if (!service.command || service.command.length === 0)
             continue;
         const preferred = service.port;
-        if (!usedPorts.has(preferred) &&
-            (await isPortFree(preferred))) {
-            usedPorts.add(preferred);
+        let target = -1;
+        if (worktree.isPrimary) {
+            if (!usedPorts.has(preferred) && (await isPortFree(preferred))) {
+                target = preferred;
+            }
+            else {
+                target = await findFreePort();
+                logWarn(`Port ${preferred} busy for service '${name}', using ${target}`);
+            }
         }
         else {
-            const newPort = await findFreePort();
-            logWarn(`Port ${preferred} busy for service '${name}', using ${newPort}`);
-            // Update PORT env var to match
-            if (service.env?.PORT && service.env.PORT.value === String(preferred)) {
-                service.env.PORT.value = String(newPort);
+            // Reserved block: next free port in [blockBase, blockBase+SERVICE_SUBRANGE).
+            for (let i = blockCursor; i < PORT_BLOCK_SERVICE_SUBRANGE; i++) {
+                const candidate = blockBase + i;
+                if (!usedPorts.has(candidate) && (await isPortFree(candidate))) {
+                    target = candidate;
+                    blockCursor = i + 1;
+                    break;
+                }
             }
-            portRemaps.set(preferred, newPort);
-            service.port = newPort;
-            usedPorts.add(newPort);
+            if (target < 0) {
+                // Block exhausted or contended — degrade to an OS-ephemeral port.
+                target = await findFreePort();
+                logWarn(`Worktree port block exhausted for '${name}', using ${target}`);
+            }
+        }
+        if (target !== preferred) {
+            // Rewrite the service's OWN port env var(s) — not just a var literally
+            // named `PORT`. Without this, a service reading `VCS_PORT`/`AGENT_API_PORT`
+            // keeps its deploy-time default and collides across worktrees (MESH-2088).
+            rewriteOwnServicePort(service, preferred, target);
+            portRemaps.set(preferred, target);
+            service.port = target;
         }
+        usedPorts.add(target);
     }
     // Cross-service URL rewriting: when a service port is reassigned,
     // update any env var in other services that references the old port
     // (e.g., API_URL from a link() pointing to the API's original port).
-    if (portRemaps.size > 0) {
-        for (const service of Object.values(allocated.services)) {
-            if (!service.env)
-                continue;
-            for (const envVar of Object.values(service.env)) {
-                for (const [oldPort, newPort] of portRemaps) {
-                    if (envVar.value.includes(`localhost:${oldPort}`)) {
-                        envVar.value = envVar.value.replace(`localhost:${oldPort}`, `localhost:${newPort}`);
-                    }
+    rewriteCrossServicePorts(allocated, portRemaps);
+    rewriteClusterHostsToLocal(allocated);
+    return allocated;
+}
+/**
+ * Rewrite `localhost:${oldPort}` → `localhost:${newPort}` in EVERY service's env
+ * values, for each `oldPort → newPort` entry in `portRemaps`. Mutates the given
+ * `devOutput` in place — callers pass a clone they own, so this stays safe.
+ *
+ * Shared by `allocatePorts` (launch-time reallocation) and `mergePinnedPorts`
+ * (refresh-time re-pinning) so both apply identical cross-service rewrites.
+ */
+function rewriteCrossServicePorts(devOutput, portRemaps) {
+    if (portRemaps.size === 0)
+        return;
+    for (const service of Object.values(devOutput.services)) {
+        if (!service.env)
+            continue;
+        for (const envVar of Object.values(service.env)) {
+            for (const [oldPort, newPort] of portRemaps) {
+                if (envVar.value.includes(`localhost:${oldPort}`)) {
+                    envVar.value = envVar.value.replace(`localhost:${oldPort}`, `localhost:${newPort}`);
                 }
             }
         }
     }
-    return allocated;
+}
+/**
+ * Merge a session's PINNED ports/tunnels into a freshly-read DevOutput.
+ *
+ * `mesh dev restart <svc> --refresh-env` re-reads `pulumi stack output` to pick
+ * up config/deploy changes, but the running session already allocated local
+ * ports (`allocatePorts`) and opened SSM tunnels. Re-reading the raw stack
+ * output would carry the DEPLOYED (pre-allocation) ports, so writing those into
+ * the env file would point the service — and its peers — at the wrong ports and
+ * break the live tunnels.
+ *
+ * This returns `fresh` (so new/changed non-port env values win) but overrides:
+ *   - EVERY service present in both `fresh` and `pinned` keeps its pinned/
+ *     allocated PORT (both `service.port` and `service.env.PORT.value`) — not
+ *     just the refreshed one, so a regenerated service's peer references land on
+ *     the session-allocated ports, and
+ *   - every tunnel present in `pinned` with the pinned host:port (the live SSM
+ *     endpoints); tunnels that exist only in `fresh` survive untouched.
+ *
+ * It then re-applies BOTH of the peer-addressing rewrites `allocatePorts` does —
+ * there are two now, and naming only one here is how they drift apart:
+ *   - PORT: for each service whose port differs between `fresh` (preferred) and
+ *     `pinned` (allocated), `localhost:${freshPort}` → `localhost:${pinnedPort}`
+ *     across EVERY service's env (e.g. a `ui`'s `API_URL` pointing at `api`).
+ *   - HOST: an in-cluster address for a service running LOCALLY becomes its local
+ *     one. `pulumi stack output` carries cluster hosts verbatim, so a refresh
+ *     without this restores exactly the value MESH-2597 exists to remove.
+ *
+ * Pure: deep-clones and never mutates its arguments.
+ */
+export function mergePinnedPorts(fresh, pinned) {
+    const merged = JSON.parse(JSON.stringify(fresh));
+    // Pinned tunnels win (live SSM/VPC endpoints); fresh-only tunnels survive.
+    const pinnedTunnels = JSON.parse(JSON.stringify(pinned.tunnels ?? {}));
+    merged.tunnels = { ...(merged.tunnels ?? {}), ...pinnedTunnels };
+    // Pin EVERY service's allocated port (never re-allocate). Track fresh→pinned
+    // port remaps so peer references (localhost:<freshPort>) can be rewritten.
+    const portRemaps = new Map();
+    for (const [name, mergedSvc] of Object.entries(merged.services ?? {})) {
+        const pinnedSvc = pinned.services?.[name];
+        if (!pinnedSvc || typeof pinnedSvc.port !== 'number')
+            continue;
+        const freshPort = mergedSvc.port;
+        mergedSvc.port = pinnedSvc.port;
+        if (mergedSvc.env?.PORT) {
+            mergedSvc.env.PORT.value = String(pinnedSvc.port);
+        }
+        if (typeof freshPort === 'number' && freshPort > 0 && freshPort !== pinnedSvc.port) {
+            portRemaps.set(freshPort, pinnedSvc.port);
+        }
+    }
+    // Re-apply cross-service URL rewrite (mirrors allocatePorts): peer references
+    // to a preferred port become references to the session-allocated port.
+    rewriteCrossServicePorts(merged, portRemaps);
+    // BOTH rewrites, or `--refresh-env` undoes the other one. This path re-reads
+    // `pulumi stack output`, which carries in-cluster hosts verbatim, so without
+    // this a refresh restores `AGENT_API_INTERNAL_URL` to
+    // `http://studio-api.<ns>.svc.cluster.local:8080` for a service running locally
+    // — reintroducing MESH-2597 on the command whose entire purpose is refreshing
+    // env.
+    rewriteClusterHostsToLocal(merged);
+    return merged;
 }
 // ============================================================================
 // Pulumi helpers
@@ -164,12 +413,12 @@ function findMonorepoRoot() {
     const root = path.parse(dir).root;
     while (dir !== root) {
         // Look for pnpm-workspace.yaml (pnpm monorepo) or .git (repo root)
-        if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml")) ||
-            fs.existsSync(path.join(dir, "turbo.json"))) {
+        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) ||
+            fs.existsSync(path.join(dir, 'turbo.json'))) {
             return dir;
         }
         // .git as fallback — but only if it's a directory (not a worktree file)
-        const gitPath = path.join(dir, ".git");
+        const gitPath = path.join(dir, '.git');
         if (fs.existsSync(gitPath)) {
             return dir;
         }
@@ -190,10 +439,8 @@ function discoverApps(monorepoRoot) {
         const projectName = getProjectName(appDir);
         const stacks = fs
             .readdirSync(appDir)
-            .filter((f) => f.startsWith("Pulumi.") &&
-            f.endsWith(".yaml") &&
-            f !== "Pulumi.yaml")
-            .map((f) => f.replace(/^Pulumi\./, "").replace(/\.yaml$/, ""));
+            .filter((f) => f.startsWith('Pulumi.') && f.endsWith('.yaml') && f !== 'Pulumi.yaml')
+            .map((f) => f.replace(/^Pulumi\./, '').replace(/\.yaml$/, ''));
         apps.push({
             name: projectName,
             tenant,
@@ -203,42 +450,40 @@ function discoverApps(monorepoRoot) {
         });
     }
     // 1. Tenant-scoped: {tenants,tests/tenants}/<tenant>/apps/<app>/
-    const searchDirs = ["tenants", "tests/tenants"];
+    const searchDirs = ['tenants', 'tests/tenants'];
     for (const searchDir of searchDirs) {
         const base = path.join(monorepoRoot, searchDir);
         if (!fs.existsSync(base))
             continue;
         for (const tenant of fs.readdirSync(base)) {
-            const appsDir = path.join(base, tenant, "apps");
+            const appsDir = path.join(base, tenant, 'apps');
             if (!fs.existsSync(appsDir) || !fs.statSync(appsDir).isDirectory())
                 continue;
             for (const app of fs.readdirSync(appsDir)) {
                 const appDir = path.join(appsDir, app);
-                if (!fs.existsSync(path.join(appDir, "Pulumi.yaml")))
+                if (!fs.existsSync(path.join(appDir, 'Pulumi.yaml')))
                     continue;
                 addApp(appDir, tenant);
             }
         }
     }
     // 2. Flat layout: apps/<app>/ (tenant read from first stack config)
-    const flatAppsDir = path.join(monorepoRoot, "apps");
+    const flatAppsDir = path.join(monorepoRoot, 'apps');
     if (fs.existsSync(flatAppsDir) && fs.statSync(flatAppsDir).isDirectory()) {
         for (const app of fs.readdirSync(flatAppsDir)) {
             const appDir = path.join(flatAppsDir, app);
             if (!fs.statSync(appDir).isDirectory())
                 continue;
-            if (!fs.existsSync(path.join(appDir, "Pulumi.yaml")))
+            if (!fs.existsSync(path.join(appDir, 'Pulumi.yaml')))
                 continue;
             // Read tenant from first stack config's mesh:tenant
-            let tenant = "unknown";
+            let tenant = 'unknown';
             const stackConfigs = fs
                 .readdirSync(appDir)
-                .filter((f) => f.startsWith("Pulumi.") &&
-                f.endsWith(".yaml") &&
-                f !== "Pulumi.yaml");
+                .filter((f) => f.startsWith('Pulumi.') && f.endsWith('.yaml') && f !== 'Pulumi.yaml');
             if (stackConfigs.length > 0) {
                 try {
-                    const content = fs.readFileSync(path.join(appDir, stackConfigs[0]), "utf-8");
+                    const content = fs.readFileSync(path.join(appDir, stackConfigs[0]), 'utf-8');
                     const tenantMatch = content.match(/mesh:tenant:\s*(\S+)/);
                     if (tenantMatch)
                         tenant = tenantMatch[1];
@@ -257,13 +502,13 @@ function findAppRoot(appPath) {
     if (appPath) {
         // Resolve relative to cwd or monorepo root
         const resolved = path.resolve(appPath);
-        if (fs.existsSync(path.join(resolved, "Pulumi.yaml")))
+        if (fs.existsSync(path.join(resolved, 'Pulumi.yaml')))
             return resolved;
         // Try relative to monorepo root
         const mono = findMonorepoRoot();
         if (mono) {
             const fromMono = path.resolve(mono, appPath);
-            if (fs.existsSync(path.join(fromMono, "Pulumi.yaml")))
+            if (fs.existsSync(path.join(fromMono, 'Pulumi.yaml')))
                 return fromMono;
         }
         logError(`No Pulumi.yaml found at: ${appPath}`);
@@ -272,7 +517,7 @@ function findAppRoot(appPath) {
     let dir = process.cwd();
     const root = path.parse(dir).root;
     while (dir !== root) {
-        if (fs.existsSync(path.join(dir, "Pulumi.yaml"))) {
+        if (fs.existsSync(path.join(dir, 'Pulumi.yaml'))) {
             return dir;
         }
         dir = path.dirname(dir);
@@ -283,10 +528,10 @@ function findAppRoot(appPath) {
  * Read the Pulumi project name from Pulumi.yaml.
  */
 function getProjectName(appRoot) {
-    const yamlPath = path.join(appRoot, "Pulumi.yaml");
+    const yamlPath = path.join(appRoot, 'Pulumi.yaml');
     if (!fs.existsSync(yamlPath))
         return path.basename(appRoot);
-    const content = fs.readFileSync(yamlPath, "utf-8");
+    const content = fs.readFileSync(yamlPath, 'utf-8');
     const match = content.match(/^name:\s*(.+)$/m);
     return match?.[1]?.trim() ?? path.basename(appRoot);
 }
@@ -303,10 +548,10 @@ function detectStack(appRoot, stageArg) {
     if (process.env.MESH_STAGE)
         return process.env.MESH_STAGE;
     try {
-        const result = execFileSync("pulumi", ["stack", "--show-name"], {
+        const result = execFileSync('pulumi', ['stack', '--show-name'], {
             cwd: appRoot,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
         }).trim();
         if (result)
             return result;
@@ -316,7 +561,9 @@ function detectStack(appRoot, stageArg) {
     }
     // Infer from Pulumi.<stack>.yaml config files
     try {
-        const files = fs.readdirSync(appRoot).filter((f) => f.startsWith("Pulumi.") && f.endsWith(".yaml") && f !== "Pulumi.yaml");
+        const files = fs
+            .readdirSync(appRoot)
+            .filter((f) => f.startsWith('Pulumi.') && f.endsWith('.yaml') && f !== 'Pulumi.yaml');
         if (files.length === 1) {
             const match = files[0].match(/^Pulumi\.(.+)\.yaml$/);
             if (match?.[1]) {
@@ -328,20 +575,66 @@ function detectStack(appRoot, stageArg) {
     catch {
         // Fall through
     }
-    return "dev";
+    return 'dev';
+}
+/**
+ * Build the `--stack <name>` args for Pulumi commands.
+ * Newer Pulumi versions require fully-qualified names (organization/project/stack)
+ * with `--stack`. If the stack is already selected, we can omit the flag entirely.
+ */
+function stackArgs(appRoot, stack) {
+    // Check if the requested stack is already the selected one — if so, skip --stack
+    try {
+        const selected = execFileSync('pulumi', ['stack', '--show-name'], {
+            cwd: appRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (selected === stack)
+            return [];
+    }
+    catch {
+        // ignore
+    }
+    // Try selecting the stack first (works with short names), then omit --stack
+    try {
+        execFileSync('pulumi', ['stack', 'select', stack], {
+            cwd: appRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return [];
+    }
+    catch {
+        // Fall through — pass --stack and hope the name is fully qualified
+    }
+    return ['--stack', stack];
 }
 /**
  * Read the dev output from Pulumi stack.
  * Tries `app` output first (new env.register() format), falls back to `dev`.
  */
-function getDevOutput(appRoot, stack) {
+/**
+ * Thrown by `getDevOutput` when no readable Pulumi stack output exists (usually a
+ * fresh app that hasn't been `stack init` + `deploy`ed yet). Typed so each caller
+ * presents it in its OWN context: only the launch path can conclude "nothing to
+ * run" and print first-run guidance; the `--refresh-env`/restart handlers must
+ * keep the running session's env untouched (MESH-2097). Carries the underlying
+ * read error so an auth/network/JSON failure isn't misdiagnosed as "fresh app".
+ */
+class MissingStackOutputError extends Error {
+    stackName;
+    constructor(stackName, cause) {
+        super(`No Pulumi stack output for '${stackName}'`, { cause });
+        this.stackName = stackName;
+        this.name = 'MissingStackOutputError';
+    }
+}
+function getDevOutput(appRoot, stack, awsEnv) {
+    const sa = stackArgs(appRoot, stack);
     // Try new format: export const app = env.register() → { dev: { ... } }
     try {
-        const result = execFileSync("pulumi", ["stack", "output", "app", "--json", "--show-secrets", "--stack", stack], {
-            cwd: appRoot,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "pipe"],
-        });
+        const result = pulumiStackOutput(appRoot, 'app', sa, awsEnv);
         const appOutput = JSON.parse(result);
         if (appOutput.dev) {
             return appOutput.dev;
@@ -352,18 +645,16 @@ function getDevOutput(appRoot, stack) {
     }
     // Legacy format: export const dev = ...
     try {
-        const result = execFileSync("pulumi", ["stack", "output", "dev", "--json", "--show-secrets", "--stack", stack], {
-            cwd: appRoot,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "pipe"],
-        });
+        const result = pulumiStackOutput(appRoot, 'dev', sa, awsEnv);
         return JSON.parse(result);
     }
     catch (err) {
-        logError(`Failed to read Pulumi stack output for stack '${stack}'.`);
-        logInfo("Make sure you've deployed with: pulumi up");
-        logInfo("And that the stack exports 'app' or 'dev' output.");
-        throw err;
+        // No readable stack output. Throw a TYPED error so each caller decides how to
+        // present it (MESH-2097): the launch path prints first-run guidance + exits;
+        // the --refresh-env/restart handlers keep the running session untouched.
+        // (process.exit() here previously hijacked control flow past those fail-closed
+        // catches, and a bare `throw` escaped as an uncaught node stacktrace.)
+        throw new MissingStackOutputError(stack, err);
     }
 }
 // ============================================================================
@@ -371,7 +662,7 @@ function getDevOutput(appRoot, stack) {
 // ============================================================================
 function hasTmux() {
     try {
-        execFileSync("which", ["tmux"], { stdio: "ignore" });
+        execFileSync('which', ['tmux'], { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -380,7 +671,7 @@ function hasTmux() {
 }
 function sessionExists(name) {
     try {
-        execFileSync("tmux", ["has-session", "-t", name], { stdio: "ignore" });
+        execFileSync('tmux', ['has-session', '-t', name], { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -389,25 +680,38 @@ function sessionExists(name) {
 }
 function killSession(name) {
     try {
-        execFileSync("tmux", ["kill-session", "-t", name], { stdio: "ignore" });
+        execFileSync('tmux', ['kill-session', '-t', name], { stdio: 'ignore' });
         return true;
     }
     catch {
         return false;
     }
 }
+const AWS_STATIC_CREDENTIAL_ENV_KEYS = [
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AWS_WEB_IDENTITY_TOKEN_FILE',
+    'AWS_ROLE_ARN',
+];
+function applyAwsProfileOverride(profile) {
+    process.env.AWS_PROFILE = profile;
+    for (const key of AWS_STATIC_CREDENTIAL_ENV_KEYS) {
+        delete process.env[key];
+    }
+}
 /**
  * Collect AWS credentials from the current environment.
  */
 function getAwsEnvVars() {
     const result = {};
     const vars = [
-        "AWS_PROFILE",
-        "AWS_ACCESS_KEY_ID",
-        "AWS_SECRET_ACCESS_KEY",
-        "AWS_SESSION_TOKEN",
-        "AWS_REGION",
-        "AWS_DEFAULT_REGION",
+        'AWS_PROFILE',
+        'AWS_ACCESS_KEY_ID',
+        'AWS_SECRET_ACCESS_KEY',
+        'AWS_SESSION_TOKEN',
+        'AWS_REGION',
+        'AWS_DEFAULT_REGION',
     ];
     for (const name of vars) {
         const value = process.env[name];
@@ -417,7 +721,114 @@ function getAwsEnvVars() {
     return result;
 }
 /**
- * Resolve env vars for a service, rewriting tunnel references.
+ * Build the AWS env vars to hand to long-lived child services (ui, api,
+ * ai-assistant) and SSM tunnels.
+ *
+ * For the AWS SSO credential path, returns AWS_PROFILE + AWS_REGION only so
+ * the AWS SDK's default provider chain can auto-refresh credentials from the
+ * SSO cache (~8h session) as short-lived STS tokens expire. Without this,
+ * child processes inherit a frozen STS triple and start throwing
+ * ExpiredTokenException ~1h into a dev session.
+ *
+ * For the Zitadel web-identity path, when `opts` is supplied we write an AWS
+ * config file whose `credential_process` re-invokes `mesh login … --credential-process`,
+ * so the AWS SDK's default provider chain auto-refreshes the underlying STS
+ * triple (the `mesh login` process re-issues the Zitadel token as needed).
+ * This removes the ~1h forced `mesh dev` restart. When `opts` is absent we
+ * fall back to the frozen STS triple (used by CI/`environment` and any caller
+ * that doesn't thread the context/role through).
+ *
+ * For the remaining non-SSO paths (CI/CD env keys, or no deployer role),
+ * returns the explicit STS triple — there is no profile to refresh from. The
+ * user must restart `mesh dev` when those tokens expire.
+ */
+export function buildChildAwsEnv(awsEnv, method, profile, opts) {
+    const result = {};
+    if (awsEnv.AWS_REGION)
+        result.AWS_REGION = awsEnv.AWS_REGION;
+    if (awsEnv.AWS_DEFAULT_REGION)
+        result.AWS_DEFAULT_REGION = awsEnv.AWS_DEFAULT_REGION;
+    if (method === 'sso' && profile) {
+        result.AWS_PROFILE = profile;
+        return result;
+    }
+    // Zitadel path with a credential_process profile: hand children a profile
+    // that self-refreshes via `mesh login`, never a frozen triple.
+    if (method === 'zitadel' && opts) {
+        const sanitizedContext = opts.context.replace(/[^A-Za-z0-9_-]/g, '-');
+        const profileName = `mesh-dev-${sanitizedContext}`;
+        const configPath = path.join(opts.sessionScratchDir, 'aws-config');
+        const region = awsEnv.AWS_REGION ?? awsEnv.AWS_DEFAULT_REGION ?? '';
+        fs.mkdirSync(opts.sessionScratchDir, { recursive: true });
+        fs.writeFileSync(configPath, renderCredentialProcessProfile({
+            profileName,
+            context: opts.context,
+            roleArn: opts.roleArn,
+            region,
+            meshBin: opts.meshBin,
+        }), { mode: 0o600 });
+        const out = {
+            AWS_PROFILE: profileName,
+            AWS_CONFIG_FILE: configPath,
+        };
+        if (region)
+            out.AWS_REGION = region;
+        return out;
+    }
+    for (const key of ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN']) {
+        if (awsEnv[key])
+            result[key] = awsEnv[key];
+    }
+    if (profile && !result.AWS_ACCESS_KEY_ID) {
+        result.AWS_PROFILE = profile;
+    }
+    return result;
+}
+/**
+ * Resolve a service's source dir onto the CURRENT worktree (MESH-2013).
+ *
+ * `mesh dev` reads the service `src` from `pulumi stack output`. Two shapes exist:
+ *   - New (post relative-src fix in infra-components): a monorepo-RELATIVE dir
+ *     like `packages/agent-sdk` → just resolve it against this worktree's root.
+ *   - Legacy: an ABSOLUTE path baked at the deploying `pulumi up`, e.g.
+ *     `/…/mesh-platform/.worktrees/streaming-ui-builder/packages/agent-sdk`. The
+ *     old logic stripped only up to `/mesh-platform/`, keeping the
+ *     `.worktrees/<name>/` segment — so it re-rooted to a *sibling worktree* that
+ *     also exists, silently running the wrong worktree's code. We now reduce to
+ *     the monorepo-relative portion (dropping any `.worktrees/<name>/`) and
+ *     re-root here, so a stack deployed from any worktree runs from THIS one.
+ */
+function rebaseServiceSrc(src, monorepoRoot) {
+    if (!monorepoRoot)
+        return src;
+    const rel = monorepoRelativeSrc(src);
+    if (rel === null)
+        return src;
+    const rebased = path.join(monorepoRoot, rel);
+    return fs.existsSync(rebased) ? rebased : src;
+}
+/**
+ * Reduce a service `src` to its monorepo-relative form (pure; no filesystem).
+ *   - relative (`./packages/x` or `packages/x`) → normalized `packages/x`
+ *   - legacy absolute (`/…/mesh-platform[/.worktrees/<name>]/packages/x`) →
+ *     `packages/x` (drops the repo root AND any deploying-worktree segment)
+ * Returns null when an absolute path has no recognizable monorepo marker.
+ */
+export function monorepoRelativeSrc(src) {
+    if (!path.isAbsolute(src))
+        return src.replace(/^\.\//, '') || '.';
+    // Match the LAST `/mesh-platform` at a segment boundary — covers the repo root
+    // itself (nothing follows → '.'), a nested `.worktrees/<name>/`, and normal
+    // subpaths. A path ending at the repo root (e.g. a service whose src IS the
+    // monorepo root) previously slipped through and stayed absolute (MESH-2069).
+    const m = src.match(/^.*\/mesh-platform(?:\/(.*))?$/);
+    if (!m)
+        return null;
+    const rest = (m[1] ?? '').replace(/^\.worktrees\/[^/]+(?:\/|$)/, '');
+    return rest === '' ? '.' : rest;
+}
+/**
+ * Resolve env vars for a service, rewriting tunnel references to VPC endpoints.
  */
 function getServiceEnvVars(service, tunnels) {
     const result = {};
@@ -427,22 +838,20 @@ function getServiceEnvVars(service, tunnels) {
             if (spec.tunnel) {
                 const tunnel = tunnels[spec.tunnel];
                 if (tunnel) {
+                    // Rewrite to VPC endpoint (VPN provides direct access)
                     try {
-                        // Try as a full URL first (e.g. postgres://host:5432/db)
                         const url = new URL(value);
                         if (url.hostname) {
-                            url.hostname = "localhost";
-                            url.port = String(tunnel.localPort);
+                            url.hostname = tunnel.host;
+                            url.port = String(tunnel.port);
                             value = url.toString();
                         }
                         else {
-                            // URL parsed but hostname empty (e.g. host:port parsed as protocol)
-                            value = `localhost:${tunnel.localPort}`;
+                            value = `${tunnel.host}:${tunnel.port}`;
                         }
                     }
                     catch {
-                        // Not a URL at all — bare host:port or just hostname
-                        value = `localhost:${tunnel.localPort}`;
+                        value = `${tunnel.host}:${tunnel.port}`;
                     }
                 }
             }
@@ -459,9 +868,7 @@ function getServiceEnvVars(service, tunnels) {
  */
 function setTmuxEnv(sessionName, vars) {
     for (const [key, value] of Object.entries(vars)) {
-        execFileSync("tmux", [
-            "set-environment", "-t", sessionName, key, value,
-        ], { stdio: "ignore" });
+        execFileSync('tmux', ['set-environment', '-t', sessionName, key, value], { stdio: 'ignore' });
     }
 }
 /**
@@ -474,9 +881,9 @@ function setTmuxEnv(sessionName, vars) {
 function envPrefix(vars) {
     const entries = Object.entries(vars);
     if (entries.length === 0)
-        return "";
+        return '';
     const parts = entries.map(([k, v]) => `${k}=${shellEscape(v)}`);
-    return `env ${parts.join(" ")} `;
+    return `env ${parts.join(' ')} `;
 }
 /** Escape a value for shell interpolation. */
 function shellEscape(s) {
@@ -491,9 +898,9 @@ function shellEscape(s) {
 // ============================================================================
 /**
  * Resolve secrets from Secrets Manager and return env var key→value pairs.
- * Applies tunnel rewrites to DATABASE_URL if a tunnel is active.
+ * VPN provides direct access — no URL rewriting needed.
  */
-async function resolveSecrets(secrets, tunnels) {
+async function resolveSecrets(secrets) {
     const client = new SecretsManagerClient({});
     const resolved = {};
     for (const [name, secret] of Object.entries(secrets)) {
@@ -503,25 +910,9 @@ async function resolveSecrets(secrets, tunnels) {
                 continue;
             const values = JSON.parse(response.SecretString);
             for (const [secretKey, envVar] of Object.entries(secret.envMapping)) {
-                const raw = values[secretKey];
-                if (raw === undefined)
+                const value = values[secretKey];
+                if (value === undefined)
                     continue;
-                let value = raw;
-                // Rewrite DATABASE_URL host:port if there's a tunnel
-                if (envVar === "DATABASE_URL" || secretKey === "DATABASE_URL") {
-                    for (const tunnel of Object.values(tunnels)) {
-                        try {
-                            const parsed = new URL(value);
-                            parsed.hostname = "localhost";
-                            parsed.port = String(tunnel.localPort);
-                            value = parsed.toString();
-                            break;
-                        }
-                        catch {
-                            // Not a URL
-                        }
-                    }
-                }
                 resolved[envVar] = value;
             }
             logSuccess(`Secret resolved: ${name} (${secret.secretName})`);
@@ -532,6 +923,491 @@ async function resolveSecrets(secrets, tunnels) {
     }
     return resolved;
 }
+/**
+ * Resolve the Temporal encoding key from the K8s secret in the app namespace.
+ *
+ * The Pulumi-generated devEncodingKey is a placeholder that differs from the
+ * deployed key, causing decryption failures when the local worker encounters
+ * existing Temporal payloads. Reading the real key from K8s ensures local dev
+ * can decrypt data created by deployed workers.
+ *
+ * Returns the encoding key value, or undefined if not available.
+ */
+function resolveTemporalEncodingKey(tenant, env, appName) {
+    const namespace = `${tenant}-${env}-${appName}`;
+    const secretName = `${namespace}-temporal-encoding-key`;
+    try {
+        const b64 = execFileSync('kubectl', [
+            'get',
+            'secret',
+            secretName,
+            '-n',
+            namespace,
+            '-o',
+            'jsonpath={.data.TEMPORAL_ENCODING_KEY}',
+        ], { encoding: 'utf-8', timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (b64) {
+            const key = Buffer.from(b64, 'base64').toString('utf-8');
+            logSuccess(`Temporal encoding key resolved from K8s secret (${secretName})`);
+            return key;
+        }
+    }
+    catch {
+        // Non-fatal — secret may not exist yet or kubectl may not have access
+    }
+    return undefined;
+}
+/**
+ * Re-resolve the session-level Temporal auth vars the SAME way launch does
+ * (see startServices): kubeconfig from SSM, M2M auth, encoding key from the
+ * K8s secret, and TEMPORAL_ADDRESS from the (pinned) tunnel. Used by
+ * `mesh dev restart --refresh-env` so a regenerated env file carries the live
+ * resolved values, not the dev-output placeholders (which would desync payload
+ * encryption between services).
+ */
+async function resolveTemporalAuthVars(sessionName, devOutput) {
+    const tenant = devOutput.platform?.tenant ?? 'mesh';
+    const platformEnv = devOutput.platform?.env ?? 'dev';
+    // Hub platform name — the EKS export lives under it, not under a hardcoded
+    // "mesh" (MESH-2515); same axis as the bastion resolution.
+    const platformName = resolveHubPlatformName(devOutput.platform);
+    const kubeconfigPath = await ensureKubeconfig(platformName, platformEnv, sessionName, {
+        onError: ({ parameter, error }) => logWarn(`EKS cluster resolve failed (${parameter}): ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`),
+    });
+    if (kubeconfigPath) {
+        process.env.KUBECONFIG = kubeconfigPath;
+        setTmuxEnv(sessionName, { KUBECONFIG: kubeconfigPath });
+    }
+    else if (!process.env.KUBECONFIG) {
+        // ensureKubeconfig couldn't re-resolve the cluster from SSM (transient /
+        // stale creds). Fall back to the session kubeconfig written at launch so the
+        // kubectl calls below don't default to ~/.kube/config — which macOS TCC
+        // denies for shells without Full Disk Access ("operation not permitted").
+        const existing = sessionKubeconfigPath(sessionName);
+        if (fs.existsSync(existing)) {
+            // Set only this process's env — deliberately NOT setTmuxEnv: this is a
+            // best-effort fallback to a possibly-stale last-good kubeconfig, so we use
+            // it for the kubectl calls below without persisting it into the session
+            // (a later successful re-resolve is the one that should win the session).
+            process.env.KUBECONFIG = existing;
+        }
+    }
+    let temporalAuthVars = {};
+    if (devOutput.tunnels['temporal']) {
+        // Deliberately NOT `platformName` from above: the Temporal-auth fallback is
+        // `?? tenant` (dedicated tenants may run their own Temporal), while the EKS
+        // fallback is `?? 'mesh'`. Whether that difference is correct is MESH-2551;
+        // don't "fix" either default to match the other without reading it.
+        temporalAuthVars = await resolveTemporalAuth(tenant, platformEnv, devOutput.platform?.name ?? tenant);
+        const appName = devOutput.app ?? '';
+        if (appName) {
+            const encodingKey = resolveTemporalEncodingKey(tenant, platformEnv, appName);
+            if (encodingKey) {
+                temporalAuthVars.TEMPORAL_ENCODING_KEY = encodingKey;
+            }
+        }
+        const temporalTunnel = devOutput.tunnels['temporal'];
+        temporalAuthVars.TEMPORAL_ADDRESS = tunnelClientAddress(temporalTunnel);
+    }
+    return temporalAuthVars;
+}
+/**
+ * Resolve the dev-user identity vars (DEV_USER_*) from cached `mesh login`
+ * credentials for the platform context (e.g. 'mesh.dev'). Credentials are
+ * stored under the platform context, not the tenant name — all tenants share
+ * the same Zitadel instance.
+ *
+ * Services (e.g., Hub UI) use these as a fallback when the real oauth2-proxy
+ * `X-Forwarded-*` request headers are absent:
+ *   DEV_USER_ID           - subject from idToken, matches conversation ownership
+ *   DEV_USER_EMAIL        - user email from idToken
+ *   DEV_USER_ID_TOKEN     - full idToken JWT (profile claims, authorization hint)
+ *   DEV_USER_ACCESS_TOKEN - full accessToken JWT (has project:roles claim)
+ *
+ * Returned vars must be overlaid onto each service's env FILE (not just the
+ * tmux session env): the dev output may carry a placeholder value (e.g. hub
+ * ui's DEV_USER_ACCESS_TOKEN="dev-local"), and the sourced per-service env
+ * file wins over the session env, so a session-env-only injection gets
+ * clobbered and every tenant-scoped Hub view silently 401s.
+ */
+function resolveDevUserVars(devOutput) {
+    const credContext = devOutput.platform
+        ? devOutput.platform.tenant === 'local'
+            ? 'local'
+            : `mesh.${devOutput.platform.env}`
+        : null;
+    if (!credContext)
+        return {};
+    const meshCreds = readCredentials(credContext);
+    if (!meshCreds?.idToken)
+        return {};
+    const vars = { DEV_USER_ID_TOKEN: meshCreds.idToken };
+    try {
+        const payload = JSON.parse(Buffer.from(meshCreds.idToken.split('.')[1], 'base64url').toString());
+        if (payload.sub)
+            vars.DEV_USER_ID = payload.sub;
+        if (payload.email)
+            vars.DEV_USER_EMAIL = payload.email;
+    }
+    catch {
+        /* ignore decode errors */
+    }
+    if (meshCreds.accessToken) {
+        vars.DEV_USER_ACCESS_TOKEN = meshCreds.accessToken;
+    }
+    return vars;
+}
+// ============================================================================
+// SSM tunnel fallback (when VPN is not connected)
+// ============================================================================
+/**
+ * Base port for SSM tunnels. Preferred ports use 20000 + original_port to
+ * avoid collisions with dev services (1000-9999 range). If the preferred
+ * port is already reserved or occupied, mesh dev walks upward until it finds
+ * an available port.
+ *
+ * Examples:
+ *   PostgreSQL  5432 → 25432
+ *   Temporal    7233 → 27233
+ *   Temporal UI 8080 → 28080
+ */
+const SSM_TUNNEL_BASE_PORT = 20000;
+/** How long to wait for an SSM tunnel's local port to accept TCP before failing. */
+const TUNNEL_READY_TIMEOUT_MS = 60_000;
+/**
+ * Build the client-facing `host:port` for an SSM tunnel.
+ *
+ * The `aws ssm start-session` port-forwarder binds IPv4 `127.0.0.1` only.
+ * Advertising `localhost` lets Node/grpc-js resolve to IPv6 `::1` first, which
+ * the tunnel isn't listening on — so e.g. the Temporal gRPC client fails with
+ * `ECONNREFUSED ::1:<port>` and the Hub's Automations/workflow lists never load.
+ * Maps the literal `localhost` (how tunnels are advertised today) to `127.0.0.1`
+ * so clients hit the bound listener. Any other host — VPN-direct VPC endpoints,
+ * or a different loopback literal like `::1`/`127.0.0.1` — passes through unchanged.
+ */
+export function tunnelClientAddress(tunnel) {
+    const host = tunnel.host === 'localhost' ? '127.0.0.1' : tunnel.host;
+    return `${host}:${tunnel.port}`;
+}
+/**
+ * Render the Connections section (live tunnel health) as status-window lines.
+ *
+ * The status window refreshes every ~2s, so this is where a mid-session tunnel
+ * death surfaces (MESH-2016): a dead tunnel shows `⚠ … DOWN` and a SINGLE
+ * remediation line explains the `ECONNREFUSED` retry spam the dependent service
+ * windows emit — instead of leaving the operator to decode that spam themselves.
+ * Returns `[]` when there are no tunnels (nothing to show).
+ */
+export function formatTunnelHealth(health) {
+    if (health.length === 0)
+        return [];
+    const lines = ['Connections:'];
+    for (const h of health) {
+        const icon = h.reachable ? '✓' : '⚠';
+        const suffix = h.reachable ? '' : '   DOWN';
+        lines.push(`  ${icon} ${h.name.padEnd(16)} ${h.address}${suffix}`);
+    }
+    const down = health.filter((h) => !h.reachable).map((h) => h.name);
+    if (down.length > 0) {
+        const noun = down.length === 1 ? 'tunnel' : 'tunnels';
+        lines.push('');
+        lines.push(`  ⚠ ${down.length} ${noun} down (${down.join(', ')}) — dependent services are ` +
+            `retrying (ECONNREFUSED spam is expected). Relaunch: mesh dev`);
+    }
+    return lines;
+}
+/** Probe every tunnel's client address in parallel and resolve its health. */
+async function probeTunnelHealth(tunnels) {
+    return Promise.all(Object.entries(tunnels).map(async ([name, tun]) => ({
+        name,
+        address: tunnelClientAddress(tun),
+        // Dial the SAME address the client uses (localhost→127.0.0.1) so the probe
+        // sees exactly what a dependent service would. Use the connection-HOLDS
+        // probe, not a bare accept: a forwarder binds its local port even when its
+        // upstream leg is dead (a dropped SSM session, or a Tailscale SOCKS bridge
+        // dialing a stale port — MESH-2169), so "port accepts" would report a dead
+        // tunnel as healthy. Holding briefly catches the accept-then-close teardown.
+        reachable: await probeConnectionHolds(tun.host === 'localhost' ? '127.0.0.1' : tun.host, tun.port, 800),
+    })));
+}
+/**
+ * Probe the routing-critical tunnel of a (Tailscale-rewritten) devOutput and
+ * return its name if the forwarder binds but does not ROUTE, else null.
+ *
+ * Only `temporal` is gated — it's the load-bearing VPC dependency (services die
+ * on a gRPC deadline when it's dead), and keying on it mirrors the vpn-direct
+ * reachability gate ({@link gateVpnDirectReachability}). A Tailscale forwarder
+ * accepts its local port even when its SOCKS upstream is dead or the joined
+ * tailnet doesn't route the VPC; such a forwarder tears the connection down
+ * within the grace window, so it fails the connection-HOLDS probe that a bare
+ * accept (the readiness gate's `waitForPort`) would pass (MESH-2169/MESH-2268).
+ */
+export async function firstUnroutableTunnel(tunnels) {
+    const temporal = tunnels['temporal'];
+    if (!temporal || temporal.host !== 'localhost')
+        return null;
+    const holds = await probeConnectionHolds('127.0.0.1', temporal.port, 800);
+    return holds ? null : 'temporal';
+}
+/**
+ * Resolve which tunnel backing `mesh dev` should use.
+ *
+ * An explicit `--transport` flag wins. Both `auto` and the default (unset)
+ * prefer Tailscale when it's available (brew `tailscaled` present), else fall
+ * back to the VPN-direct/SSM choice: VPN-direct when the VPN is connected, else
+ * SSM when the session-manager plugin is present. Where Tailscale isn't
+ * available the behavior is unchanged from before this feature.
+ */
+export function resolveTransport(flag, ctx) {
+    if (flag === "tailscale" || flag === "ssm")
+        return flag;
+    if (flag !== undefined && flag !== "auto") {
+        throw new Error(`Invalid --transport '${flag}'. Valid values: auto (default), tailscale, ssm.`);
+    }
+    const legacy = ctx.vpnConnected ? "vpn-direct" : ctx.hasSsmPlugin ? "ssm" : "vpn-direct";
+    return ctx.tailscaleAvailable ? "tailscale" : legacy;
+}
+/**
+ * Correct an auto-selected `vpn-direct` transport against ACTUAL reachability of
+ * the Temporal VPC endpoint (MESH-2016). `resolveTransport` uses a presence check
+ * (any Tailscale/VPN up) that's tailnet-blind — Tailscale-for-SSH looks connected
+ * but doesn't route the mesh VPC. Only `vpn-direct` is reachability-gated (it's
+ * never an explicit choice); every other transport passes through unchanged.
+ *
+ * Pure so the fallback logic is testable independently of the TCP probe.
+ */
+export function reachabilityFallbackTransport(transport, temporalReachable, hasSsmPlugin) {
+    if (transport !== "vpn-direct")
+        return { transport, reason: "not-vpn-direct" };
+    if (temporalReachable)
+        return { transport, reason: "reachable" };
+    if (hasSsmPlugin)
+        return { transport: "ssm", reason: "fallback-ssm" };
+    return { transport, reason: "unreachable-no-plugin" };
+}
+/**
+ * Apply the reachability gate to a (possibly auto-selected) transport: if it's
+ * `vpn-direct`, TCP-dial the Temporal VPC endpoint and downgrade to SSM when it's
+ * actually unreachable, logging the decision. Returns the effective transport;
+ * a no-op for any non-`vpn-direct` transport.
+ *
+ * Called on BOTH auto-select paths — the normal resolve result AND the
+ * Tailscale→legacy fallback (when no mesh login config exists for the derived
+ * context) — so a `vpn-direct` can never reach `startServices` unprobed
+ * (MESH-2016).
+ */
+async function gateVpnDirectReachability(transport, devOutput) {
+    if (transport !== "vpn-direct")
+        return transport;
+    const temporalTunnel = devOutput.tunnels?.["temporal"];
+    if (!temporalTunnel)
+        return transport;
+    const { host, port } = temporalTunnel;
+    const reachable = await probeTcpReachable(host, port, 1500);
+    const decision = reachabilityFallbackTransport(transport, reachable, hasSessionManagerPlugin());
+    if (decision.reason === "reachable") {
+        logInfo(`Transport: VPN-direct — Temporal VPC endpoint ${host}:${port} is reachable.`);
+    }
+    else if (decision.reason === "fallback-ssm") {
+        logWarn(`Transport: VPN reports connected but the Temporal VPC endpoint ${host}:${port} is unreachable ` +
+            `(tailnet-blind presence check) — falling back to SSM tunnels (2XXXX port range; VPN-only features ` +
+            `like in-cluster kubectl are unavailable). Pin with --transport=ssm to skip this probe.`);
+    }
+    else if (decision.reason === "unreachable-no-plugin") {
+        logWarn(`Transport: Temporal VPC endpoint ${host}:${port} is unreachable and the SSM session-manager ` +
+            `plugin is missing — VPN-direct will likely fail. Fix VPN routing or install the plugin ` +
+            `(see: mesh dev doctor).`);
+    }
+    return decision.transport;
+}
+/**
+ * Derive the Headscale login-server URL from a login context's issuer
+ * (`identity.<env>.<domain>` → `vpn.<env>.<domain>`). Used for the Tailscale
+ * transport's OIDC join. Returns null if the context has no cached login config.
+ */
+function deriveLoginServer(context) {
+    const cfg = getContextConfig(context);
+    if (!cfg?.issuer)
+        return null;
+    try {
+        const u = new URL(cfg.issuer);
+        const parts = u.hostname.split(".");
+        parts[0] = "vpn";
+        return `https://${parts.join(".")}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function preferredSsmLocalPort(remotePort) {
+    const preferred = SSM_TUNNEL_BASE_PORT + remotePort;
+    if (preferred > 65535) {
+        throw new Error(`Cannot allocate SSM tunnel port for remote port ${remotePort}: preferred local port ${preferred} exceeds 65535`);
+    }
+    return preferred;
+}
+/**
+ * Reserve a deterministic local-port candidate for an SSM tunnel.
+ *
+ * This prevents two tunnels with the same remote port (common for HTTPS
+ * endpoints) from being assigned the same localhost port before the AWS CLI
+ * has a chance to bind it.
+ */
+export function reserveSsmLocalPortCandidate(remotePort, reservedPorts, startAt = preferredSsmLocalPort(remotePort)) {
+    for (let port = startAt; port <= 65535; port += 1) {
+        if (!reservedPorts.has(port)) {
+            reservedPorts.add(port);
+            return port;
+        }
+    }
+    throw new Error(`Cannot allocate SSM tunnel port for remote port ${remotePort}: no free candidate ports remain`);
+}
+async function allocateSsmLocalPort(remotePort, reservedPorts) {
+    let nextCandidate = preferredSsmLocalPort(remotePort);
+    while (nextCandidate <= 65535) {
+        const candidate = reserveSsmLocalPortCandidate(remotePort, reservedPorts, nextCandidate);
+        if (await isPortFree(candidate)) {
+            return candidate;
+        }
+        nextCandidate = candidate + 1;
+    }
+    throw new Error(`Cannot allocate SSM tunnel port for remote port ${remotePort}: no local ports are available`);
+}
+/**
+ * Check if the session-manager-plugin is installed (required for SSM tunnels).
+ */
+function hasSessionManagerPlugin() {
+    try {
+        execFileSync('which', ['session-manager-plugin'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start SSM port-forwarding tunnels as tmux windows within the dev session.
+ *
+ * For each tunnel defined in devOutput (e.g., temporal, rds), this:
+ * 1. Reads the bastion instance ID and service endpoints from SSM
+ * 2. Spawns `aws ssm start-session` in a dedicated tmux window
+ * 3. Rewrites devOutput.tunnels to point at localhost:2XXXX
+ *
+ * Returns the rewritten devOutput with tunnels pointing to localhost.
+ */
+async function startSsmTunnels(sessionName, devOutput) {
+    const platformEnv = devOutput.platform?.env ?? 'dev';
+    // The bastion is a HUB platform resource (/mesh-platform/<hub>/<env>/platform-bastion),
+    // not an app-tenant resource — devOutput.platform.tenant is the APP tenant (e.g. acme),
+    // which for shared tenants has no bastion. Resolve under the platform/hub name; default
+    // to "mesh" (matching how resolveTemporalAuth reads platform-level params).
+    const bastionTenant = devOutput.platform?.name ?? 'mesh';
+    // Read bastion info from SSM
+    const bastion = await getPlatformBastionInfo(bastionTenant, platformEnv).catch(() => null);
+    if (!bastion) {
+        logError('Could not read platform bastion info from SSM.');
+        logInfo('Make sure PlatformBastion is deployed in your platform stack.');
+        logInfo("If you don't have a bastion, connect via VPN instead: mesh vpn connect");
+        throw new Error('SSM tunnel fallback unavailable: no bastion found');
+    }
+    const rewritten = JSON.parse(JSON.stringify(devOutput));
+    const tunnelCount = Object.keys(devOutput.tunnels).length;
+    if (tunnelCount === 0) {
+        logInfo('No tunnels defined — SSM fallback not needed.');
+        return rewritten;
+    }
+    logInfo(`Starting ${tunnelCount} SSM tunnel(s) via bastion ${bastion.instanceId}...`);
+    // Map devOutput tunnel names to bastion service keys
+    // devOutput uses names like "temporal", "rds"; bastion uses "temporal-frontend", "rds"
+    const tunnelToBastionKey = {
+        temporal: 'temporal-frontend',
+        'temporal-ui': 'temporal-ui',
+        rds: 'rds',
+        db: 'rds',
+        database: 'rds',
+    };
+    // Observability tunnels are non-fatal under SSM fallback — skip with a warning
+    // rather than aborting the dev loop when the bastion doesn't expose them.
+    const OPTIONAL_TUNNEL_NAMES = new Set([
+        'loki',
+        'prometheus',
+        'tempo',
+        'pushgateway',
+        'grafana',
+    ]);
+    const missingEndpoints = [];
+    const skippedOptional = [];
+    const reservedPorts = new Set();
+    const plannedTunnels = [];
+    for (const [tunnelName] of Object.entries(devOutput.tunnels)) {
+        const bastionKey = tunnelToBastionKey[tunnelName] ?? tunnelName;
+        const endpoint = bastion.services[bastionKey];
+        if (!endpoint) {
+            // Observability tunnels degrade gracefully under SSM fallback: without
+            // them the consuming app's monitoring views (logs/metrics/traces) won't
+            // work, but they must not block the core dev loop. Only critical tunnels
+            // (temporal, rds, ...) are fatal when the bastion can't reach them.
+            if (OPTIONAL_TUNNEL_NAMES.has(tunnelName)) {
+                skippedOptional.push(`${tunnelName} (bastion key: ${bastionKey})`);
+            }
+            else {
+                missingEndpoints.push(`${tunnelName} (bastion key: ${bastionKey})`);
+            }
+            continue;
+        }
+        plannedTunnels.push({
+            tunnelName,
+            endpoint,
+            localPort: await allocateSsmLocalPort(endpoint.port, reservedPorts),
+        });
+    }
+    if (skippedOptional.length > 0) {
+        logWarn('Skipping optional observability tunnel(s) not exposed by the bastion (SSM fallback):');
+        for (const skipped of skippedOptional) {
+            logInfo(`  Skipped: ${skipped}`);
+        }
+        logInfo('  Monitoring views (logs/metrics/traces) stay unavailable until VPN is connected.');
+    }
+    if (missingEndpoints.length > 0) {
+        logError('SSM tunnel fallback cannot cover every required dev tunnel.');
+        for (const missing of missingEndpoints) {
+            logInfo(`  Missing: ${missing}`);
+        }
+        logInfo(`  Available bastion services: ${Object.keys(bastion.services).join(', ') || '(none)'}`);
+        logInfo('Connect VPN instead or deploy/update PlatformBastion with the missing service endpoints.');
+        throw new Error('SSM tunnel fallback unavailable: missing bastion endpoints');
+    }
+    for (const { tunnelName, endpoint, localPort } of plannedTunnels) {
+        // Create a tmux window for this tunnel
+        const windowName = `tunnel-${tunnelName}`;
+        const ssmCmd = [
+            'aws',
+            'ssm',
+            'start-session',
+            '--target',
+            bastion.instanceId,
+            '--document-name',
+            'AWS-StartPortForwardingSessionToRemoteHost',
+            '--parameters',
+            `'${JSON.stringify({
+                host: [endpoint.host],
+                portNumber: [String(endpoint.port)],
+                localPortNumber: [String(localPort)],
+            })}'`,
+        ].join(' ');
+        execFileSync('tmux', ['new-window', '-t', sessionName, '-n', windowName]);
+        // Keep window alive so tunnel errors are visible
+        execFileSync('tmux', ['set-option', '-t', `${sessionName}:${windowName}`, 'remain-on-exit', 'on'], { stdio: 'ignore' });
+        execFileSync('tmux', ['send-keys', '-t', `${sessionName}:${windowName}`, ssmCmd, 'Enter']);
+        // Rewrite the tunnel to point at localhost
+        rewritten.tunnels[tunnelName] = {
+            host: 'localhost',
+            port: localPort,
+        };
+        logSuccess(`  ${tunnelName}: localhost:${localPort} → ${endpoint.host}:${endpoint.port} (via SSM)`);
+    }
+    return rewritten;
+}
 /**
  * Update the DevBox host's Caddy reverse proxy config.
  *
@@ -541,9 +1417,9 @@ async function resolveSecrets(secrets, tunnels) {
  */
 async function updateDevboxProxy(devOutput, appRoot) {
     const appName = devOutput.app ?? path.basename(appRoot);
-    const tenant = devOutput.platform?.tenant ?? "mesh";
-    const env = devOutput.platform?.env ?? "dev";
-    const stack = devOutput.stack ?? "dev";
+    const tenant = devOutput.platform?.tenant ?? 'mesh';
+    const env = devOutput.platform?.env ?? 'dev';
+    const stack = devOutput.stack ?? 'dev';
     const baseDomain = `${tenant}-${env}.mesh.local`;
     // Build hostname → port map
     const services = {};
@@ -553,148 +1429,462 @@ async function updateDevboxProxy(devOutput, appRoot) {
         }
     }
     for (const [name, tunnel] of Object.entries(devOutput.tunnels)) {
-        if (tunnel.localPort) {
-            services[`${name}.${stack}.${appName}.${baseDomain}`] = tunnel.localPort;
+        if (tunnel.port) {
+            services[`${name}.${stack}.${appName}.${baseDomain}`] = tunnel.port;
         }
     }
     if (Object.keys(services).length === 0)
         return;
     // Generate Caddyfile
     const lines = [
-        "# Auto-generated by mesh dev — do not edit manually.",
-        "",
-        ":8080 {",
+        '# Auto-generated by mesh dev — do not edit manually.',
+        '',
+        ':8080 {',
         '  respond /health "OK" 200',
-        "}",
-        "",
+        '}',
+        '',
     ];
     for (const [hostname, port] of Object.entries(services)) {
         lines.push(`http://${hostname} {`);
         lines.push(`  reverse_proxy localhost:${port}`);
-        lines.push("}");
-        lines.push("");
+        lines.push('}');
+        lines.push('');
     }
-    const caddyfile = lines.join("\n");
+    const caddyfile = lines.join('\n');
     // Write to host's /etc/caddy via a throwaway container with a host volume mount.
     // The Docker socket is the HOST's, so -v /etc/caddy mounts the HOST path.
-    execFileSync("docker", [
-        "run", "--rm",
-        "-v", "/etc/caddy:/etc/caddy",
-        "busybox", "sh", "-c",
+    execFileSync('docker', [
+        'run',
+        '--rm',
+        '-v',
+        '/etc/caddy:/etc/caddy',
+        'busybox',
+        'sh',
+        '-c',
         `cat > /etc/caddy/Caddyfile << 'CADDYEOF'\n${caddyfile}\nCADDYEOF`,
-    ], { stdio: "pipe" });
+    ], { stdio: 'pipe' });
     // Reload Caddy on the host via nsenter into PID 1's mount namespace
-    execFileSync("docker", [
-        "run", "--rm", "--pid=host", "--privileged",
-        "busybox", "nsenter", "-t", "1", "-m", "--",
-        "caddy", "reload", "--config", "/etc/caddy/Caddyfile", "--adapter", "caddyfile",
-    ], { stdio: "pipe" });
-    logSuccess("DevBox proxy updated:");
+    execFileSync('docker', [
+        'run',
+        '--rm',
+        '--pid=host',
+        '--privileged',
+        'busybox',
+        'nsenter',
+        '-t',
+        '1',
+        '-m',
+        '--',
+        'caddy',
+        'reload',
+        '--config',
+        '/etc/caddy/Caddyfile',
+        '--adapter',
+        'caddyfile',
+    ], { stdio: 'pipe' });
+    logSuccess('DevBox proxy updated:');
     for (const [hostname, port] of Object.entries(services)) {
         logInfo(`  http://${hostname} → localhost:${port}`);
     }
 }
-// ============================================================================
-// Core actions
-// ============================================================================
-/**
- * Start all services in tmux windows.
- */
-async function startServices(sessionName, appRoot, devOutput, headless) {
-    if (!hasTmux()) {
-        logError("tmux is required. Install with: brew install tmux");
-        process.exit(1);
+async function setupSubdomainRouting(devOutput, appRoot) {
+    // 1. Get Tailscale info
+    const tsInfo = await getTailscaleInfo();
+    if (!tsInfo)
+        return null;
+    const appName = devOutput.app ?? path.basename(appRoot);
+    const stack = devOutput.stack ?? 'dev';
+    const baseDomain = `${appName}.${stack}.${tsInfo.hostname}.vpn.internal`;
+    // 2. Derive Headscale DNS config from platform context (same convention as `mesh vpn`)
+    const platform = devOutput.platform ?? { tenant: 'mesh', env: 'dev' };
+    const dnsConfig = headscaleDnsConfig(platform.name ?? platform.tenant, platform.env);
+    // 3. Build DNS records for all services + tunnels
+    const records = [];
+    for (const [name, service] of Object.entries(devOutput.services)) {
+        if (service.port) {
+            records.push({ name: `${name}.${baseDomain}`, type: 'A', value: tsInfo.ip });
+        }
     }
-    // Kill existing session
-    if (sessionExists(sessionName)) {
-        logInfo(`Killing existing session: ${sessionName}`);
-        killSession(sessionName);
+    for (const [name] of Object.entries(devOutput.tunnels)) {
+        records.push({ name: `${name}.${baseDomain}`, type: 'A', value: tsInfo.ip });
+    }
+    // 4. Remove stale DNS records (best-effort)
+    try {
+        unregisterDnsRecords(dnsConfig, baseDomain);
+    }
+    catch {
+        /* ignore */
+    }
+    // 5. Generate Caddyfile
+    const caddyDir = '/tmp/mesh-dev-caddy';
+    const caddyfile = path.join(caddyDir, 'Caddyfile');
+    if (!fs.existsSync(caddyDir))
+        fs.mkdirSync(caddyDir, { recursive: true });
+    // Build Caddy config — bind directly to the Tailscale IP on port 80.
+    // In kernel tun mode, tailscale0 is a real interface so Caddy can listen
+    // on it without any tailscale serve layer in between.
+    const caddyLines = [`# mesh-dev: ${appName}/${stack} (${tsInfo.hostname})`, ''];
+    for (const [name, service] of Object.entries(devOutput.services)) {
+        if (service.port) {
+            caddyLines.push(`http://${name}.${baseDomain} {`);
+            caddyLines.push(`  bind ${tsInfo.ip}`);
+            caddyLines.push(`  reverse_proxy localhost:${service.port}`);
+            caddyLines.push('}');
+            caddyLines.push('');
+        }
+    }
+    for (const [name, tunnel] of Object.entries(devOutput.tunnels)) {
+        caddyLines.push(`http://${name}.${baseDomain} {`);
+        caddyLines.push(`  bind ${tsInfo.ip}`);
+        caddyLines.push(`  reverse_proxy ${tunnel.host}:${tunnel.port}`);
+        caddyLines.push('}');
+        caddyLines.push('');
+    }
+    fs.writeFileSync(caddyfile, caddyLines.join('\n'));
+    // 6. Start or reload Caddy
+    let caddyRunning = false;
+    try {
+        execFileSync('pgrep', ['-f', 'caddy run.*mesh-dev-caddy'], { stdio: 'pipe' });
+        caddyRunning = true;
+    }
+    catch {
+        /* not running */
+    }
+    if (caddyRunning) {
+        try {
+            execFileSync('caddy', ['reload', '--config', caddyfile, '--adapter', 'caddyfile'], {
+                stdio: 'pipe',
+            });
+        }
+        catch {
+            logWarn('Caddy reload failed — check Caddyfile syntax');
+            return null;
+        }
+    }
+    else {
+        try {
+            execFileSync('which', ['caddy'], { stdio: 'pipe' });
+        }
+        catch {
+            logWarn('Caddy not found. Install for subdomain routing: curl -fsSL https://caddyserver.com/api/download?os=linux&arch=arm64 -o /usr/local/bin/caddy && chmod +x /usr/local/bin/caddy');
+            return null;
+        }
+        const caddy = spawn('caddy', ['run', '--config', caddyfile, '--adapter', 'caddyfile'], {
+            stdio: 'ignore',
+            detached: true,
+            cwd: caddyDir,
+        });
+        caddy.unref();
+    }
+    // 7. Register DNS records (after Caddy is confirmed running)
+    try {
+        const existing = readDnsRecords(dnsConfig);
+        const allRecords = existing.filter((r) => !r.name.endsWith(baseDomain));
+        allRecords.push(...records);
+        registerDnsRecords(dnsConfig, allRecords);
+    }
+    catch {
+        logWarn('DNS registration failed — Headscale pod may be unreachable. Dev routing may not work.');
+        return null;
+    }
+    return { tsHostname: tsInfo.hostname, tsIp: tsInfo.ip, baseDomain, dnsConfig };
+}
+// ============================================================================
+// Core actions
+// ============================================================================
+/**
+ * Start all services in tmux windows.
+ */
+async function startServices(sessionName, appRoot, devOutput, headless, awsEnv, tunnelPlan = { transport: 'vpn-direct' }, worktreeRoot, taskQueueSuffix = '') {
+    if (!hasTmux()) {
+        logError('tmux is required. Install with: brew install tmux');
+        process.exit(1);
+    }
+    // Always kill any existing session and recreate for a clean start.
+    // Tunnels (if any) are set up as part of this flow below.
+    if (sessionExists(sessionName)) {
+        logInfo(`Killing existing session: ${sessionName}`);
+        killSession(sessionName);
     }
     const serviceNames = Object.keys(devOutput.services);
     if (serviceNames.length === 0) {
-        logWarn("No services defined in dev output.");
-        return;
+        logWarn('No services defined in dev output.');
+        return devOutput;
     }
-    const tunnelNames = Object.keys(devOutput.tunnels);
-    // Create session with a status window
+    // Create tmux session with a status window (always fresh).
     logInfo(`Creating tmux session: ${sessionName}`);
-    execFileSync("tmux", [
-        "new-session", "-d", "-s", sessionName, "-n", "status", "-c", appRoot,
-    ]);
-    // Start tunnels via tunnel manager in the status window (before services)
-    if (tunnelNames.length > 0) {
-        const bastionTunnels = Object.entries(devOutput.tunnels).filter(([, t]) => (t.type ?? "bastion") === "bastion");
-        // Validate bastion tunnels have a bastion instance
-        if (bastionTunnels.length > 0 && !devOutput.bastion?.instanceId) {
-            logError("Bastion tunnels defined but no bastion.instanceId in dev output.");
-            logInfo("Add bastion: { instanceId: '...' } to your dev stack output.");
-            process.exit(1);
+    execFileSync('tmux', ['new-session', '-d', '-s', sessionName, '-n', 'status', '-c', appRoot]);
+    // Set AWS credentials on the session BEFORE starting anything that needs them
+    // (SSM tunnels, services). tmux windows inherit the session environment.
+    setTmuxEnv(sessionName, awsEnv);
+    // Bring up VPC tunnels (rewriting devOutput.tunnels to localhost:PORT) via the
+    // chosen backing. Tailscale (shared per-tenant userspace daemon): an explicit
+    // `--transport tailscale` now hard-fails on any bring-up error (see below); only
+    // an auto-resolved tailscale choice falls back to SSM. vpn-direct needs no tunnels.
+    const hasTunnels = Object.keys(devOutput.tunnels).length > 0;
+    let effectiveTransport = tunnelPlan.transport;
+    if (hasTunnels && effectiveTransport === 'tailscale' && tunnelPlan.tailscale) {
+        try {
+            const rewritten = await startTailscaleTunnels(devOutput, tunnelPlan.tailscale);
+            // Verify the forwarders actually ROUTE, not just bind (MESH-2268). Transport
+            // selection picks tailscale on PRESENCE (a tailscaled binary exists), so an
+            // auto-selected daemon can come up joined to a tailnet that doesn't route the
+            // mesh VPC, or with a dead SOCKS upstream (MESH-2169) — the forwarder binds
+            // its port either way and the bare-accept readiness gate below (waitForPort)
+            // would pass it, letting services start and then die on a gRPC deadline.
+            // Throw on a dead critical tunnel so the catch below applies the same
+            // explicit-hard-fail-vs-auto-SSM-fallback policy as a bring-up failure — and
+            // only commit the rewrite (reassign devOutput) once it holds, so an SSM
+            // fallback runs startSsmTunnels on the ORIGINAL, un-rewritten tunnels.
+            const dead = await firstUnroutableTunnel(rewritten.tunnels);
+            if (dead) {
+                throw new Error(`forwarder for '${dead}' bound but does not route the VPC ` +
+                    `(dead SOCKS upstream or non-routing tailnet)`);
+            }
+            devOutput = rewritten;
+            // Announce ONLY after the join + forwarders actually came up — the previous
+            // pre-flight "Using userspace-Tailscale tunnels" printed before this even ran,
+            // so a fallback still read as success (MESH-2098).
+            logInfo('Connected: userspace-Tailscale tunnels for VPC resources (shared per tenant).');
         }
-        // Set AWS creds on session so tunnel windows inherit them
-        setTmuxEnv(sessionName, getAwsEnvVars());
-        // Write tunnel config for the tunnel manager
-        const stateDir = path.join(os.tmpdir(), "mesh-dev-sessions");
-        if (!fs.existsSync(stateDir))
-            fs.mkdirSync(stateDir, { recursive: true });
-        const tunnelConfigPath = path.join(stateDir, `${sessionName}-tunnels.json`);
-        fs.writeFileSync(tunnelConfigPath, JSON.stringify({
-            tunnels: devOutput.tunnels,
-            bastionId: devOutput.bastion?.instanceId,
-        }));
-        // Run tunnel manager in the status window (combines tunnel management + status display)
-        // Use process.argv to self-reference (npx mesh may not work in all setups)
-        const meshBin = process.argv.slice(0, 2).join(" ");
-        const managerCmd = `${meshBin} dev __tunnel-manager --config '${tunnelConfigPath}' --tmux-session '${sessionName}'`;
-        execFileSync("tmux", [
-            "send-keys", "-t", `${sessionName}:status`, managerCmd, "Enter",
-        ]);
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            if (tunnelPlan.explicit) {
+                // The user explicitly asked for --transport=tailscale. Don't silently
+                // override that with SSM — surface the real reason (often a pending VPN
+                // node registration whose URL was printed above) and let them act.
+                logError(`Tailscale transport failed: ${reason}`);
+                logInfo('If a VPN registration URL was shown above, open it to authorize this machine, then re-run.');
+                logInfo('Or switch backing explicitly: mesh dev --transport ssm');
+                // We already killed the prior session and created a fresh (empty) one
+                // above; tear it down so an explicit-tailscale failure leaves no orphaned
+                // half-session behind.
+                killSession(sessionName);
+                process.exit(1);
+            }
+            logWarn(`Tailscale transport unavailable (${reason}) — falling back to SSM tunnels.`);
+            effectiveTransport = 'ssm';
+        }
+    }
+    if (hasTunnels && effectiveTransport === 'ssm') {
+        devOutput = await startSsmTunnels(sessionName, devOutput);
+    }
+    if (hasTunnels && effectiveTransport !== 'vpn-direct') {
+        // Gate service start on tunnel readiness: poll each tunnel's local port
+        // until it accepts TCP. Without this, Temporal-connected services (api,
+        // worker, vcs) raced the SSM tunnel and died connection-refused at launch.
         for (const [tName, tunnel] of Object.entries(devOutput.tunnels)) {
-            const target = tunnel.type === "kubectl"
-                ? `${tunnel.namespace ?? "default"}/${tunnel.resource ?? tName}:${tunnel.port}`
-                : `${tunnel.host}:${tunnel.port}`;
-            logSuccess(`Tunnel: ${tName} → localhost:${tunnel.localPort} → ${target}`);
+            if (tunnel.host !== 'localhost')
+                continue; // not SSM-rewritten
+            logInfo(`Waiting for tunnel ${tName} (localhost:${tunnel.port})...`);
+            const ready = await waitForPort('localhost', tunnel.port, TUNNEL_READY_TIMEOUT_MS);
+            if (!ready) {
+                logError(`Tunnel '${tName}' did not become ready on localhost:${tunnel.port} within ${TUNNEL_READY_TIMEOUT_MS / 1000}s.`);
+                logInfo(`  Check the tunnel window for errors: tmux attach -t ${sessionName} (window tunnel-${tName})`);
+                logInfo('  Common causes: expired AWS credentials, bastion stopped, session-manager-plugin errors.');
+                throw new Error(`SSM tunnel '${tName}' not ready on localhost:${tunnel.port} after ${TUNNEL_READY_TIMEOUT_MS / 1000}s`);
+            }
+            logSuccess(`  Tunnel ready: ${tName} (localhost:${tunnel.port})`);
+        }
+    }
+    const tunnelNames = Object.keys(devOutput.tunnels);
+    // Set up subdomain routing if Tailscale is available
+    const subdomainCtx = await setupSubdomainRouting(devOutput, appRoot);
+    // Log VPC connections
+    if (tunnelNames.length > 0) {
+        const isSSM = Object.values(devOutput.tunnels).some((t) => t.host === 'localhost' && t.port >= SSM_TUNNEL_BASE_PORT);
+        logSuccess(isSSM ? 'SSM tunnel connections:' : 'VPN direct connections:');
+        for (const [tName, tunnel] of Object.entries(devOutput.tunnels)) {
+            if (subdomainCtx) {
+                logInfo(`  ${tName} \u2192 http://${tName}.${subdomainCtx.baseDomain}`);
+            }
+            else {
+                logInfo(`  ${tName} \u2192 ${tunnel.host}:${tunnel.port}`);
+            }
         }
-        // Give tunnels a moment to establish before starting services
-        logInfo("Waiting for tunnels to establish...");
-        spawnSync("sleep", ["3"]);
     }
     // Resolve secrets from Secrets Manager
     let secretEnvVars = {};
     if (devOutput.secrets && Object.keys(devOutput.secrets).length > 0) {
-        secretEnvVars = await resolveSecrets(devOutput.secrets, devOutput.tunnels);
+        secretEnvVars = await resolveSecrets(devOutput.secrets);
+    }
+    // Resolve Temporal auth credentials from SSM when a temporal endpoint is configured.
+    const tenant = devOutput.platform?.tenant ?? 'mesh';
+    const platformEnv = devOutput.platform?.env ?? 'dev';
+    // Write a session-scoped kubeconfig (aws eks get-token) so the kubectl calls
+    // below (encoding-key read, temporal-pod env fallback) don't depend on an
+    // ambient ~/.kube/config. Best-effort: continue without it if unresolved.
+    // The local platform (`mesh start`) has no cluster — skip entirely.
+    const isLocalPlatform = tenant === 'local';
+    if (!isLocalPlatform) {
+        // Hub platform name — the EKS export lives under it, not under a hardcoded
+        // "mesh" (MESH-2515); same axis as the bastion resolution.
+        const platformName = resolveHubPlatformName(devOutput.platform);
+        const kubeconfigPath = await ensureKubeconfig(platformName, platformEnv, sessionName, {
+            onError: ({ parameter, error }) => logWarn(`EKS cluster resolve failed (${parameter}): ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`),
+        });
+        if (kubeconfigPath) {
+            process.env.KUBECONFIG = kubeconfigPath;
+            setTmuxEnv(sessionName, { KUBECONFIG: kubeconfigPath });
+            logSuccess(`Kubeconfig resolved from SSM (hub ${platformName}/${platformEnv}) → ${kubeconfigPath}`);
+        }
+        else {
+            logWarn('Could not resolve EKS kubeconfig from SSM; kubectl calls will use ambient config (if any).');
+        }
     }
-    // Set shared env vars (AWS creds + secrets) on the tmux session.
-    // Per-service vars are set before each window is created.
-    setTmuxEnv(sessionName, getAwsEnvVars());
+    let temporalAuthVars = {};
+    if (devOutput.tunnels['temporal']) {
+        // Deliberately NOT the `?? 'mesh'` fallback the EKS path above uses: the
+        // Temporal-auth fallback is `?? tenant` (dedicated tenants may run their
+        // own Temporal). Whether that difference is correct is MESH-2551.
+        temporalAuthVars = await resolveTemporalAuth(tenant, platformEnv, devOutput.platform?.name ?? tenant);
+        // Resolve the encoding key from K8s so local dev can decrypt
+        // payloads created by deployed workers.
+        const appName = devOutput.app ?? '';
+        if (appName) {
+            const encodingKey = resolveTemporalEncodingKey(tenant, platformEnv, appName);
+            if (encodingKey) {
+                temporalAuthVars.TEMPORAL_ENCODING_KEY = encodingKey;
+            }
+        }
+        // Set TEMPORAL_ADDRESS to the VPC endpoint for direct VPN access (or the
+        // pinned loopback address under SSM fallback — see tunnelClientAddress).
+        const temporalTunnel = devOutput.tunnels['temporal'];
+        temporalAuthVars.TEMPORAL_ADDRESS = tunnelClientAddress(temporalTunnel);
+    }
+    // Set shared env vars (secrets + temporal auth) on the tmux session.
+    // AWS creds were already set earlier (before SSM tunnels started).
     setTmuxEnv(sessionName, secretEnvVars);
+    setTmuxEnv(sessionName, temporalAuthVars);
+    // Inject dev user identity from mesh login credentials so services can
+    // emulate the oauth2-proxy auth headers locally.
+    //
+    // The credentials are stored under the platform context (e.g. 'mesh.dev'),
+    // not the tenant name. Use 'mesh' as the platform name since all tenants
+    // share the same Zitadel instance.
+    //
+    // Services (e.g., Hub UI) use these env vars as a fallback when the real
+    // oauth2-proxy `X-Forwarded-*` request headers are absent:
+    //   DEV_USER_ID           - subject from idToken, matches conversation ownership
+    //   DEV_USER_EMAIL        - user email from idToken
+    //   DEV_USER_ID_TOKEN     - full idToken JWT (profile claims, authorization hint)
+    //   DEV_USER_ACCESS_TOKEN - full accessToken JWT (has project:roles claim)
+    // Local platform creds live under the `local` context (mesh login local).
+    const credContext = devOutput.platform
+        ? isLocalPlatform
+            ? 'local'
+            : `mesh.${devOutput.platform.env}`
+        : null;
+    const devUserVars = resolveDevUserVars(devOutput);
+    if (Object.keys(devUserVars).length > 0) {
+        setTmuxEnv(sessionName, devUserVars);
+        logSuccess(`Dev user injected from mesh login: ${credContext}`);
+        // Serve a continuously-fresh dev-user token so services survive past the
+        // ~1h Zitadel horizon without a restart (MESH-2039). The static vars above
+        // remain the fallback when this URL is absent. App-agnostic: gated on the
+        // platform context, not the app — any `mesh dev` app inherits it.
+        const tokenPort = await findFreePort();
+        const tokenUrl = `http://127.0.0.1:${tokenPort}`;
+        setTmuxEnv(sessionName, { DEV_USER_TOKEN_URL: tokenUrl });
+        execFileSync('tmux', ['new-window', '-t', sessionName, '-n', 'token-server']);
+        execFileSync('tmux', ['set-option', '-t', `${sessionName}:token-server`, 'remain-on-exit', 'on'], { stdio: 'ignore' });
+        execFileSync('tmux', [
+            'send-keys',
+            '-t',
+            `${sessionName}:token-server`,
+            `npx mesh dev __token-server ${tokenPort} ${credContext}`,
+            'Enter',
+        ]);
+        // Best-effort readiness so the first requests land (non-fatal).
+        for (let i = 0; i < 15 && !(await isPortListening(tokenPort)); i++) {
+            await new Promise((r) => setTimeout(r, 200));
+        }
+        logSuccess(`Dev-user token-server: ${tokenUrl} (context ${credContext})`);
+    }
+    else if (credContext) {
+        logWarn(`No mesh login credentials found for '${credContext}'.`);
+        logInfo(`  Run: mesh login ${credContext}`);
+        logInfo('  Hub UI will show unauthenticated state without valid credentials.');
+    }
+    const monorepoRoot = findMonorepoRoot();
     for (const [name, service] of Object.entries(devOutput.services)) {
-        const cmd = service.command.join(" ");
+        const cmd = service.command.join(' ');
         // Skip services with no dev command (e.g., deployed-only like ApiDocs)
         if (!cmd) {
             logInfo(`Skipped: ${name} (no dev command, deployed to K8s)`);
             continue;
         }
-        const serviceDir = path.resolve(appRoot, service.src);
-        // Per-service env vars are inlined into the command via `env K=V`
-        // to avoid cross-service leaks through the tmux session environment.
-        const serviceVars = getServiceEnvVars(service, devOutput.tunnels);
-        const prefixedCmd = `${envPrefix(serviceVars)}${cmd}`;
-        execFileSync("tmux", [
-            "new-window", "-t", sessionName, "-n", name, "-c", serviceDir,
-        ]);
+        const serviceDir = path.resolve(appRoot, rebaseServiceSrc(service.src, monorepoRoot));
+        // Wrong-worktree guard (MESH-2013): if `rebaseServiceSrc` couldn't re-root the
+        // deploy-time absolute path onto THIS worktree, `serviceDir` can point into a
+        // DIFFERENT worktree — silently running stale code. Refuse rather than launch it.
+        if (worktreeRoot && fs.existsSync(serviceDir)) {
+            const wtRootWithSep = worktreeRoot.endsWith(path.sep) ? worktreeRoot : worktreeRoot + path.sep;
+            if (serviceDir !== worktreeRoot && !serviceDir.startsWith(wtRootWithSep)) {
+                logError(`Refusing to launch '${name}': its source resolved to ${serviceDir}, ` +
+                    `outside this worktree (${worktreeRoot}). The stack was likely deployed ` +
+                    `from another worktree. Re-run \`mesh deploy up\` here, or pass --app.`);
+                process.exit(1);
+            }
+        }
+        // Skip services whose source directory doesn't exist in this worktree.
+        // This happens when the Pulumi stack was deployed from a different branch
+        // that added a service not yet present here (e.g., hub-worker added on
+        // feature/hub-credential-management but absent from feature/app-detail-redesign).
+        if (!fs.existsSync(serviceDir)) {
+            logWarn(`Skipped: ${name} (source directory not found: ${serviceDir}` +
+                `${serviceDir !== service.src ? ` — rebased from ${service.src}` : ''})`);
+            continue;
+        }
+        // Per-service env vars are written to a 0600 env file and `source`d by
+        // the launch command, scoping them to the process (no cross-service
+        // leaks through the tmux session environment) while keeping the
+        // send-keys string short — inlining the full env used to intermittently
+        // exceed what tmux send-keys delivers intact, silently truncating the
+        // command so the service never started.
+        //
+        // Overlay the RESOLVED Temporal vars (real encoding key + tunnel address +
+        // M2M auth, fetched from K8s/SSM) on top of the dev-output env. The dev
+        // output carries placeholder values from the Agent's Temporal link (e.g.
+        // a `dev-encoding-key-*` placeholder), and the per-service env would
+        // otherwise shadow the session-level resolved values — desyncing services
+        // that DO carry the placeholder (worker) from those that don't (api),
+        // which breaks payload encryption (mismatched encoding keys → decode null).
+        const serviceVars = {
+            ...getServiceEnvVars(service, devOutput.tunnels),
+            ...temporalAuthVars,
+            // Overlay the resolved dev-user identity for the same reason as the
+            // Temporal vars: the dev output may carry a placeholder (e.g. hub ui's
+            // DEV_USER_ACCESS_TOKEN="dev-local"), and since the sourced env file
+            // wins over the tmux session env, the placeholder would clobber the
+            // real token injected above — silently 401ing tenant-scoped Hub views.
+            ...devUserVars,
+            // Per-worktree Temporal task-queue isolation (MESH-2013 Slice 2): agent
+            // workers/apps append this to their task-queue names so concurrent
+            // worktrees don't steal each other's workflow tasks. Empty on the primary
+            // checkout → omitted → unchanged historical behavior.
+            ...(taskQueueSuffix ? { MESH_TASK_QUEUE_SUFFIX: taskQueueSuffix } : {}),
+        };
+        const envFilePath = getServiceEnvFilePath(sessionName, name);
+        writeEnvFile(envFilePath, serviceVars);
+        // Local mode ships the service's stdout to the platform's log pipeline
+        // via OTLP (assets/log-shipper.mjs): the OTEL_* vars in the env file
+        // carry the hosted k8s_* attribution, so the Hub's logs view covers
+        // local runs with zero file plumbing.
+        const launchCmd = buildLaunchCommand(envFilePath, serviceDir, cmd, service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : undefined);
+        execFileSync('tmux', ['new-window', '-t', sessionName, '-n', name, '-c', serviceDir]);
         // Keep window alive on exit so errors are visible
-        execFileSync("tmux", [
-            "set-option", "-t", `${sessionName}:${name}`, "remain-on-exit", "on",
-        ], { stdio: "ignore" });
-        execFileSync("tmux", [
-            "send-keys", "-t", `${sessionName}:${name}`, prefixedCmd, "Enter",
-        ]);
-        logSuccess(`Started: ${name} (${service.src}, port ${service.port})`);
+        execFileSync('tmux', ['set-option', '-t', `${sessionName}:${name}`, 'remain-on-exit', 'on'], {
+            stdio: 'ignore',
+        });
+        execFileSync('tmux', ['send-keys', '-t', `${sessionName}:${name}`, launchCmd, 'Enter']);
+        // Log the ACTUAL launch dir (`serviceDir`, after the worktree rebase), not the
+        // raw deploy-time `service.src` — printing the pre-rebase path made a correctly
+        // re-rooted service look like it was running from a different (stale) worktree.
+        logSuccess(`Started: ${name} (${serviceDir}, port ${service.port})`);
     }
     // Generate reverse proxy config for DevBox hostname-based routing.
-    // When running inside a devbox (DEVCONTAINER=1 on EC2), update the host's
-    // Caddy config so services are accessible via {service}.mesh.local.
-    if (process.env.DEVCONTAINER === "1") {
+    if (process.env.DEVCONTAINER === '1') {
         try {
             await updateDevboxProxy(devOutput, appRoot);
         }
@@ -702,56 +1892,65 @@ async function startServices(sessionName, appRoot, devOutput, headless) {
             logWarn(`Could not update devbox proxy: ${e.message}`);
         }
     }
-    // Status window: if no tunnels, run watch for live status updates.
-    // (When tunnels exist, the tunnel manager already runs in the status window.)
-    if (tunnelNames.length === 0) {
-        const statusCmd = `watch -n2 -t npx mesh dev --status --session '${sessionName}'`;
-        execFileSync("tmux", [
-            "send-keys", "-t", `${sessionName}:status`, statusCmd, "Enter",
-        ]);
-    }
-    console.log("");
+    // Run live status updates in the status window
+    const statusCmd = `watch -n2 -t npx mesh dev --status --session '${sessionName}'`;
+    execFileSync('tmux', ['send-keys', '-t', `${sessionName}:status`, statusCmd, 'Enter']);
+    console.log('');
     logSuccess(`Dev session started: ${sessionName}`);
-    console.log("");
+    console.log('');
     if (tunnelNames.length > 0) {
-        console.log("Tunnels:");
+        console.log('Connections (VPN direct):');
         for (const tName of tunnelNames) {
             const t = devOutput.tunnels[tName];
-            const target = t.type === "kubectl"
-                ? `${t.namespace ?? "default"}/${t.resource ?? tName}:${t.port}`
-                : `${t.host}:${t.port}`;
-            const label = t.type === "kubectl" ? " (kubectl)" : "";
-            console.log(`  ${tName.padEnd(20)} localhost:${t.localPort} → ${target}${label}`);
+            if (subdomainCtx) {
+                console.log(`  ${tName.padEnd(20)} http://${tName}.${subdomainCtx.baseDomain}`);
+            }
+            else {
+                console.log(`  ${tName.padEnd(20)} ${t.host}:${t.port}`);
+            }
         }
-        console.log("");
+        console.log('');
     }
-    console.log("Services:");
+    console.log('Services:');
     for (const name of serviceNames) {
         const s = devOutput.services[name];
         const hasCmd = s.command && s.command.length > 0;
         if (hasCmd) {
-            const addr = s.port ? `http://localhost:${s.port}` : "(no port)";
-            console.log(`  ${name.padEnd(20)} ${addr}`);
+            if (subdomainCtx && s.port) {
+                console.log(`  ${name.padEnd(20)} http://${name}.${subdomainCtx.baseDomain}`);
+            }
+            else {
+                const addr = s.port ? `http://localhost:${s.port}` : '(no port)';
+                console.log(`  ${name.padEnd(20)} ${addr}`);
+            }
         }
         else {
             console.log(`  ${name.padEnd(20)} (deployed)`);
         }
     }
-    console.log("");
+    console.log('');
     if (!headless) {
-        logInfo("Attaching to tmux session...");
-        spawnSync("tmux", ["attach", "-t", sessionName], { stdio: "inherit" });
+        logInfo('Attaching to tmux session...');
+        if (process.env.TMUX) {
+            spawnSync('tmux', ['switch-client', '-t', sessionName], { stdio: 'inherit' });
+        }
+        else {
+            spawnSync('tmux', ['attach', '-t', sessionName], { stdio: 'inherit' });
+        }
     }
     else {
         console.log(`Attach with:  tmux attach -t ${sessionName}`);
         console.log(`Stop with:    mesh dev --kill`);
-        console.log("");
+        console.log('');
     }
+    // Return the (possibly SSM-tunnel-rewritten) devOutput so the caller can
+    // persist it in session state for --status / restart.
+    return devOutput;
 }
 /**
  * Show status of running services.
  */
-function showStatus(sessionName, devOutput, asJson) {
+async function showStatus(sessionName, devOutput, asJson) {
     if (!sessionExists(sessionName)) {
         if (asJson) {
             console.log(JSON.stringify({ running: false, session: sessionName }));
@@ -764,106 +1963,135 @@ function showStatus(sessionName, devOutput, asJson) {
     // Get tmux window list
     let windows = [];
     try {
-        const raw = execFileSync("tmux", [
-            "list-windows", "-t", sessionName, "-F", "#{window_name} #{pane_dead}",
-        ], { encoding: "utf-8" });
-        windows = raw.trim().split("\n");
+        const raw = execFileSync('tmux', ['list-windows', '-t', sessionName, '-F', '#{window_name} #{pane_dead}'], { encoding: 'utf-8' });
+        windows = raw.trim().split('\n');
     }
     catch {
         // Session might have disappeared
     }
     const windowStatus = {};
     for (const line of windows) {
-        const [name, dead] = line.split(" ");
+        const [name, dead] = line.split(' ');
         if (name)
-            windowStatus[name] = dead === "1" ? "exited" : "running";
+            windowStatus[name] = dead === '1' ? 'exited' : 'running';
     }
     const tunnelNames = Object.keys(devOutput.tunnels);
+    // Live-probe each tunnel so a mid-session tunnel death shows as DOWN here
+    // (this render runs every ~2s in the status window) — MESH-2016.
+    const tunnelHealth = await probeTunnelHealth(devOutput.tunnels);
+    const healthByName = new Map(tunnelHealth.map((h) => [h.name, h]));
     if (asJson) {
         const services = {};
         for (const [name, svc] of Object.entries(devOutput.services)) {
             services[name] = {
-                status: windowStatus[name] ?? "unknown",
+                status: windowStatus[name] ?? 'unknown',
                 port: svc.port,
                 src: svc.src,
             };
         }
         const tunnels = {};
         for (const [name, tun] of Object.entries(devOutput.tunnels)) {
-            const target = tun.type === "kubectl"
-                ? `${tun.namespace ?? "default"}/${tun.resource ?? name}:${tun.port}`
-                : `${tun.host}:${tun.port}`;
-            const listening = isPortListeningSync(tun.localPort);
             tunnels[name] = {
-                status: listening ? "running" : "down",
-                localPort: tun.localPort,
-                remote: target,
-                type: tun.type ?? "bastion",
+                host: tun.host,
+                port: tun.port,
+                reachable: healthByName.get(name)?.reachable ?? false,
             };
         }
         console.log(JSON.stringify({ running: true, session: sessionName, services, tunnels }, null, 2));
     }
     else {
-        console.log("── mesh dev ──");
-        console.log("");
+        console.log('\u2500\u2500 mesh dev \u2500\u2500');
+        console.log('');
         console.log(`Session: ${sessionName}`);
         if (tunnelNames.length > 0) {
-            // Tunnel manager runs in a single window; check health by probing local ports
-            const managerStatus = windowStatus["tunnels"] ?? "unknown";
-            const managerIcon = managerStatus === "running" ? "●" : "✗";
-            console.log("");
-            console.log(`Tunnels: ${managerIcon} manager ${managerStatus}`);
-            for (const [name, tun] of Object.entries(devOutput.tunnels)) {
-                const listening = isPortListeningSync(tun.localPort);
-                const icon = listening ? "●" : "✗";
-                const status = listening ? "up" : "down";
-                const target = tun.type === "kubectl"
-                    ? `${tun.namespace ?? "default"}/${tun.resource ?? name}:${tun.port}`
-                    : `${tun.host}:${tun.port}`;
-                const label = tun.type === "kubectl" ? " kubectl" : "";
-                console.log(`  ${icon} ${name.padEnd(16)} ${status.padEnd(10)} :${tun.localPort} → ${target}${label}`);
-            }
-        }
-        console.log("");
-        console.log("Services:");
+            console.log('');
+            for (const line of formatTunnelHealth(tunnelHealth))
+                console.log(line);
+        }
+        console.log('');
+        console.log('Services:');
         for (const [name, svc] of Object.entries(devOutput.services)) {
             const hasCmd = svc.command && svc.command.length > 0;
             if (!hasCmd) {
                 console.log(`  ☁ ${name.padEnd(16)} deployed                ${svc.src}`);
                 continue;
             }
-            const status = windowStatus[name] ?? "unknown";
-            const icon = status === "running" ? "●" : status === "exited" ? "✗" : "?";
-            const addr = svc.port ? `:${svc.port}` : "";
+            const status = windowStatus[name] ?? 'unknown';
+            const icon = status === 'running' ? '●' : status === 'exited' ? '✗' : '?';
+            const addr = svc.port ? `:${svc.port}` : '';
             console.log(`  ${icon} ${name.padEnd(16)} ${status.padEnd(10)} ${addr.padEnd(8)} ${svc.src}`);
         }
-        console.log("");
-        console.log("Commands:");
-        console.log("  mesh dev restart <s>   Restart a service");
-        console.log("  mesh dev logs <s>      Tail service logs");
-        console.log("  mesh dev --kill        Stop everything");
-        console.log("");
-        console.log("tmux: Ctrl+b n/p switch windows, d detach");
+        console.log('');
+        console.log('Commands:');
+        console.log('  mesh dev restart <s>   Restart a service');
+        console.log('  mesh dev logs <s>      Tail service logs');
+        console.log('  mesh dev --kill        Stop everything');
+        console.log('');
+        console.log('tmux: Ctrl+b n/p switch windows, d detach');
     }
 }
 /**
  * Restart a single service window.
  */
-function restartService(sessionName, serviceName, _appRoot, devOutput) {
-    const service = devOutput.services[serviceName];
+async function restartService(sessionName, serviceName, appRoot, devOutput, awsEnv, opts) {
+    let service = devOutput.services[serviceName];
     if (!service) {
         logError(`Unknown service: ${serviceName}`);
-        logInfo(`Available: ${Object.keys(devOutput.services).join(", ")}`);
+        logInfo(`Available: ${Object.keys(devOutput.services).join(', ')}`);
         process.exit(1);
     }
     if (!sessionExists(sessionName)) {
         logError(`No active session: ${sessionName}. Run 'mesh dev' first.`);
         process.exit(1);
     }
+    // --refresh-env: regenerate this service's env file from CURRENT stack/SSM
+    // outputs BEFORE killing the running process, so a failed read leaves the
+    // good env file (and the running service) untouched (fail-closed).
+    if (opts?.refreshEnv) {
+        if (!opts.stack) {
+            logError('--refresh-env: no stack resolved; keeping existing env and NOT restarting.');
+            return;
+        }
+        // The session's allocated devOutput pins the ports/tunnels to reuse.
+        const pinned = opts.sessionState?.devOutput ?? devOutput;
+        let fresh;
+        try {
+            fresh = getDevOutput(appRoot, opts.stack, awsEnv);
+        }
+        catch (err) {
+            logError(`--refresh-env: failed to read stack output for '${opts.stack}'. Keeping the existing env file for '${serviceName}' and NOT restarting.`);
+            logInfo(String(err?.message ?? err));
+            return;
+        }
+        const merged = mergePinnedPorts(fresh, pinned);
+        const mergedService = merged.services[serviceName];
+        if (!mergedService) {
+            logError(`--refresh-env: service '${serviceName}' is absent from the fresh stack output. Keeping the existing env file and NOT restarting.`);
+            return;
+        }
+        const temporalAuthVars = await resolveTemporalAuthVars(sessionName, merged);
+        // Recompute the per-worktree suffix (deterministic from the worktree path,
+        // so it matches what launch wrote) — a restarted service must keep polling
+        // this worktree's isolated task queue (MESH-2013 Slice 2).
+        const { taskQueueSuffix } = resolveWorktreeIdentity(appRoot);
+        const serviceVars = {
+            ...getServiceEnvVars(mergedService, merged.tunnels),
+            ...temporalAuthVars,
+            // Same overlay as launch: without it, --refresh-env rewrites the env
+            // file from dev output and its DEV_USER_* placeholders clobber the real
+            // token from `mesh login` (the "restart silently 401s the Hub" trap).
+            ...resolveDevUserVars(merged),
+            ...(taskQueueSuffix ? { MESH_TASK_QUEUE_SUFFIX: taskQueueSuffix } : {}),
+        };
+        writeEnvFile(getServiceEnvFilePath(sessionName, serviceName), serviceVars);
+        // Relaunch from the refreshed service definition (command/src may have changed).
+        service = mergedService;
+        logSuccess(`Regenerated env for '${serviceName}' from current stack/SSM outputs.`);
+    }
     const target = `${sessionName}:${serviceName}`;
     // Kill the current pane process and respawn
     try {
-        execFileSync("tmux", ["respawn-pane", "-k", "-t", target], { stdio: "ignore" });
+        execFileSync('tmux', ['respawn-pane', '-k', '-t', target], { stdio: 'ignore' });
     }
     catch {
         // Window might not exist yet
@@ -871,12 +2099,27 @@ function restartService(sessionName, serviceName, _appRoot, devOutput) {
         process.exit(1);
     }
     // Refresh shared env (AWS creds may have rotated) on the session.
-    // Per-service vars are inlined into the command to avoid cross-service leaks.
-    setTmuxEnv(sessionName, getAwsEnvVars());
-    const serviceVars = getServiceEnvVars(service, devOutput.tunnels);
-    const cmd = service.command.join(" ");
-    const prefixedCmd = `${envPrefix(serviceVars)}${cmd}`;
-    execFileSync("tmux", ["send-keys", "-t", target, prefixedCmd, "Enter"]);
+    setTmuxEnv(sessionName, awsEnv);
+    const cmd = service.command.join(' ');
+    // Source the SAME env file written at launch — it is the session's env
+    // contract for this service, guaranteeing a byte-identical environment.
+    // Reconstructing env here has historically diverged from launch (e.g.
+    // TEMPORAL_ENCODING_KEY drift → "cannot decrypt payload" / missing key →
+    // "Unknown encoding: binary/encrypted").
+    const envFilePath = getServiceEnvFilePath(sessionName, serviceName);
+    let restartCmd;
+    if (fs.existsSync(envFilePath)) {
+        const serviceDir = path.resolve(appRoot, rebaseServiceSrc(service.src, findMonorepoRoot()));
+        // Keep the local log pipeline attached across restarts.
+        restartCmd = buildLaunchCommand(envFilePath, serviceDir, cmd, service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : undefined);
+    }
+    else {
+        logWarn(`No launch env file for '${serviceName}' (${envFilePath}) — session predates env-file launches.`);
+        logWarn('Falling back to reconstructed env; restart `mesh dev` for a faithful environment.');
+        const serviceVars = getServiceEnvVars(service, devOutput.tunnels);
+        restartCmd = `${envPrefix(serviceVars)}${cmd}`;
+    }
+    execFileSync('tmux', ['send-keys', '-t', target, restartCmd, 'Enter']);
     logSuccess(`Restarted: ${serviceName}`);
 }
 /**
@@ -889,216 +2132,121 @@ function showLogs(sessionName, serviceName, tail) {
     }
     const target = `${sessionName}:${serviceName}`;
     try {
-        const result = execFileSync("tmux", [
-            "capture-pane", "-t", target, "-p", "-S", `-${tail}`,
-        ], { encoding: "utf-8" });
+        const result = execFileSync('tmux', ['capture-pane', '-t', target, '-p', '-S', `-${tail}`], {
+            encoding: 'utf-8',
+        });
         process.stdout.write(result);
     }
     catch {
         logError(`Could not capture logs for '${serviceName}'.`);
-        logInfo("Is the service name correct? Check with: mesh dev --status");
+        logInfo('Is the service name correct? Check with: mesh dev --status');
         process.exit(1);
     }
 }
 // ============================================================================
-// Tunnel Manager
+// Command registration
 // ============================================================================
-import { spawn } from "child_process";
 /**
- * Tunnel manager — spawns all tunnels as child processes, monitors health,
- * auto-restarts on failure, and prints a live status table.
- *
- * Runs in a single tmux window instead of one window per tunnel.
+ * Assemble a {@link DoctorContext} for the current app/stack/session, resolving
+ * the deployer role the same way the `restart`/launch paths do (default role +
+ * Zitadel-claim admin selection). Used by `mesh dev doctor`.
  */
-function runTunnelManager(configPath, sessionName) {
-    const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-    const tunnelEntries = Object.entries(config.tunnels);
-    if (tunnelEntries.length === 0) {
-        console.log("No tunnels to manage.");
-        return;
-    }
-    const states = tunnelEntries.map(([name, tunnel]) => {
-        let argv;
-        if ((tunnel.type ?? "bastion") === "bastion") {
-            argv = [
-                "aws", "ssm", "start-session",
-                "--target", config.bastionId,
-                "--document-name", "AWS-StartPortForwardingSessionToRemoteHost",
-                "--parameters", JSON.stringify({
-                    host: [tunnel.host],
-                    portNumber: [String(tunnel.port)],
-                    localPortNumber: [String(tunnel.localPort)],
-                }),
-            ];
-        }
-        else {
-            const ns = tunnel.namespace ?? "default";
-            const resource = tunnel.resource ?? `svc/${name}`;
-            argv = ["kubectl", "port-forward", "-n", ns, resource, `${tunnel.localPort}:${tunnel.port}`];
-        }
-        return {
-            name,
-            tunnel,
-            process: null,
-            status: "starting",
-            restarts: 0,
-            lastStart: 0,
-            argv,
-        };
-    });
-    function startTunnel(state) {
-        state.status = "starting";
-        state.lastStart = Date.now();
-        const [cmd, ...args] = state.argv;
-        const child = spawn(cmd, args, {
-            stdio: ["ignore", "pipe", "pipe"],
-        });
-        child.stdout?.on("data", () => {
-            // SSM/kubectl output — tunnel is establishing
-            if (state.status === "starting") {
-                state.status = "up";
-            }
-        });
-        child.stderr?.on("data", (data) => {
-            const msg = data.toString().trim();
-            if (msg && !msg.includes("Starting session") && !msg.includes("Forwarding from")) {
-                console.log(`  [${state.name}] ${msg}`);
-            }
+function buildDoctorContext(appRoot, stack, sessionName) {
+    const state = loadSessionState(sessionName);
+    const defaultDeployerRole = readStackConfig(appRoot, stack, 'mesh:deployerRole');
+    const adminDeployerRole = readStackConfig(appRoot, stack, 'mesh:adminDeployerRole');
+    const platformContext = derivePlatformContext(appRoot, stack);
+    let deployerRole = defaultDeployerRole;
+    if (defaultDeployerRole) {
+        const meshCreds = platformContext ? readCredentials(platformContext) : null;
+        const idToken = meshCreds && new Date(meshCreds.expiresAt) > new Date() ? meshCreds.idToken : null;
+        deployerRole = selectRoleForCaller(idToken, {
+            defaultRole: defaultDeployerRole,
+            adminRole: adminDeployerRole ?? undefined,
         });
-        child.on("exit", (code) => {
-            state.process = null;
-            if (shuttingDown)
-                return;
-            state.status = "down";
-            state.restarts++;
-            // Back off: wait longer between restarts (1s, 2s, 4s, 8s, max 30s)
-            const delay = Math.min(1000 * Math.pow(2, Math.min(state.restarts - 1, 4)), 30000);
-            console.log(`  [${state.name}] exited (code ${code}), restarting in ${delay / 1000}s...`);
-            state.status = "restarting";
-            setTimeout(() => {
-                if (!shuttingDown)
-                    startTunnel(state);
-            }, delay);
-        });
-        state.process = child;
-        // Mark as "up" after a short delay if still running
-        setTimeout(() => {
-            if (state.process && state.status === "starting") {
-                state.status = "up";
-            }
-        }, 2000);
-    }
-    let shuttingDown = false;
-    function shutdown() {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        console.log("\nShutting down tunnels...");
-        for (const state of states) {
-            if (state.process) {
-                state.process.kill("SIGTERM");
-            }
-        }
-        setTimeout(() => process.exit(0), 1000);
-    }
-    process.on("SIGTERM", shutdown);
-    process.on("SIGINT", shutdown);
-    // Print header
-    console.log("mesh dev — tunnel manager");
-    console.log("─".repeat(60));
-    for (const state of states) {
-        const target = state.tunnel.type === "kubectl"
-            ? `${state.tunnel.namespace ?? "default"}/${state.tunnel.resource ?? state.name}:${state.tunnel.port}`
-            : `${state.tunnel.host}:${state.tunnel.port}`;
-        const label = state.tunnel.type === "kubectl" ? "kubectl" : "bastion";
-        console.log(`  ${state.name.padEnd(16)} :${state.tunnel.localPort} → ${target} (${label})`);
-    }
-    console.log("─".repeat(60));
-    console.log("");
-    // Start all tunnels
-    for (const state of states) {
-        startTunnel(state);
-    }
-    // Periodically print full status (tunnels + services)
-    function printStatus() {
-        if (shuttingDown)
-            return;
-        // Clear screen and move cursor to top
-        process.stdout.write("\x1b[2J\x1b[H");
-        console.log("── mesh dev ──");
-        console.log("");
-        // Tunnels
-        console.log("Tunnels:");
-        for (const s of states) {
-            const icon = s.status === "up" ? "●" : s.status === "restarting" ? "↻" : s.status === "starting" ? "…" : "✗";
-            const statusLabel = s.status === "up" ? "up" : s.status === "restarting" ? `restart(${s.restarts})` : s.status;
-            const target = s.tunnel.type === "kubectl"
-                ? `${s.tunnel.namespace ?? "default"}/${s.tunnel.resource ?? s.name}:${s.tunnel.port}`
-                : `${s.tunnel.host}:${s.tunnel.port}`;
-            const label = s.tunnel.type === "kubectl" ? " kubectl" : "";
-            console.log(`  ${icon} ${s.name.padEnd(16)} ${statusLabel.padEnd(14)} :${s.tunnel.localPort} → ${target}${label}`);
-        }
-        // Services (check tmux window status if session name provided)
-        if (sessionName) {
-            let windows = [];
-            try {
-                const raw = execFileSync("tmux", [
-                    "list-windows", "-t", sessionName, "-F", "#{window_name} #{pane_dead}",
-                ], { encoding: "utf-8" });
-                windows = raw.trim().split("\n");
-            }
-            catch { }
-            const windowStatus = {};
-            for (const line of windows) {
-                const [name, dead] = line.split(" ");
-                if (name)
-                    windowStatus[name] = dead === "1" ? "exited" : "running";
-            }
-            // Get service names from session state
-            const state = loadSessionState(sessionName);
-            if (state?.devOutput?.services) {
-                console.log("");
-                console.log("Services:");
-                for (const [name, svc] of Object.entries(state.devOutput.services)) {
-                    const hasCmd = svc.command && svc.command.length > 0;
-                    if (!hasCmd) {
-                        console.log(`  ☁ ${name.padEnd(16)} deployed                ${svc.src}`);
-                        continue;
-                    }
-                    const status = windowStatus[name] ?? "unknown";
-                    const icon = status === "running" ? "●" : status === "exited" ? "✗" : "?";
-                    const addr = svc.port ? `:${svc.port}` : "";
-                    console.log(`  ${icon} ${name.padEnd(16)} ${status.padEnd(14)} ${addr.padEnd(8)} ${svc.src}`);
-                }
-            }
-        }
-        console.log("");
-        console.log("mesh dev --status / --kill   |   Ctrl+b n/p switch windows");
     }
-    // Print initial status after tunnels start, then refresh every 2s
-    setTimeout(printStatus, 3000);
-    setInterval(printStatus, 2000);
+    return {
+        appRoot,
+        stack,
+        sessionName,
+        deployerRole,
+        platformContext,
+        credMethod: null,
+        sessionState: state,
+    };
 }
-// ============================================================================
-// Command registration
-// ============================================================================
 export function registerDevCommand(program) {
     const dev = program
-        .command("dev")
-        .description("Start local dev environment (reads Pulumi stack outputs)")
-        .option("--app <path>", "Path to a Pulumi app (relative to monorepo root or cwd)")
-        .option("--stage <stage>", "Pulumi stack name (default: auto-detect)")
-        .option("--headless", "Start without attaching to tmux")
-        .option("--kill", "Kill existing dev session")
-        .option("--status", "Show service status")
-        .option("--json", "Output status as JSON (with --status)")
-        .option("--session <name>", "Custom tmux session name");
+        .command('dev')
+        .description('Start local dev environment (reads Pulumi stack outputs)')
+        .option('--app <path>', 'Path to a Pulumi app (relative to monorepo root or cwd)')
+        .option('--stack <stack>', 'Pulumi stack name (default: auto-detect)')
+        .addOption(new Option('--stage <stack>', 'Deprecated alias for --stack').hideHelp())
+        .option('--headless', 'Start without attaching to tmux')
+        .option('--kill', 'Kill existing dev session')
+        .option('--status', 'Show service status')
+        .option('--json', 'Output status as JSON (with --status)')
+        .option('--session <name>', 'Override the tmux session name (auto-derived per git worktree by default — omit to keep concurrent worktrees isolated)')
+        .option('--dry-run', 'Print the resolved worktree/session/port plan and exit without launching')
+        .option('--force', 'Relaunch even if workflow code changed since launch (may strand in-flight conversations)')
+        .option('--profile <name>', 'AWS SSO profile to use (e.g., mesh-dev)')
+        .addOption(new Option('--transport <mode>', 'Tunnel backing (default: auto — Tailscale when available, else SSM/VPN)').choices(['auto', 'ssm', 'tailscale']))
+        .option('--local', 'Run against the local Mesh platform from `mesh start` (no AWS, no VPN, no Pulumi state). Auto-selected when the app has no Pulumi.yaml.')
+        .option('--externals [names]', "Also realize the app's declared external services (package.json → mesh.externals): all of them, or a comma-separated subset of name[=mode] entries. Modes: mock (emulate — OpenAPI spec via Prism, or a mock process), local (a local version via docker compose, e.g. a vendor DB replica), remote (connect to the actual service — vendor sandbox credentials, or the external configured in the app's tenant environment). name=mode overrides the declaration's default for this run (e.g. plaid-db=remote). Each realization seeds the ExternalService credential secret so resolveCredentials() runs unchanged. Local mode only.")
+        .option('--mock [names]', 'Alias for --externals.')
+        .option('--runner <runner>', "Process runner for local mode: 'tmux' (default — dev machines) or 'docker' (CI/headless: services run as a docker compose project with host networking; Linux semantics).", 'tmux');
+    // Hidden: the dev-user token-server (MESH-2039). Launched into its own tmux
+    // window by the dev launcher; serves a continuously-fresh dev-user token.
+    dev
+        .command('__token-server <port> <context>', { hidden: true })
+        .action(async (port, context) => {
+        const { startTokenServer } = await import('./dev-token-server.js');
+        await startTokenServer(Number(port), context);
+    });
     // Default action: start or show status
     dev.action(async (options) => {
+        // An explicit --profile must win over stale shell-exported STS credentials.
+        // The AWS SDK/CLI prefer AWS_ACCESS_KEY_ID over AWS_PROFILE, so clear any
+        // static credentials before resolving the deployer role.
+        if (options.profile) {
+            applyAwsProfileOverride(options.profile);
+        }
         // Fast-path: --status/--kill with explicit --session can skip app root resolution
         if (options.session && (options.status || options.kill)) {
             const sessionName = options.session;
+            if (loadSessionState(sessionName)?.runner === 'docker') {
+                if (options.kill) {
+                    dockerDevDown(sessionName);
+                    composeExternalsDown(loadSessionState(sessionName)?.composeExternals);
+                    localProbesRemove(loadSessionState(sessionName)?.externalProbeFiles);
+                    removeSessionState(sessionName);
+                    logSuccess(`Killed docker dev session: ${sessionName}`);
+                }
+                else {
+                    console.log(dockerDevPs(sessionName));
+                }
+                return;
+            }
             if (options.kill) {
+                composeExternalsDown(loadSessionState(sessionName)?.composeExternals);
+                localProbesRemove(loadSessionState(sessionName)?.externalProbeFiles);
+                // Clean up DNS records for this app
+                try {
+                    const devOutput = loadSessionState(sessionName)?.devOutput;
+                    if (devOutput) {
+                        const tsInfo = await getTailscaleInfo();
+                        if (tsInfo) {
+                            const appName = devOutput.app ?? sessionName.replace(/-dev$/, '');
+                            const stack = devOutput.stack ?? 'dev';
+                            const baseDomain = `${appName}.${stack}.${tsInfo.hostname}.vpn.internal`;
+                            const platform = devOutput.platform ?? { tenant: 'mesh', env: 'dev' };
+                            unregisterDnsRecords(headscaleDnsConfig(platform.name ?? platform.tenant, platform.env), baseDomain);
+                        }
+                    }
+                }
+                catch {
+                    /* best effort */
+                }
                 if (sessionExists(sessionName)) {
                     killSession(sessionName);
                     logSuccess(`Killed session: ${sessionName}`);
@@ -1112,16 +2260,50 @@ export function registerDevCommand(program) {
             // --status with --session: use state file, no Pulumi needed
             const state = loadSessionState(sessionName);
             if (state) {
-                showStatus(sessionName, state.devOutput, !!options.json);
+                await showStatus(sessionName, state.devOutput, !!options.json);
                 return;
             }
             // No state — fall through to normal flow
         }
         const appRoot = findAppRoot(options.app);
         const projectName = getProjectName(appRoot);
-        const sessionName = options.session ?? `${projectName}-dev`;
+        // Port block scoped to (worktree, app): concurrent sibling-app sessions
+        // must draw disjoint ports (probing races slow boots). Scoped once here so
+        // local and tethered modes resolve the SAME plan — every other field stays
+        // worktree-scoped, so session naming and task queues are unaffected.
+        const worktree = withAppScopedPortBlock(resolveWorktreeIdentity(appRoot), appRoot);
+        const sessionName = options.session ?? deriveSessionName(projectName, worktree);
         // --kill
         if (options.kill) {
+            composeExternalsDown(loadSessionState(sessionName)?.composeExternals);
+            localProbesRemove(loadSessionState(sessionName)?.externalProbeFiles);
+            if (loadSessionState(sessionName)?.runner === 'docker') {
+                dockerDevDown(sessionName);
+                removeSessionState(sessionName);
+                logSuccess(`Killed docker dev session: ${sessionName}`);
+                return;
+            }
+            // Tailscale VPN tunnels are machine-global + shared across sessions, so
+            // they persist on purpose after a kill. Capture the tenant before state
+            // is removed so we can point at the explicit stop below.
+            const killTsTenant = loadSessionState(sessionName)?.devOutput.platform?.name ?? 'mesh';
+            // Clean up DNS records for this app
+            try {
+                const devOutput = loadSessionState(sessionName)?.devOutput;
+                if (devOutput) {
+                    const tsInfo = await getTailscaleInfo();
+                    if (tsInfo) {
+                        const appName = devOutput.app ?? projectName;
+                        const stack = devOutput.stack ?? 'dev';
+                        const baseDomain = `${appName}.${stack}.${tsInfo.hostname}.vpn.internal`;
+                        const platform = devOutput.platform ?? { tenant: 'mesh', env: 'dev' };
+                        unregisterDnsRecords(headscaleDnsConfig(platform.name ?? platform.tenant, platform.env), baseDomain);
+                    }
+                }
+            }
+            catch {
+                /* best effort */
+            }
             if (sessionExists(sessionName)) {
                 killSession(sessionName);
                 logSuccess(`Killed session: ${sessionName}`);
@@ -1130,37 +2312,589 @@ export function registerDevCommand(program) {
                 logInfo(`No active session: ${sessionName}`);
             }
             removeSessionState(sessionName);
+            if (readTailscaleState(killTsTenant)) {
+                logInfo(`VPN tunnels persist across sessions — stop them with: mesh vpn tunnel down --tenant ${killTsTenant}`);
+            }
+            return;
+        }
+        // ── Local mode (design §5.2) ─────────────────────────────────────
+        // Explicit --local, or auto when the app has no Pulumi program at all
+        // (hasStackBacking also checks the monorepo ROOT — apps like apps/hub
+        // deploy via a root program and must keep the tethered default).
+        // Synthesizes DevOutput from repo conventions and wires services to the
+        // `mesh start` platform: no AWS credentials, no VPN, no Pulumi state.
+        const localMode = !!options.local || !hasStackBacking(appRoot);
+        if (localMode) {
+            // Read-only status query: report and exit BEFORE any side effect
+            // (platform boot, Zitadel provisioning, registry writes) — parity
+            // with the tethered path's early --status short-circuit.
+            if (options.status) {
+                const state = loadSessionState(sessionName);
+                if (state?.runner === 'docker') {
+                    console.log(dockerDevPs(sessionName));
+                    return;
+                }
+                const statusOutput = state?.devOutput ??
+                    buildLocalDevOutput(appRoot, detectLocalTenant(appRoot), { mocks: {} });
+                showStatus(sessionName, statusOutput, !!options.json);
+                return;
+            }
+            const dockerRunner = options.runner === 'docker';
+            if (!dockerRunner && !hasTmux()) {
+                logError('tmux is not installed. Fix: brew install tmux (or use --runner docker)');
+                process.exit(1);
+            }
+            await ensureLocalPlatformRunning();
+            const localTenant = detectLocalTenant(appRoot);
+            logInfo(`Project: ${projectName}, Stack: local (mesh start platform)`);
+            // --externals (alias --mock): resolve the requested subset of the
+            // app's declared externals (package.json → mesh.externals). Entries
+            // are name[=mode] — an explicit mode overrides the declaration's
+            // default for this run (materialized onto the decl so every
+            // downstream externalMode() call agrees). Mock-mode externals join
+            // the same orchestration as services named mock-{name}; all
+            // realizations get their credential secret seeded after ports are
+            // final.
+            const externalsRequest = options.externals ?? options.mock;
+            let selectedMocks = {};
+            // The externals the developer NAMED (empty for the bare flag, which
+            // selects everything declared). Failing to realize one of these is
+            // fatal; failing to realize one the developer never asked for by name
+            // only costs that external.
+            const requestedExplicitly = new Set();
+            if (externalsRequest) {
+                const declared = readLocalMocks(appRoot);
+                let requested;
+                let overrides = new Map();
+                if (externalsRequest === true) {
+                    requested = Object.keys(declared);
+                }
+                else {
+                    ({ names: requested, overrides } = parseExternalsSelection(String(externalsRequest)));
+                    for (const name of requested)
+                        requestedExplicitly.add(name);
+                }
+                const unknown = requested.filter((name) => !declared[name]);
+                if (unknown.length > 0) {
+                    throw new MeshCliError(`Unknown external(s): ${unknown.join(', ')} — declared in package.json mesh.externals: ${Object.keys(declared).join(', ') || '(none)'}`, { remediation: { docs: 'package.json → "mesh": { "externals": { … } }' } });
+                }
+                if (requested.length === 0) {
+                    logWarn('No externals declared (package.json → mesh.externals) — continuing without.');
+                }
+                selectedMocks = Object.fromEntries(requested.map((name) => [
+                    name,
+                    overrides.has(name) ? { ...declared[name], mode: overrides.get(name) } : declared[name],
+                ]));
+                // Validate every declaration's resolved mode up front — a bad decl
+                // (or an override the decl can't satisfy) should fail here, not
+                // after half the orchestration is up.
+                for (const [name, decl] of Object.entries(selectedMocks))
+                    externalMode(name, decl);
+            }
+            const rawDevOutput = buildLocalDevOutput(appRoot, localTenant, {
+                mocks: selectedMocks,
+            });
+            // --dry-run (worktree-plan parity with tethered mode): print the
+            // resolved session/port plan and exit before any side effect —
+            // no Zitadel provisioning, no registry writes, no launch.
+            if (options.dryRun) {
+                printDevPlan(sessionName, appRoot, worktree, await allocatePorts(rawDevOutput, worktree));
+                // Non-service realizations (local/remote) don't appear in the port
+                // plan — list them so the dry run shows the whole picture.
+                for (const [name, decl] of Object.entries(selectedMocks)) {
+                    const mode = externalMode(name, decl);
+                    if (mode === 'local') {
+                        console.log(`  external ${name.padEnd(18)} local — docker compose (${decl.compose}) → localhost:${decl.port}`);
+                    }
+                    else if (mode === 'remote') {
+                        console.log(`  external ${name.padEnd(18)} remote — actual service credentials (no local process)`);
+                    }
+                }
+                return;
+            }
+            // Auto-provision the app tenant's auth config (approved Zitadel
+            // tenant-auth pattern: org per tenant → project per app → application
+            // per service + credential secret). Best-effort: the dev loop still
+            // works if Zitadel isn't seeded yet.
+            try {
+                const tenant = localTenant;
+                const app = rawDevOutput.app ?? projectName;
+                logInfo(`Provisioning auth config for tenant '${tenant}', app '${app}'…`);
+                const services = Object.keys(rawDevOutput.services);
+                // Mocks are stand-ins, not services of the app — no Zitadel
+                // application for them (the registry still lists them for the Hub).
+                const authServices = services.filter((name) => !name.startsWith('mock-'));
+                // App-declared project roles (package.json → mesh.auth.roles): created
+                // on the project and granted to the local `{app}-m2m` caller, so
+                // role-scoped services (roles claim → scopes) accept its tokens.
+                let authRoles = [];
+                try {
+                    const appPkg = JSON.parse(fs.readFileSync(path.join(appRoot, 'package.json'), 'utf-8'));
+                    if (Array.isArray(appPkg?.mesh?.auth?.roles)) {
+                        authRoles = appPkg.mesh.auth.roles.filter((r) => typeof r === 'string');
+                    }
+                }
+                catch {
+                    // no package.json / unparsable — roles stay empty
+                }
+                await ensureAppTenantAuth({ tenant, app, services: authServices, roles: authRoles });
+                // The app's own Temporal namespace ({tenant}-{env}-{app}) — the same
+                // name the cloud provisioner creates and the Hub's per-app workflow
+                // view resolves.
+                await ensureTemporalNamespace(localAppNamespace(tenant, app));
+            }
+            catch (err) {
+                logWarn(`Auth auto-provisioning skipped: ${err instanceof Error ? err.message : err}` +
+                    ` — if the local Zitadel predates seeding, run: mesh stop --destroy && mesh start`);
+            }
+            const devOutput = await allocatePorts(rawDevOutput, worktree);
+            // Register AFTER allocatePorts: the registry must carry the ports the
+            // services actually listen on, or StackPort/Hub (and anything reading
+            // /mesh-platform/…/stacks/local) points at dead URLs.
+            try {
+                await registerLocalApp({
+                    tenant: localTenant,
+                    app: devOutput.app ?? projectName,
+                    services: Object.keys(devOutput.services),
+                    ports: Object.fromEntries(Object.entries(devOutput.services).map(([name, svc]) => [name, svc.port])),
+                    // ExternalService.link() parity: consuming services carry the
+                    // external names, so the Hub shows consumers + per-app uptime.
+                    links: Object.values(selectedMocks)
+                        .map((decl) => decl.external)
+                        .filter((n) => !!n),
+                });
+            }
+            catch (err) {
+                logWarn(`Local registry registration skipped: ${err instanceof Error ? err.message : err}`);
+            }
+            // Wire realizations AFTER ports are final: realize each declaration
+            // by mode, then seed the external's credential secret and register it
+            // in the Hub — the app's resolveCredentials() path runs unchanged.
+            //   mock   → mock-{name} service URL (Prism / mock process)
+            //   local  → docker compose up -d --wait, endpoint from decl.port
+            //   remote → actual-service credentials seeded (inline, or pulled
+            //            from the app's tenant environment)
+            const composeExternals = [];
+            const externalProbeFiles = [];
+            for (const [name, decl] of Object.entries(selectedMocks)) {
+                const mode = externalMode(name, decl);
+                try {
+                    let probeFile;
+                    if (mode === 'local') {
+                        logInfo(`Starting docker external '${name}' (${decl.compose})…`);
+                        // undefined = adopted a realization another checkout owns —
+                        // not recorded, so --kill leaves it running.
+                        const composeRef = await composeExternalUp(appRoot, sessionName, name, decl);
+                        if (composeRef)
+                            composeExternals.push(composeRef);
+                        probeFile = await seedLocalMock({
+                            tenant: localTenant,
+                            app: devOutput.app ?? projectName,
+                            name,
+                            decl,
+                            endpoint: { url: `http://localhost:${decl.port}`, host: 'localhost', port: decl.port },
+                        });
+                    }
+                    else if (mode === 'remote') {
+                        probeFile = await seedLocalMock({
+                            tenant: localTenant,
+                            app: devOutput.app ?? projectName,
+                            name,
+                            decl,
+                        });
+                    }
+                    else {
+                        const mockService = devOutput.services[`mock-${name}`];
+                        if (!mockService)
+                            continue;
+                        probeFile = await seedLocalMock({
+                            tenant: localTenant,
+                            app: devOutput.app ?? projectName,
+                            name,
+                            decl,
+                            endpoint: {
+                                url: `http://localhost:${mockService.port}`,
+                                host: 'localhost',
+                                port: mockService.port,
+                            },
+                        });
+                    }
+                    if (probeFile)
+                        externalProbeFiles.push(probeFile);
+                }
+                catch (err) {
+                    // A remote external the developer didn't name costs only itself:
+                    // the bare `--externals` selects everything declared, and a
+                    // machine with no AWS identity (or no vendor key in the shell)
+                    // must still get its mock and local externals — that's the
+                    // zero-access local loop. Naming it keeps the failure fatal.
+                    if (mode === 'remote' && !requestedExplicitly.has(name) && err instanceof MeshCliError) {
+                        logWarn(`External '${name}': skipped — ${err.message}` +
+                            ` (re-run with \`mesh dev --externals ${name}=remote\` to make this fatal).`);
+                        continue;
+                    }
+                    if (err instanceof MeshCliError)
+                        throw err; // bad decl / missing env var / failed remote pull — hard stop
+                    if (mode === 'local') {
+                        // The app's services depend on this external — starting them
+                        // against a dead dependency helps nobody.
+                        throw new MeshCliError(`Docker external '${name}' failed to start: ${err instanceof Error ? err.message : err}`, { remediation: { command: `docker compose -f ${decl.compose} up  # debug it directly` } });
+                    }
+                    logWarn(`External '${name}' credential seeding failed: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            if (dockerRunner) {
+                // C2: render the same DevOutput as a docker compose project.
+                const composePath = writeDevCompose(sessionName, appRoot, devOutput.services);
+                logInfo(`Docker runner: ${composePath}`);
+                dockerDevUp(sessionName);
+                saveSessionState(sessionName, {
+                    appRoot,
+                    stack: 'local',
+                    devOutput,
+                    startedAt: new Date().toISOString(),
+                    runner: 'docker',
+                    composeExternals,
+                    externalProbeFiles,
+                });
+                console.log('');
+                logSuccess(`Dev session started (docker): ${sessionName}`);
+                console.log('');
+                console.log('Services:');
+                for (const [name, service] of Object.entries(devOutput.services)) {
+                    console.log(`  ${name.padEnd(20)} http://localhost:${service.port}`);
+                }
+                console.log('');
+                console.log(`Status with:  mesh dev --status --session '${sessionName}'`);
+                console.log('Stop with:    mesh dev --kill');
+                return;
+            }
+            const finalDevOutput = await startServices(sessionName, appRoot, devOutput, !!options.headless, localAwsEnv(), // ministack wiring — the only "AWS" children need
+            { transport: 'vpn-direct' });
+            saveSessionState(sessionName, {
+                appRoot,
+                stack: 'local',
+                devOutput: finalDevOutput,
+                startedAt: new Date().toISOString(),
+                runner: 'tmux',
+                composeExternals,
+                externalProbeFiles,
+            });
             return;
         }
-        const stack = detectStack(appRoot, options.stage);
+        if (options.mock || options.externals) {
+            logWarn('--externals/--mock is local-mode only for now (tethered dev outputs do not carry external declarations yet — MESH-1885). Continuing without them.');
+        }
+        const stack = detectStack(appRoot, resolveStackOption(options));
         logInfo(`Project: ${projectName}, Stack: ${stack}`);
-        const rawDevOutput = getDevOutput(appRoot, stack);
+        // Detect if the user accidentally ran `mesh dev` from the monorepo root
+        // instead of an app directory. The monorepo root has a Pulumi.yaml but
+        // no services/apps to run. Standalone apps (create-app scaffolds) ARE
+        // their own workspace root — an api/ or worker/ package right here means
+        // this is an app, not a monorepo root.
+        const monorepoRoot = findMonorepoRoot();
+        const looksLikeStandaloneApp = ['api', 'worker', 'web'].some((dir) => fs.existsSync(path.join(appRoot, dir, 'package.json')));
+        if (monorepoRoot && path.resolve(appRoot) === path.resolve(monorepoRoot) && !looksLikeStandaloneApp) {
+            logError(`mesh dev should be run from an app directory, not the monorepo root.\n`);
+            logInfo('Try:');
+            logInfo('  cd apps/hub && mesh dev');
+            logInfo('');
+            logInfo('Or specify the app path:');
+            logInfo('  mesh dev --app apps/hub');
+            logInfo('');
+            logInfo('List available apps:');
+            logInfo('  mesh dev list');
+            process.exit(1);
+        }
+        // ── Prerequisite checks ──────────────────────────────────────────
+        // Check all prerequisites upfront so the user gets one clear list of
+        // what needs fixing, rather than failing one step at a time.
+        const issues = [];
+        const profileHint = options.profile ?? process.env.AWS_PROFILE ?? 'mesh-dev';
+        // AWS role + credential resolution.
+        // The stack can declare two role ARNs:
+        //   - `mesh:deployerRole` — the default per-tenant deployer
+        //   - `mesh:adminDeployerRole` — optional admin variant assumed when the
+        //     caller's Zitadel JWT carries an admin-tier role (e.g.
+        //     `mesh.platform:admin`). selectRoleForCaller picks between them.
+        // tmux + credential validation/diagnosis is handled below by the shared
+        // doctor preflight so `mesh dev` and `mesh dev doctor` agree.
+        const platformContext = derivePlatformContext(appRoot, stack);
+        const defaultDeployerRole = readStackConfig(appRoot, stack, 'mesh:deployerRole');
+        const adminDeployerRole = readStackConfig(appRoot, stack, 'mesh:adminDeployerRole');
+        let deployerRole = defaultDeployerRole;
+        if (defaultDeployerRole) {
+            const meshCreds = platformContext ? readCredentials(platformContext) : null;
+            const idToken = meshCreds && new Date(meshCreds.expiresAt) > new Date() ? meshCreds.idToken : null;
+            deployerRole = selectRoleForCaller(idToken, {
+                defaultRole: defaultDeployerRole,
+                adminRole: adminDeployerRole ?? undefined,
+            });
+            if (adminDeployerRole && deployerRole === adminDeployerRole) {
+                logInfo(`Caller has admin Zitadel role — assuming ${deployerRole.split('/').pop()} (admin variant)`);
+            }
+        }
+        let awsEnv;
+        let credMethod = 'ambient';
+        // Method fed to the doctor context: the resolved method on success, or
+        // `null` on a failed resolution so the `creds` check probes for the exact
+        // reason (no-session / expired / assume-denied / stale-env-override).
+        let credMethodForDoctor = 'ambient';
+        if (deployerRole) {
+            const resolved = await resolveAwsCredentials(deployerRole, appRoot, stack);
+            if (!resolved) {
+                awsEnv = {};
+                credMethodForDoctor = null;
+            }
+            else {
+                awsEnv = resolved.env;
+                credMethod = resolved.method;
+                credMethodForDoctor = resolved.method;
+            }
+        }
+        else {
+            awsEnv = getAwsEnvVars();
+            credMethodForDoctor = 'ambient';
+        }
+        // 3. VPN or SSM fallback
+        const vpnConnected = await isVpnConnected();
+        // `let`: the auto-selected `vpn-direct` may be downgraded to `ssm` below by a
+        // reachability probe once devOutput's Temporal endpoint is known (MESH-2016).
+        let transport = resolveTransport(options.transport, {
+            vpnConnected,
+            hasSsmPlugin: hasSessionManagerPlugin(),
+            tailscaleAvailable: tailscaleAvailable(),
+        });
+        if (options.transport === 'tailscale' && !tailscaleAvailable()) {
+            issues.push('  \u2718 --transport=tailscale but the tailscaled binary is missing.\n' +
+                '    Fix: brew install tailscale');
+        }
+        if (transport === 'ssm') {
+            if (hasSessionManagerPlugin()) {
+                if (!vpnConnected) {
+                    logWarn('VPN not connected \u2014 will use SSM port-forwarding tunnels for VPC resources.');
+                }
+                logInfo('  Tunnels use the 2XXXX port range (e.g., PostgreSQL on 25432, Temporal on 27233).');
+                logInfo('  Limitations: no kubectl exec into pods, no internal ingress/ALB access.');
+                logInfo('  For full VPC access, connect VPN: mesh vpn connect');
+            }
+            else {
+                issues.push('  \u2718 VPN is not connected and session-manager-plugin is not installed.\n' +
+                    '    Option 1 (VPN):        mesh vpn connect\n' +
+                    '    Option 2 (SSM):        brew install --cask session-manager-plugin\n' +
+                    '    Option 3 (Tailscale):  mesh dev --transport=tailscale');
+            }
+        }
+        else if (transport === 'tailscale') {
+            // The daemon bring-up + join happen in startServices; announce success there,
+            // not here — otherwise a fallback to SSM still reads as "using Tailscale"
+            // (MESH-2098). A pending node registration prints its own URL during the join.
+            logInfo('Bringing up userspace-Tailscale tunnels for VPC resources (shared per tenant)…');
+        }
+        // Shared doctor preflight: the same checks as `mesh dev doctor`, so launch
+        // and on-demand diagnosis name failures identically. Errors block launch;
+        // warnings (config/worktree) print and proceed.
+        const preflightCtx = {
+            appRoot,
+            stack,
+            sessionName,
+            deployerRole,
+            platformContext,
+            credMethod: credMethodForDoctor,
+            sessionState: null,
+        };
+        const preflight = await runChecks(preflightCtx, 'preflight', ALL_CHECKS);
+        const preflightReport = renderHuman(preflight);
+        if (preflightReport)
+            console.log(preflightReport);
+        const preflightStatus = aggregateStatus(preflight.map((r) => r.result));
+        if (preflightStatus === 'error' || issues.length > 0) {
+            logError('\nPrerequisites not met. Fix the above before running mesh dev, then retry: mesh dev');
+            for (const issue of issues)
+                console.log(issue);
+            process.exit(1);
+        }
+        // ── Credentials resolved, inject into environment ──────────────
+        // Ensure AWS_REGION is set from the Pulumi stack config. Without this, AWS
+        // SDK clients (SSM, Secrets Manager) would default to us-east-1.
+        const awsRegion = readStackConfig(appRoot, stack, 'aws:region');
+        if (awsRegion && !awsEnv.AWS_REGION) {
+            awsEnv.AWS_REGION = awsRegion;
+        }
+        Object.assign(process.env, awsEnv);
+        // Build the env that long-lived child services (ui, api, ai-assistant) and
+        // SSM tunnels will see. When credentials came from AWS SSO, prefer passing
+        // AWS_PROFILE + AWS_REGION so the AWS SDK v3 default provider chain can
+        // auto-refresh from the SSO cache (~8h session) as short-lived STS tokens
+        // expire. Without this, the hub API starts throwing ExpiredTokenException
+        // about an hour in and tenants disappear from the UI. For non-SSO paths
+        // (Zitadel JWT, CI/CD env keys) there is no profile to fall back to, so
+        // pass the STS keys directly and accept that the user must restart
+        // `mesh dev` when they expire.
+        // For the Zitadel deployer path, hand children a self-refreshing
+        // credential_process profile (context + role from the resolution above,
+        // written into this session's scratch dir) instead of a frozen STS triple.
+        const zitadelOpts = credMethod === 'zitadel' && deployerRole
+            ? (() => {
+                const context = derivePlatformContext(appRoot, stack);
+                return context
+                    ? {
+                        context,
+                        roleArn: deployerRole,
+                        sessionScratchDir: getSessionEnvDir(sessionName),
+                        meshBin: resolveStableMeshBin(process.argv[1]),
+                    }
+                    : undefined;
+            })()
+            : undefined;
+        const childAwsEnv = buildChildAwsEnv(awsEnv, credMethod, profileHint, zitadelOpts);
+        let rawDevOutput;
+        try {
+            rawDevOutput = getDevOutput(appRoot, stack, awsEnv);
+        }
+        catch (err) {
+            if (err instanceof MissingStackOutputError) {
+                // Only the launch path can conclude "nothing to run" — print the
+                // forward-chaining first-run fix and exit cleanly (MESH-2097). The
+                // suggested commands carry --stack because the bare forms error right
+                // after `stack init` (matching stack.ts's next-step output).
+                logError(`No Pulumi stack output for '${stack}' — mesh dev has nothing to run.`);
+                logInfo('If this is a new app, initialize and materialize it first:');
+                logInfo('  mesh stack init                       # create your personal dev stack');
+                logInfo(`  mesh deploy up --stack ${stack} --yes  # produce the app output mesh dev reads`);
+                logInfo(`Then: mesh dev --stage ${stack}   (the stack must export an \`app\` or \`dev\` output.)`);
+                logInfo('No deployed stack yet? Run against the local platform: mesh dev --local (needs `mesh start`).');
+                // Surface the underlying read error so an auth/network/JSON failure isn't
+                // silently misdiagnosed as "fresh app" with zero forensics.
+                const cause = err.cause?.message;
+                if (cause)
+                    logInfo(`(underlying stack-read error: ${cause})`);
+                process.exit(1);
+            }
+            throw err;
+        }
         // --status — use persisted state (has allocated ports), fall back to raw
         if (options.status) {
             const state = loadSessionState(sessionName);
-            showStatus(sessionName, state?.devOutput ?? rawDevOutput, !!options.json);
+            await showStatus(sessionName, state?.devOutput ?? rawDevOutput, !!options.json);
+            return;
+        }
+        // Allocate dynamic ports (avoid collisions with other running apps).
+        // devOutput is passed by value and may be rewritten inside startServices
+        // if SSM tunnels are used (to point tunnels at localhost:2XXXX).
+        const devOutput = await allocatePorts(rawDevOutput, worktree);
+        // Reachability gate (MESH-2016): the transport chosen above used a PRESENCE
+        // check (isVpnConnected → "is any Tailscale/VPN up"), which is tailnet-blind —
+        // Tailscale-for-SSH looks connected but doesn't route the mesh VPC. Now that
+        // devOutput is known, probe the real Temporal VPC endpoint and downgrade an
+        // auto-selected vpn-direct to SSM when it's unreachable.
+        transport = await gateVpnDirectReachability(transport, devOutput);
+        // --dry-run: show the resolved worktree/session/port plan, launch nothing.
+        if (options.dryRun) {
+            printDevPlan(sessionName, appRoot, worktree, devOutput);
             return;
         }
-        // Allocate dynamic ports (avoid collisions with other running apps)
-        const devOutput = await allocatePorts(rawDevOutput);
+        // Build the tunnel plan for the chosen transport. For Tailscale, resolve the
+        // shared per-tenant daemon context (tenant = hub platform name, since the
+        // bastion is a hub resource); reuse the daemon's SOCKS port if it's already up.
+        let tunnelPlan = { transport };
+        if (transport === 'tailscale') {
+            const tsTenant = devOutput.platform?.name ?? 'mesh';
+            const tsEnv = devOutput.platform?.env ?? 'dev';
+            const tsContext = derivePlatformContext(appRoot, stack) ?? `${tsTenant}.${tsEnv}`;
+            const loginServer = deriveLoginServer(tsContext);
+            if (!loginServer) {
+                // Implicit selection (auto/unset) must degrade to the legacy transport,
+                // not dead-end. Only an explicit --transport=tailscale may hard-error.
+                const msg = `No login config for context '${tsContext}' — run: mesh login ${tsContext}`;
+                if (options.transport === 'tailscale') {
+                    logError(msg);
+                    process.exit(1);
+                }
+                const legacy = vpnConnected
+                    ? 'vpn-direct'
+                    : hasSessionManagerPlugin()
+                        ? 'ssm'
+                        : 'vpn-direct';
+                // Reachability-gate this legacy fallback too (MESH-2016): otherwise a
+                // machine with tailscaled (→ auto picks tailscale) but no mesh login
+                // config, with any tailnet up (vpnConnected), would land on an UNPROBED
+                // vpn-direct and reproduce the exact ECONNREFUSED this feature fixes.
+                const gatedLegacy = await gateVpnDirectReachability(legacy, devOutput);
+                logWarn(`${msg} — falling back to ${gatedLegacy} transport.`);
+                tunnelPlan = { transport: gatedLegacy };
+            }
+            else {
+                const prior = readTailscaleState(tsTenant);
+                const daemonUp = tailscaleDaemonState(tsTenant).backendState !== 'Down';
+                // Reuse the running daemon's real SOCKS port (daemon.json survives
+                // `down`); never mint a fresh one the daemon isn't listening on.
+                const socksPort = daemonUp
+                    ? (readTailscaleDaemonMeta(tsTenant)?.socksPort ?? prior?.socksPort ?? (await findFreePort()))
+                    : await findFreePort();
+                // Zero-touch VPN join (MESH-2099): try to mint a single-use pre-auth key
+                // from the platform's VpnJoinBroker so `tailscale up --authkey` joins
+                // silently. Any failure leaves preAuthKey undefined → the interactive
+                // browser-relay join (MESH-2098) is used instead.
+                let preAuthKey;
+                const brokerUrl = resolveVpnJoinBroker(tsContext);
+                if (brokerUrl) {
+                    const minted = await mintPreAuthKey(tsContext, brokerUrl, { getValidToken });
+                    if (minted?.authKey) {
+                        preAuthKey = minted.authKey;
+                    }
+                    else {
+                        logInfo('zero-touch VPN join unavailable, falling back to browser registration');
+                    }
+                }
+                tunnelPlan = {
+                    transport,
+                    explicit: options.transport === 'tailscale',
+                    tailscale: {
+                        tenant: tsTenant,
+                        env: tsEnv,
+                        region: awsRegion ?? 'us-east-2',
+                        loginServer,
+                        socksPort,
+                        preAuthKey,
+                    },
+                };
+            }
+        }
+        // Relaunch safety (MESH-2017): a relaunch recreates the worker onto current
+        // code. If the workflow source changed since this session started, warn before
+        // it replays in-flight conversations against it (require --force). Checked
+        // BEFORE startServices, which kills+recreates the session.
+        if (workflowChangeWouldStrand(loadSessionState(sessionName), appRoot, !!options.force)) {
+            process.exit(1);
+        }
+        // Start services. startServices handles tmux session creation, tunnel setup
+        // (SSM or Tailscale, per tunnelPlan), and service windows. It returns the
+        // final devOutput with tunnels rewritten to localhost ports.
+        const finalDevOutput = await startServices(sessionName, appRoot, devOutput, !!options.headless, childAwsEnv, tunnelPlan, worktree.worktreeRoot, worktree.taskQueueSuffix);
         // Persist session state so --status and restart see allocated ports
+        // and the final tunnel endpoints (localhost for SSM, VPC for VPN).
         saveSessionState(sessionName, {
             appRoot,
             stack,
-            devOutput,
+            devOutput: finalDevOutput,
             startedAt: new Date().toISOString(),
+            workflowFingerprint: fingerprintWorkflowSource(appRoot, finalDevOutput.services),
         });
-        // Start services
-        await startServices(sessionName, appRoot, devOutput, !!options.headless);
     });
     // Subcommand: logs
     dev
-        .command("logs <service>")
-        .description("Show logs for a service")
-        .option("--tail <lines>", "Number of lines", "100")
+        .command('logs <service>')
+        .description('Show logs for a service')
+        .option('--tail <lines>', 'Number of lines', '100')
         .action((service, opts) => {
         // --session is on the parent dev command
         const sessionName = dev.opts().session;
+        const resolvedSession = sessionName ?? `${getProjectName(findAppRoot())}-dev`;
+        if (loadSessionState(resolvedSession)?.runner === 'docker') {
+            console.log(dockerDevLogs(resolvedSession, service, parseInt(opts.tail, 10)));
+            return;
+        }
         if (sessionName) {
             showLogs(sessionName, service, parseInt(opts.tail, 10));
         }
@@ -1172,31 +2906,154 @@ export function registerDevCommand(program) {
     });
     // Subcommand: restart
     dev
-        .command("restart <service>")
-        .description("Restart a service")
-        .option("--stage <stage>", "Pulumi stack name")
-        .action((service, opts) => {
-        // --session is on the parent dev command
-        const parentSession = dev.opts().session;
+        .command('restart <service>')
+        .description('Restart a service')
+        .option('--stack <stack>', 'Pulumi stack name')
+        .addOption(new Option('--stage <stack>', 'Deprecated alias for --stack').hideHelp())
+        .option('--refresh-env', "Regenerate this service's env from current stack/SSM outputs before restarting (for config/deploy changes)")
+        .option('--force', 'Restart the worker even if workflow code changed since launch (may strand in-flight conversations)')
+        .action(async (service, opts) => {
+        // Hoisted so the catch can name the right login context (not a hardcoded
+        // one) even when a throw happens before cred resolution. MESH-2089.
+        let ctx = null;
+        try {
+            // --session is on the parent dev command
+            const parentSession = dev.opts().session;
+            const parentProfile = dev.opts().profile;
+            if (parentProfile) {
+                applyAwsProfileOverride(parentProfile);
+            }
+            const appRoot = findAppRoot();
+            const projectName = getProjectName(appRoot);
+            const sessionName = parentSession ?? `${projectName}-dev`;
+            const state = loadSessionState(sessionName);
+            if (state?.runner === 'docker') {
+                dockerDevRestart(sessionName, service);
+                logSuccess(`Restarted: ${service}`);
+                return;
+            }
+            // Relaunch safety (MESH-2017): restarting the WORKER onto changed workflow
+            // code strands in-flight conversations; restarting other services (ui/api)
+            // doesn't. Gate the worker restart on the workflow-source fingerprint.
+            if (/worker/i.test(service) && workflowChangeWouldStrand(state, appRoot, !!opts.force)) {
+                process.exit(1);
+            }
+            const stack = state?.stack ?? detectStack(appRoot, resolveStackOption(opts));
+            ctx = derivePlatformContext(appRoot, stack);
+            // Resolve credentials BEFORE reading any Pulumi/SSM/kubeconfig output
+            // (MESH-2090). With ambient AWS_* cleared (the documented restart
+            // hygiene), the parent-side AWS calls the restart path makes — the
+            // getDevOutput fallback below, and under --refresh-env the
+            // resolveTemporalAuthVars/ensureKubeconfig calls — read the default SDK
+            // chain (process.env). Resolving first lets us thread the resolved creds
+            // into this process's env, and lets the precise login preflight fire
+            // before the devOutput fallback (which was the MESH-2089 crash site).
+            const defaultDeployerRole = readStackConfig(appRoot, stack, 'mesh:deployerRole');
+            const adminDeployerRole = readStackConfig(appRoot, stack, 'mesh:adminDeployerRole');
+            let deployerRole = defaultDeployerRole;
+            if (defaultDeployerRole) {
+                const meshCreds = ctx ? readCredentials(ctx) : null;
+                const idToken = meshCreds && new Date(meshCreds.expiresAt) > new Date() ? meshCreds.idToken : null;
+                deployerRole = selectRoleForCaller(idToken, {
+                    defaultRole: defaultDeployerRole,
+                    adminRole: adminDeployerRole ?? undefined,
+                });
+            }
+            const resolved = deployerRole ? await resolveAwsCredentials(deployerRole, appRoot, stack) : null;
+            // Login preflight (MESH-2089): if a deployer role is configured but creds
+            // couldn't be resolved AND there are no ambient AWS creds to fall back on,
+            // the restart would proceed with no credentials and fail downstream. Name
+            // the real problem (e.g. "run mesh login <ctx> --device") instead.
+            if (deployerRole && !resolved && !process.env.AWS_ACCESS_KEY_ID) {
+                const pf = ctx ? credProbeToPreflightError(await probeCredentials(ctx, deployerRole), ctx) : null;
+                logError(pf?.message ??
+                    `Couldn't resolve AWS credentials to restart '${service}'. Run: mesh login ${ctx ?? 'mesh.dev'} --device`);
+                process.exit(1);
+            }
+            const baseAwsEnv = resolved?.env ?? getAwsEnvVars();
+            // Ensure AWS_REGION is set from stack config so parent-side SDK clients
+            // (SSM, EKS) don't default to us-east-1. Mirrors the launch path.
+            const awsRegion = readStackConfig(appRoot, stack, 'aws:region');
+            if (awsRegion && !baseAwsEnv.AWS_REGION) {
+                baseAwsEnv.AWS_REGION = awsRegion;
+            }
+            // Inject the resolved creds into THIS process's env so the parent-side
+            // AWS calls below run credentialed even when ambient AWS_* was cleared
+            // (MESH-2090). Mirrors the launch path's inject (see startServices).
+            Object.assign(process.env, baseAwsEnv);
+            const profileHint = parentProfile ?? process.env.AWS_PROFILE ?? 'mesh-dev';
+            const zitadelOpts = resolved?.method === 'zitadel' && deployerRole && ctx
+                ? {
+                    context: ctx,
+                    roleArn: deployerRole,
+                    sessionScratchDir: getSessionEnvDir(sessionName),
+                    meshBin: resolveStableMeshBin(process.argv[1]),
+                }
+                : undefined;
+            const awsEnv = buildChildAwsEnv(baseAwsEnv, resolved?.method ?? 'ambient', profileHint, zitadelOpts);
+            // Use persisted state (has allocated ports), fall back to raw Pulumi
+            // output — now credentialed via the resolved env (MESH-2090).
+            const devOutput = state?.devOutput ?? getDevOutput(appRoot, stack, baseAwsEnv);
+            await restartService(sessionName, service, appRoot, devOutput, awsEnv, {
+                refreshEnv: !!opts.refreshEnv,
+                stack,
+                sessionState: state,
+            });
+            // Re-baseline the workflow fingerprint after a worker restart (MESH-2017):
+            // the worker now runs the current code, so a subsequent unchanged restart
+            // must NOT nag — otherwise a good-citizen `--force` earns a session of
+            // false warnings, training the reflex this guard exists to prevent.
+            if (/worker/i.test(service) && state) {
+                saveSessionState(sessionName, {
+                    ...state,
+                    workflowFingerprint: fingerprintWorkflowSource(appRoot, state.devOutput?.services),
+                });
+            }
+        }
+        catch (err) {
+            // Never crash uncaught (MESH-2089): a cred/kubeconfig/tmux failure should
+            // name itself, not dump a bare Node stack. The underlying error is logged
+            // so the exact cause is pinned if this recurs.
+            logError(`Failed to restart '${service}': ${err?.message ?? String(err)}`);
+            logInfo(`If this is a credential/kubeconfig issue, run \`mesh login ${ctx ?? '<your platform context>'} --device\`, ` +
+                'or `mesh dev` to relaunch the session cleanly.');
+            process.exit(1);
+        }
+    });
+    // Subcommand: doctor — diagnose the dev session
+    dev
+        .command('doctor')
+        .description('Diagnose the dev session (creds, tunnels, config, ports, worktree, Temporal) — names the fix')
+        .option('--stack <stack>', 'Pulumi stack name')
+        .addOption(new Option('--stage <stack>', 'Deprecated alias for --stack').hideHelp())
+        .option('--json', 'Machine-readable output')
+        .action(async (opts) => {
+        const parentProfile = dev.opts().profile;
+        if (parentProfile) {
+            applyAwsProfileOverride(parentProfile);
+        }
         const appRoot = findAppRoot();
         const projectName = getProjectName(appRoot);
-        const sessionName = parentSession ?? `${projectName}-dev`;
-        // Use persisted state (has allocated ports), fall back to raw Pulumi output
+        const sessionName = dev.opts().session ?? `${projectName}-dev`;
         const state = loadSessionState(sessionName);
-        const devOutput = state?.devOutput ??
-            getDevOutput(appRoot, detectStack(appRoot, opts.stage));
-        restartService(sessionName, service, appRoot, devOutput);
+        const stack = state?.stack ?? detectStack(appRoot, resolveStackOption(opts));
+        // `--json` may land on either the subcommand or the parent `dev`
+        // command (both declare it), so honor both.
+        const asJson = !!opts.json || !!dev.opts().json;
+        const ctx = buildDoctorContext(appRoot, stack, sessionName);
+        const status = await runDoctor(ctx, { json: asJson });
+        process.exit(status === 'error' ? 1 : 0);
     });
     // Subcommand: list — discover apps in the monorepo
     dev
-        .command("list")
-        .description("List Pulumi apps in the monorepo")
+        .command('list')
+        .description('List Pulumi apps in the monorepo')
         .action(() => {
         // --json is on the parent dev command
         const asJson = dev.opts().json;
         const mono = findMonorepoRoot();
         if (!mono) {
-            logError("Could not find monorepo root (pnpm-workspace.yaml or .git)");
+            logError('Could not find monorepo root (pnpm-workspace.yaml or .git)');
             process.exit(1);
         }
         const apps = discoverApps(mono);
@@ -1214,35 +3071,105 @@ export function registerDevCommand(program) {
         }
         else {
             if (apps.length === 0) {
-                logInfo("No Pulumi apps found.");
+                logInfo('No Pulumi apps found.');
                 return;
             }
-            console.log("Apps in monorepo:");
-            console.log("");
+            console.log('Apps in monorepo:');
+            console.log('');
             for (const app of apps) {
                 const sessionName = `${app.name}-dev`;
                 const running = sessionExists(sessionName);
-                const icon = running ? "●" : "○";
-                const stacks = app.stacks.length > 0
-                    ? ` (${app.stacks.join(", ")})`
-                    : "";
+                const icon = running ? '●' : '○';
+                const stacks = app.stacks.length > 0 ? ` (${app.stacks.join(', ')})` : '';
                 console.log(`  ${icon} ${app.name.padEnd(24)} ${app.tenant.padEnd(12)} ${app.relativePath}${stacks}`);
             }
-            console.log("");
+            console.log('');
         }
     });
-    // Hidden subcommand: tunnel manager (started internally by mesh dev)
+    // Subcommand: test-user — retrieve Temporal test user credentials
     dev
-        .command("__tunnel-manager")
-        .description("Internal: manage all tunnels in a single process")
-        .option("--config <path>", "Path to tunnel config JSON")
-        .option("--tmux-session <name>", "tmux session name for status display")
-        .action((opts) => {
-        if (!opts.config) {
-            logError("--config is required");
-            process.exit(1);
+        .command('test-user [name]')
+        .description('Get Temporal test user credentials (from Pulumi-managed test users)')
+        .option('--tenant <tenant>', 'Tenant name', 'mesh')
+        .option('--env <env>', 'Environment', 'dev')
+        .option('--region <region>', 'AWS region', 'us-east-2')
+        .action(async (name, opts) => {
+        const { SSMClient, GetParameterCommand, GetParametersByPathCommand } = await import('@aws-sdk/client-ssm');
+        const ssm = new SSMClient({ region: opts.region });
+        const basePath = `/mesh-platform/${opts.tenant}/${opts.env}/temporal/test-users`;
+        if (!name) {
+            // List all test users
+            try {
+                const resp = await ssm.send(new GetParametersByPathCommand({
+                    Path: basePath,
+                    Recursive: true,
+                    WithDecryption: true,
+                }));
+                if (!resp.Parameters || resp.Parameters.length === 0) {
+                    logWarn(`No test users found at ${basePath}`);
+                    logInfo('Test users are defined in Pulumi config under mesh:temporal.authorization.testUsers');
+                    logInfo("They're only available on dev stacks.");
+                    return;
+                }
+                console.log('Temporal test users:');
+                console.log('');
+                for (const param of resp.Parameters) {
+                    const userName = param.Name.split('/').pop();
+                    const creds = JSON.parse(param.Value);
+                    console.log(`  ${userName}`);
+                    console.log(`    Email:    ${creds.email}`);
+                    console.log(`    Password: ${creds.password}`);
+                    console.log(`    Roles:    ${creds.roles.join(', ')}`);
+                    if (creds.description)
+                        console.log(`    Note:     ${creds.description}`);
+                    console.log('');
+                }
+                logInfo('Login at: https://temporal.dev.mesh-platform.trabian.com');
+            }
+            catch (err) {
+                logError(`Failed to list test users: ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            }
+        }
+        else {
+            // Get a specific test user
+            try {
+                const resp = await ssm.send(new GetParameterCommand({
+                    Name: `${basePath}/${name}`,
+                    WithDecryption: true,
+                }));
+                if (!resp.Parameter?.Value) {
+                    logError(`Test user '${name}' not found at ${basePath}/${name}`);
+                    return;
+                }
+                const creds = JSON.parse(resp.Parameter.Value);
+                // Check if --json is set on parent
+                const asJson = dev.opts().json;
+                if (asJson) {
+                    console.log(JSON.stringify(creds, null, 2));
+                }
+                else {
+                    console.log(`Email:    ${creds.email}`);
+                    console.log(`Password: ${creds.password}`);
+                    console.log(`Roles:    ${creds.roles.join(', ')}`);
+                    if (creds.description)
+                        console.log(`Note:     ${creds.description}`);
+                    console.log('');
+                    logInfo('Login at: https://temporal.dev.mesh-platform.trabian.com');
+                }
+            }
+            catch (err) {
+                const msg = err.message ?? String(err);
+                if (msg.includes('ParameterNotFound') || err.name === 'ParameterNotFound') {
+                    logError(`Test user '${name}' not found.`);
+                    logInfo(`List available users with: mesh dev test-user`);
+                }
+                else {
+                    logError(`Failed to get test user: ${msg}`);
+                }
+                process.exit(1);
+            }
         }
-        runTunnelManager(opts.config, opts.tmuxSession);
     });
 }
 //# sourceMappingURL=dev.js.map