@mesh-tech/mesh-cli 0.39.0 → 0.40.0

package/dist/src/commands/dev.js

@@ -1,7 +1,7 @@
 import { execFileSync, spawn, spawnSync } from 'child_process';
+import { createHash } from 'crypto';
 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';
@@ -16,7 +16,7 @@ import { ensureKubeconfig, resolveHubPlatformName, sessionKubeconfigPath, } from
 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 { buildLaunchCommand, envFileName, getSessionEnvDir, pickLaunchHostEnv, waitForPort, writeEnvFile, parseEnvFile, diffEnvFiles, readServiceOverrides, serviceOverridesPaths, } from './dev-launch.js';
 import { buildLocalDevOutput, detectLocalTenant, ensureLocalPlatformRunning, hasStackBacking, localAppNamespace } from './local/dev-local.js';
 import { ensureAppTenantAuth, ensureSignInApp, registerLocalApp } from './local/auth-provision.js';
 import { publishLocalAppAuthz, readLocalAuthzConfig } from './local/app-authz.js';
@@ -32,8 +32,10 @@ import { writeDevCompose, dockerDevUp, dockerDevDown, dockerDevPs, dockerDevLogs
 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 { ALL_CHECKS, aggregateStatus, classifyPaneLiveness, classifySessionServices, describePaneExit, paneProcessQuery, renderHuman, runChecks, runDoctor, } from './dev-doctor.js';
+import { awaitServiceReadiness, paneTail, parseWaitSeconds, portHeldByAnother, RESTART_READY_TIMEOUT_MS, TEMPORAL_WORKER_RUNNING, } from './dev-readiness.js';
 import { resolveWorktreeIdentity, withAppScopedPortBlock, blockBasePort, PORT_BLOCK_SERVICE_SUBRANGE, } from '../utils/worktree-identity.js';
+import { devSessionsRoot } from '../utils/dev-sessions-root.js';
 export function registerServiceProbes(devOutput, tenant, probeFiles) {
     const services = {};
     for (const [name, service] of Object.entries(devOutput.services)) {
@@ -58,6 +60,9 @@ export function registerServiceProbes(devOutput, tenant, probeFiles) {
 function deriveSessionName(projectName, wt) {
     return wt.isPrimary ? `${projectName}-dev` : `${projectName}-${wt.slug}`;
 }
+function sessionNameFor(appRoot, explicit) {
+    return explicit ?? deriveSessionName(getProjectName(appRoot), resolveWorktreeIdentity(appRoot));
+}
 function printDevPlan(sessionName, appRoot, wt, devOutput) {
     const kind = wt.isPrimary ? 'primary checkout' : `linked worktree (block ${wt.portBlock})`;
     console.log(`\nmesh dev plan — ${kind}\n`);
@@ -89,9 +94,7 @@ function printDevPlan(sessionName, appRoot, wt, devOutput) {
     console.log('');
 }
 function getSessionStatePath(sessionName) {
-    const dir = path.join(os.tmpdir(), 'mesh-dev-sessions');
-    if (!fs.existsSync(dir))
-        fs.mkdirSync(dir, { recursive: true });
+    const dir = devSessionsRoot();
     return path.join(dir, `${sessionName}.json`);
 }
 function saveSessionState(sessionName, state) {
@@ -121,8 +124,9 @@ function workflowChangeWouldStrand(priorState, appRoot, force) {
     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.');
+        '  Keep it replay-compatible: gate the change with wf.patched() and commit a frozen\n' +
+        '  taken/not-taken fixture pair for the gate (the temporal-replay skill\'s patch rule;\n' +
+        '  never regenerate an existing golden), or accept the risk.');
     if (force) {
         logWarn('  Proceeding anyway (--force).');
         return false;
@@ -130,9 +134,6 @@ function workflowChangeWouldStrand(priorState, appRoot, force) {
     logError('  Refusing to restart the worker. Re-run with --force once the change is replay-safe.');
     return true;
 }
-function getSessionEnvDir(sessionName) {
-    return path.join(os.tmpdir(), 'mesh-dev-sessions', sessionName);
-}
 function getServiceEnvFilePath(sessionName, serviceName) {
     return path.join(getSessionEnvDir(sessionName), envFileName(serviceName));
 }
@@ -146,6 +147,51 @@ function removeSessionState(sessionName) {
     }
     catch { }
 }
+function getSessionPortMemoryPath(sessionName) {
+    return path.join(path.dirname(getSessionStatePath(sessionName)), `${sessionName}.ports.json`);
+}
+function loadSessionPortMemory(sessionName) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(getSessionPortMemoryPath(sessionName), 'utf-8'));
+        return rememberedPortsOf(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function sessionPortPlan(sessionName) {
+    const remembered = loadSessionPortMemory(sessionName);
+    const ownPorts = new Set();
+    if (sessionExists(sessionName)) {
+        const running = loadSessionState(sessionName)?.devOutput?.services ?? {};
+        for (const [name, port] of Object.entries(remembered)) {
+            if (running[name]?.port === port)
+                ownPorts.add(port);
+        }
+    }
+    return { remembered, ownPorts };
+}
+export function rememberedPortsOf(memory) {
+    const out = {};
+    for (const [name, port] of Object.entries(memory?.services ?? {})) {
+        if (Number.isInteger(port) && port > 0)
+            out[name] = port;
+    }
+    return out;
+}
+function saveSessionPortMemory(sessionName, devOutput) {
+    const services = {};
+    for (const [name, svc] of Object.entries(devOutput.services)) {
+        if (svc.port > 0 && svc.command && svc.command.length > 0)
+            services[name] = svc.port;
+    }
+    const memory = { services, savedAt: new Date().toISOString() };
+    try {
+        fs.writeFileSync(getSessionPortMemoryPath(sessionName), JSON.stringify(memory, null, 2));
+    }
+    catch {
+    }
+}
 export async function isPortFree(port) {
     const bindSucceeds = (host) => new Promise((resolve) => {
         const server = net.createServer();
@@ -195,7 +241,7 @@ export function rewriteOwnServicePort(service, oldPort, newPort) {
         }
     }
 }
-async function allocatePorts(devOutput, worktree) {
+export async function allocatePorts(devOutput, worktree, remembered = {}, probes = { isPortFree, findFreePort }, ownPorts = new Set()) {
     const allocated = JSON.parse(JSON.stringify(devOutput));
     const usedPorts = new Set();
     const portRemaps = new Map();
@@ -207,27 +253,42 @@ async function allocatePorts(devOutput, worktree) {
         if (!service.command || service.command.length === 0)
             continue;
         const preferred = service.port;
+        const last = remembered[name];
+        const lastIsUsable = async () => last !== undefined &&
+            last !== preferred &&
+            !usedPorts.has(last) &&
+            (ownPorts.has(last) || (await probes.isPortFree(last)));
         let target = -1;
         if (worktree.isPrimary) {
-            if (!usedPorts.has(preferred) && (await isPortFree(preferred))) {
+            if (!usedPorts.has(preferred) && (await probes.isPortFree(preferred))) {
                 target = preferred;
             }
+            else if (await lastIsUsable()) {
+                target = last;
+                logInfo(`Port ${preferred} busy for service '${name}', reusing last launch's ${target}`);
+            }
             else {
-                target = await findFreePort();
+                target = await probes.findFreePort();
                 logWarn(`Port ${preferred} busy for service '${name}', using ${target}`);
             }
         }
+        else if (await lastIsUsable()) {
+            target = last;
+        }
         else {
+            if (last !== undefined && last !== preferred) {
+                logWarn(`Port ${last} (this session's last launch) is not available for service '${name}'; allocating another`);
+            }
             for (let i = blockCursor; i < PORT_BLOCK_SERVICE_SUBRANGE; i++) {
                 const candidate = blockBase + i;
-                if (!usedPorts.has(candidate) && (await isPortFree(candidate))) {
+                if (!usedPorts.has(candidate) && (await probes.isPortFree(candidate))) {
                     target = candidate;
                     blockCursor = i + 1;
                     break;
                 }
             }
             if (target < 0) {
-                target = await findFreePort();
+                target = await probes.findFreePort();
                 logWarn(`Worktree port block exhausted for '${name}', using ${target}`);
             }
         }
@@ -268,12 +329,15 @@ export function mergePinnedPorts(fresh, pinned) {
             continue;
         const freshPort = mergedSvc.port;
         mergedSvc.port = pinnedSvc.port;
+        if (typeof freshPort === 'number' && freshPort > 0) {
+            rewriteOwnServicePort(mergedSvc, freshPort, pinnedSvc.port);
+            if (freshPort !== pinnedSvc.port) {
+                portRemaps.set(freshPort, 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);
-        }
     }
     rewriteCrossServicePorts(merged, portRemaps);
     rewriteClusterHostsToLocal(merged);
@@ -469,6 +533,95 @@ function getDevOutput(appRoot, stack, awsEnv) {
         throw new MissingStackOutputError(stack, err);
     }
 }
+function gitCommitOfDir(dir) {
+    const run = (...args) => execFileSync('git', ['-C', dir, ...args], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 2000,
+    }).trim();
+    try {
+        const commit = run('rev-parse', '--short=12', 'HEAD');
+        if (!commit)
+            return null;
+        const dirty = run('status', '--porcelain').length > 0;
+        return dirty ? `${commit}-dirty` : commit;
+    }
+    catch {
+        return null;
+    }
+}
+export function worktreeDigestOfDir(dir) {
+    const run = (cwd, ...args) => execFileSync('git', ['-C', cwd, ...args], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 10_000,
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    try {
+        const top = run(dir, 'rev-parse', '--show-toplevel').toString().trim();
+        if (!top)
+            return null;
+        const diff = run(top, 'diff', 'HEAD', '--no-color', '--no-ext-diff');
+        const untracked = run(top, 'ls-files', '--others', '--exclude-standard', '-z')
+            .toString()
+            .split('\0')
+            .filter((f) => f.length > 0)
+            .sort();
+        if (diff.length === 0 && untracked.length === 0)
+            return null;
+        const hash = createHash('sha256').update(diff);
+        for (const file of untracked) {
+            hash.update('\0').update(file).update('\0');
+            try {
+                hash.update(fs.readFileSync(path.join(top, file)));
+            }
+            catch {
+            }
+        }
+        return hash.digest('hex').slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+export function currentProgramProvenance(appRoot, stack) {
+    let configSha256 = null;
+    try {
+        configSha256 = createHash('sha256')
+            .update(fs.readFileSync(path.join(appRoot, `Pulumi.${stack}.yaml`)))
+            .digest('hex');
+    }
+    catch {
+    }
+    const gitCommit = gitCommitOfDir(appRoot);
+    const worktreeDigest = gitCommit?.endsWith('-dirty') ? worktreeDigestOfDir(appRoot) : null;
+    return { gitCommit, configSha256, worktreeDigest };
+}
+export function devOutputStaleness(recorded, current) {
+    const reasons = [];
+    if (recorded?.gitCommit && current.gitCommit && recorded.gitCommit !== current.gitCommit) {
+        reasons.push(`program is at ${current.gitCommit} but the outputs were deployed from ${recorded.gitCommit}`);
+    }
+    else if (recorded?.gitCommit &&
+        current.gitCommit &&
+        recorded.worktreeDigest &&
+        current.worktreeDigest &&
+        recorded.worktreeDigest !== current.worktreeDigest) {
+        reasons.push(`program is at ${current.gitCommit} with different uncommitted changes than the outputs were deployed from`);
+    }
+    if (recorded?.configSha256 &&
+        current.configSha256 &&
+        recorded.configSha256 !== current.configSha256) {
+        reasons.push('the stack config (Pulumi.<stack>.yaml) changed since the deploy');
+    }
+    return reasons;
+}
+function warnIfDevOutputStale(devOutput, appRoot, stack) {
+    const reasons = devOutputStaleness(devOutput.provenance, currentProgramProvenance(appRoot, stack));
+    if (reasons.length === 0)
+        return;
+    logWarn(`Stack outputs are older than the program (${reasons.join('; ')}); ` +
+        `run \`mesh deploy up --stack ${stack}\` to refresh the dev env.`);
+}
 function hasTmux() {
     try {
         execFileSync('which', ['tmux'], { stdio: 'ignore' });
@@ -620,37 +773,43 @@ export function rebaseServiceSrc(src, monorepoRoot) {
     return fs.existsSync(rebased) ? rebased : src;
 }
 export function isLinkedDependencyDir(serviceDir, appRoot) {
-    let pkgRoot = null;
-    let name = '';
-    for (let dir = serviceDir;; dir = path.dirname(dir)) {
+    const pkg = enclosingPackage(serviceDir);
+    return Boolean(pkg && appResolvedPackageDir(pkg.name, appRoot) === pkg.root);
+}
+function enclosingPackage(dir) {
+    for (let at = dir;; at = path.dirname(at)) {
         try {
-            const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
-            if (typeof manifest?.name === 'string' && manifest.name) {
-                pkgRoot = dir;
-                name = manifest.name;
-                break;
-            }
+            const manifest = JSON.parse(fs.readFileSync(path.join(at, 'package.json'), 'utf8'));
+            if (typeof manifest?.name === 'string' && manifest.name)
+                return { root: at, name: manifest.name };
         }
         catch {
         }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
+        if (path.dirname(at) === at)
+            return null;
     }
-    if (!pkgRoot)
-        return false;
+}
+function appResolvedPackageDir(name, appRoot) {
     for (let dir = appRoot;; dir = path.dirname(dir)) {
         try {
-            if (fs.realpathSync(path.join(dir, 'node_modules', name)) === pkgRoot)
-                return true;
+            return fs.realpathSync(path.join(dir, 'node_modules', name));
         }
         catch {
         }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            return false;
+        if (path.dirname(dir) === dir)
+            return null;
     }
 }
+export function relinkedServiceDir(serviceDir, appRoot) {
+    const pkg = enclosingPackage(serviceDir);
+    if (!pkg)
+        return null;
+    const own = appResolvedPackageDir(pkg.name, appRoot);
+    if (!own || own === pkg.root)
+        return null;
+    const candidate = path.join(own, path.relative(pkg.root, serviceDir));
+    return fs.existsSync(candidate) ? candidate : null;
+}
 export function monorepoRelativeSrc(src) {
     if (!path.isAbsolute(src))
         return src.replace(/^\.\//, '') || '.';
@@ -668,32 +827,57 @@ function getServiceEnvVars(service, tunnels) {
             if (spec.tunnel) {
                 const tunnel = tunnels[spec.tunnel];
                 if (tunnel) {
-                    try {
-                        const url = new URL(value);
-                        if (url.hostname) {
-                            url.hostname = tunnel.host;
-                            url.port = String(tunnel.port);
-                            value = url.toString();
-                        }
-                        else {
-                            value = `${tunnel.host}:${tunnel.port}`;
-                        }
-                    }
-                    catch {
-                        value = `${tunnel.host}:${tunnel.port}`;
-                    }
+                    value = pointAtTunnel(key, value, tunnel);
+                    const portKey = portSiblingOf(key);
+                    if (portKey && service.env[portKey])
+                        result[portKey] = String(tunnel.port);
                 }
             }
-            result[key] = value;
+            if (!(key in result))
+                result[key] = value;
         }
     }
     return result;
 }
+export function portSiblingOf(key) {
+    return key.endsWith('_HOST') ? `${key.slice(0, -'_HOST'.length)}_PORT` : undefined;
+}
+export function pointAtTunnel(key, value, tunnel) {
+    try {
+        const url = new URL(value);
+        if (url.hostname) {
+            url.hostname = tunnel.host;
+            url.port = String(tunnel.port);
+            return url.toString();
+        }
+    }
+    catch {
+    }
+    if (key.endsWith('_HOST') && !value.includes(':'))
+        return tunnel.host;
+    return `${tunnel.host}:${tunnel.port}`;
+}
 function setTmuxEnv(sessionName, vars) {
     for (const [key, value] of Object.entries(vars)) {
         execFileSync('tmux', ['set-environment', '-t', sessionName, key, value], { stdio: 'ignore' });
     }
 }
+function readTmuxSessionEnv(sessionName, keys) {
+    const out = {};
+    for (const key of keys) {
+        try {
+            const line = execFileSync('tmux', ['show-environment', '-t', sessionName, key], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (line.startsWith(`${key}=`))
+                out[key] = line.slice(key.length + 1);
+        }
+        catch {
+        }
+    }
+    return out;
+}
 function envPrefix(vars) {
     const entries = Object.entries(vars);
     if (entries.length === 0)
@@ -706,7 +890,34 @@ function shellEscape(s) {
         return s;
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
-async function resolveSecrets(secrets) {
+export function tunnelForSecret(secretName, tunnels) {
+    return tunnels[secretName] ?? (secretName === 'database' ? tunnels['db'] : undefined);
+}
+export function pointSecretUrlsAtTunnel(values, tunnel) {
+    if (!tunnel)
+        return values;
+    const out = {};
+    for (const [key, value] of Object.entries(values)) {
+        let rewritten = value;
+        try {
+            const url = new URL(value);
+            if (url.hostname) {
+                url.hostname = tunnel.host === 'localhost' ? '127.0.0.1' : tunnel.host;
+                url.port = String(tunnel.port);
+                if (/^postgres(ql)?:$/.test(url.protocol) && !url.searchParams.has('sslmode')) {
+                    url.searchParams.set('sslmode', 'no-verify');
+                    url.searchParams.set('sslaccept', 'accept_invalid_certs');
+                }
+                rewritten = url.toString();
+            }
+        }
+        catch {
+        }
+        out[key] = rewritten;
+    }
+    return out;
+}
+async function resolveSecrets(secrets, tunnels) {
     const client = new SecretsManagerClient({});
     const resolved = {};
     for (const [name, secret] of Object.entries(secrets)) {
@@ -715,12 +926,14 @@ async function resolveSecrets(secrets) {
             if (!response.SecretString)
                 continue;
             const values = JSON.parse(response.SecretString);
+            const mapped = {};
             for (const [secretKey, envVar] of Object.entries(secret.envMapping)) {
                 const value = values[secretKey];
                 if (value === undefined)
                     continue;
-                resolved[envVar] = value;
+                mapped[envVar] = value;
             }
+            Object.assign(resolved, pointSecretUrlsAtTunnel(mapped, tunnelForSecret(name, tunnels)));
             logSuccess(`Secret resolved: ${name} (${secret.secretName})`);
         }
         catch (err) {
@@ -729,8 +942,12 @@ async function resolveSecrets(secrets) {
     }
     return resolved;
 }
-function resolveTemporalEncodingKey(tenant, env, appName) {
-    const namespace = `${tenant}-${env}-${appName}`;
+export function stackNamespace(devOutput) {
+    const tenant = devOutput.platform?.tenant ?? 'mesh';
+    const stack = devOutput.stack ?? devOutput.platform?.env ?? 'dev';
+    return devOutput.app ? `${tenant}-${stack}-${devOutput.app}` : undefined;
+}
+function resolveTemporalEncodingKey(namespace) {
     const secretName = `${namespace}-temporal-encoding-key`;
     try {
         const b64 = execFileSync('kubectl', [
@@ -772,12 +989,15 @@ async function resolveTemporalAuthVars(sessionName, devOutput) {
     let temporalAuthVars = {};
     if (devOutput.tunnels['temporal']) {
         temporalAuthVars = await resolveTemporalAuth(tenant, platformEnv, devOutput.platform?.name ?? tenant);
-        const appName = devOutput.app ?? '';
-        if (appName) {
-            const encodingKey = resolveTemporalEncodingKey(tenant, platformEnv, appName);
+        const namespace = stackNamespace(devOutput);
+        if (namespace) {
+            const encodingKey = resolveTemporalEncodingKey(namespace);
             if (encodingKey) {
                 temporalAuthVars.TEMPORAL_ENCODING_KEY = encodingKey;
             }
+            else {
+                logInfo(`No deployed encoding key in ${namespace} — using the stack's dev key from the dev block.`);
+            }
         }
         const temporalTunnel = devOutput.tunnels['temporal'];
         temporalAuthVars.TEMPORAL_ADDRESS = tunnelClientAddress(temporalTunnel);
@@ -943,7 +1163,22 @@ function hasSessionManagerPlugin() {
         return false;
     }
 }
-async function startSsmTunnels(sessionName, devOutput) {
+const TUNNEL_TO_BASTION_KEY = {
+    temporal: 'temporal-frontend',
+    'temporal-ui': 'temporal-ui',
+    rds: 'rds',
+    db: 'rds',
+    database: 'rds',
+};
+export function bastionServiceForTunnel(tunnelName, tunnel, services) {
+    for (const key of [TUNNEL_TO_BASTION_KEY[tunnelName], tunnelName]) {
+        if (key && services[key])
+            return { key, endpoint: services[key] };
+    }
+    const byEndpoint = Object.entries(services).find(([, svc]) => svc.host === tunnel.host && svc.port === tunnel.port);
+    return byEndpoint ? { key: byEndpoint[0], endpoint: byEndpoint[1] } : undefined;
+}
+async function startSsmTunnels(sessionName, devOutput, appRoot, awsEnv) {
     const platformEnv = devOutput.platform?.env ?? 'dev';
     const bastionTenant = devOutput.platform?.name ?? 'mesh';
     const bastion = await getPlatformBastionInfo(bastionTenant, platformEnv).catch(() => null);
@@ -960,13 +1195,6 @@ async function startSsmTunnels(sessionName, devOutput) {
         return rewritten;
     }
     logInfo(`Starting ${tunnelCount} SSM tunnel(s) via bastion ${bastion.instanceId}...`);
-    const tunnelToBastionKey = {
-        temporal: 'temporal-frontend',
-        'temporal-ui': 'temporal-ui',
-        rds: 'rds',
-        db: 'rds',
-        database: 'rds',
-    };
     const OPTIONAL_TUNNEL_NAMES = new Set([
         'loki',
         'prometheus',
@@ -978,9 +1206,10 @@ async function startSsmTunnels(sessionName, devOutput) {
     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];
+    for (const [tunnelName, tunnel] of Object.entries(devOutput.tunnels)) {
+        const matched = bastionServiceForTunnel(tunnelName, tunnel, bastion.services);
+        const bastionKey = matched?.key ?? tunnelName;
+        const endpoint = matched?.endpoint;
         if (!endpoint) {
             if (OPTIONAL_TUNNEL_NAMES.has(tunnelName)) {
                 skippedOptional.push(`${tunnelName} (bastion key: ${bastionKey})`);
@@ -1012,6 +1241,7 @@ async function startSsmTunnels(sessionName, devOutput) {
         logInfo('Connect VPN instead or deploy/update PlatformBastion with the missing service endpoints.');
         throw new Error('SSM tunnel fallback unavailable: missing bastion endpoints');
     }
+    const hostEnv = pickLaunchHostEnv(process.env);
     for (const { tunnelName, endpoint, localPort } of plannedTunnels) {
         const windowName = `tunnel-${tunnelName}`;
         const ssmCmd = [
@@ -1031,7 +1261,15 @@ async function startSsmTunnels(sessionName, devOutput) {
         ].join(' ');
         execFileSync('tmux', ['new-window', '-t', sessionName, '-n', windowName]);
         execFileSync('tmux', ['set-option', '-t', `${sessionName}:${windowName}`, 'remain-on-exit', 'on'], { stdio: 'ignore' });
-        execFileSync('tmux', ['send-keys', '-t', `${sessionName}:${windowName}`, ssmCmd, 'Enter']);
+        const envFilePath = getServiceEnvFilePath(sessionName, windowName);
+        writeEnvFile(envFilePath, { ...hostEnv, ...awsEnv });
+        execFileSync('tmux', [
+            'send-keys',
+            '-t',
+            `${sessionName}:${windowName}`,
+            buildLaunchCommand(envFilePath, appRoot, ssmCmd, undefined, hostEnv),
+            'Enter',
+        ]);
         rewritten.tunnels[tunnelName] = {
             host: 'localhost',
             port: localPort,
@@ -1213,7 +1451,13 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     }
     logInfo(`Creating tmux session: ${sessionName}`);
     execFileSync('tmux', ['new-session', '-d', '-s', sessionName, '-n', 'status', '-c', appRoot]);
-    setTmuxEnv(sessionName, awsEnv);
+    const sessionEnv = {};
+    const shareOnSession = (vars) => {
+        Object.assign(sessionEnv, vars);
+        setTmuxEnv(sessionName, vars);
+    };
+    const hostEnv = pickLaunchHostEnv(process.env);
+    shareOnSession(awsEnv);
     const hasTunnels = Object.keys(devOutput.tunnels).length > 0;
     let effectiveTransport = tunnelPlan.transport;
     if (hasTunnels && effectiveTransport === 'tailscale' && tunnelPlan.tailscale) {
@@ -1241,7 +1485,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         }
     }
     if (hasTunnels && effectiveTransport === 'ssm') {
-        devOutput = await startSsmTunnels(sessionName, devOutput);
+        devOutput = await startSsmTunnels(sessionName, devOutput, appRoot, awsEnv);
     }
     if (hasTunnels && effectiveTransport !== 'vpn-direct') {
         for (const [tName, tunnel] of Object.entries(devOutput.tunnels)) {
@@ -1274,7 +1518,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     }
     let secretEnvVars = {};
     if (devOutput.secrets && Object.keys(devOutput.secrets).length > 0) {
-        secretEnvVars = await resolveSecrets(devOutput.secrets);
+        secretEnvVars = await resolveSecrets(devOutput.secrets, devOutput.tunnels);
     }
     const tenant = devOutput.platform?.tenant ?? 'mesh';
     const platformEnv = devOutput.platform?.env ?? 'dev';
@@ -1286,7 +1530,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         });
         if (kubeconfigPath) {
             process.env.KUBECONFIG = kubeconfigPath;
-            setTmuxEnv(sessionName, { KUBECONFIG: kubeconfigPath });
+            shareOnSession({ KUBECONFIG: kubeconfigPath });
             logSuccess(`Kubeconfig resolved from SSM (hub ${platformName}/${platformEnv}) → ${kubeconfigPath}`);
         }
         else {
@@ -1296,18 +1540,21 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     let temporalAuthVars = {};
     if (devOutput.tunnels['temporal']) {
         temporalAuthVars = await resolveTemporalAuth(tenant, platformEnv, devOutput.platform?.name ?? tenant);
-        const appName = devOutput.app ?? '';
-        if (appName) {
-            const encodingKey = resolveTemporalEncodingKey(tenant, platformEnv, appName);
+        const namespace = stackNamespace(devOutput);
+        if (namespace) {
+            const encodingKey = resolveTemporalEncodingKey(namespace);
             if (encodingKey) {
                 temporalAuthVars.TEMPORAL_ENCODING_KEY = encodingKey;
             }
+            else {
+                logInfo(`No deployed encoding key in ${namespace} — using the stack's dev key from the dev block.`);
+            }
         }
         const temporalTunnel = devOutput.tunnels['temporal'];
         temporalAuthVars.TEMPORAL_ADDRESS = tunnelClientAddress(temporalTunnel);
     }
-    setTmuxEnv(sessionName, secretEnvVars);
-    setTmuxEnv(sessionName, temporalAuthVars);
+    shareOnSession(secretEnvVars);
+    shareOnSession(temporalAuthVars);
     const credContext = devOutput.platform
         ? isLocalPlatform
             ? 'local'
@@ -1315,18 +1562,20 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         : null;
     const devUserVars = resolveDevUserVars(devOutput);
     if (Object.keys(devUserVars).length > 0) {
-        setTmuxEnv(sessionName, devUserVars);
+        shareOnSession(devUserVars);
         logSuccess(`Dev user injected from mesh login: ${credContext}`);
         const tokenPort = await findFreePort();
         const tokenUrl = `http://127.0.0.1:${tokenPort}`;
-        setTmuxEnv(sessionName, { DEV_USER_TOKEN_URL: tokenUrl });
+        shareOnSession({ 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' });
+        const tokenServerEnvFile = getServiceEnvFilePath(sessionName, 'token-server');
+        writeEnvFile(tokenServerEnvFile, hostEnv);
         execFileSync('tmux', [
             'send-keys',
             '-t',
             `${sessionName}:token-server`,
-            `npx mesh dev __token-server ${tokenPort} ${credContext}`,
+            buildLaunchCommand(tokenServerEnvFile, appRoot, `npx mesh dev __token-server ${tokenPort} ${credContext}`, undefined, hostEnv),
             'Enter',
         ]);
         for (let i = 0; i < 15 && !(await isPortListening(tokenPort)); i++) {
@@ -1340,13 +1589,14 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         logInfo('  Hub UI will show unauthenticated state without valid credentials.');
     }
     const monorepoRoot = findMonorepoRoot();
+    const notLaunched = [];
     for (const [name, service] of Object.entries(devOutput.services)) {
         const cmd = service.command.join(' ');
         if (!cmd) {
             logInfo(`Skipped: ${name} (no dev command, deployed to K8s)`);
             continue;
         }
-        const serviceDir = path.resolve(appRoot, rebaseServiceSrc(service.src, monorepoRoot));
+        let serviceDir = path.resolve(appRoot, rebaseServiceSrc(service.src, monorepoRoot));
         if (worktreeRoot && fs.existsSync(serviceDir)) {
             const wtRootWithSep = worktreeRoot.endsWith(path.sep) ? worktreeRoot : worktreeRoot + path.sep;
             const outside = serviceDir !== worktreeRoot && !serviceDir.startsWith(wtRootWithSep);
@@ -1354,11 +1604,20 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
                 logInfo(`${name}: source is a dev-linked package (${serviceDir})`);
             }
             else if (outside) {
-                logError(`Refusing to launch '${name}': its source resolved to ${serviceDir}, ` +
-                    `outside this worktree (${worktreeRoot}), and it is not a package this ` +
-                    `app resolves there. The stack was likely deployed from another ` +
-                    `worktree. Re-run \`mesh deploy up\` here, or pass --app.`);
-                process.exit(1);
+                const own = relinkedServiceDir(serviceDir, appRoot);
+                if (own) {
+                    logWarn(`${name}: the stack recorded its source in another copy of its package ` +
+                        `(${serviceDir}); running this app's own copy (${own}).`);
+                    serviceDir = own;
+                }
+                else {
+                    logError(`Not launching '${name}': its source resolved to ${serviceDir}, ` +
+                        `outside this worktree (${worktreeRoot}), and it is not a package this ` +
+                        `app resolves. The stack was likely deployed from another worktree; ` +
+                        `re-run \`mesh deploy up\` here, or pass --app. Every other service still starts.`);
+                    notLaunched.push(name);
+                    continue;
+                }
             }
         }
         if (!fs.existsSync(serviceDir)) {
@@ -1367,15 +1626,21 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
             continue;
         }
         const serviceVars = {
+            ...hostEnv,
             ...getServiceEnvVars(service, devOutput.tunnels),
+            ...secretEnvVars,
             ...temporalAuthVars,
             ...devUserVars,
             ...(taskQueueSuffix ? { MESH_TASK_QUEUE_SUFFIX: taskQueueSuffix } : {}),
             ...awsEnv,
+            ...sessionEnv,
         };
         const envFilePath = getServiceEnvFilePath(sessionName, name);
-        writeEnvFile(envFilePath, serviceVars);
-        const launchCmd = buildLaunchCommand(envFilePath, serviceDir, cmd, service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : undefined);
+        const overrides = readServiceOverrides(sessionName, name);
+        if (Object.keys(overrides).length)
+            logInfo(`${name}: applying ${Object.keys(overrides).length} override(s) from ${serviceOverridesPaths(sessionName, name).join(' / ')}`);
+        writeEnvFile(envFilePath, { ...serviceVars, ...overrides });
+        const launchCmd = buildLaunchCommand(envFilePath, serviceDir, cmd, service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : undefined, hostEnv);
         execFileSync('tmux', ['new-window', '-t', sessionName, '-n', name, '-c', serviceDir]);
         execFileSync('tmux', ['set-option', '-t', `${sessionName}:${name}`, 'remain-on-exit', 'on'], {
             stdio: 'ignore',
@@ -1395,6 +1660,9 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     execFileSync('tmux', ['send-keys', '-t', `${sessionName}:status`, statusCmd, 'Enter']);
     console.log('');
     logSuccess(`Dev session started: ${sessionName}`);
+    if (notLaunched.length > 0)
+        logWarn(`Not launched (source outside this worktree, see above): ${notLaunched.join(', ')}. ` +
+            `The rest of the session is up.`);
     console.log('');
     if (tunnelNames.length > 0) {
         console.log('Connections (VPN direct):');
@@ -1453,29 +1721,22 @@ async function showStatus(sessionName, devOutput, asJson) {
         }
         return;
     }
-    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';
-    }
+    const liveness = classifySessionServices(sessionName, devOutput.services, paneProcessQuery);
     const tunnelNames = Object.keys(devOutput.tunnels);
     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)) {
+            const l = liveness.get(name);
             services[name] = {
-                status: windowStatus[name] ?? 'unknown',
+                status: l?.state ?? 'unknown',
                 port: svc.port,
                 src: svc.src,
+                ...(l?.state === 'exited' && l.exitCode !== null ? { exitCode: l.exitCode } : {}),
+                ...(l?.state === 'exited' && l.lastActivityEpoch !== null
+                    ? { lastActivity: new Date(l.lastActivityEpoch * 1000).toISOString() }
+                    : {}),
             };
         }
         const tunnels = {};
@@ -1505,10 +1766,16 @@ async function showStatus(sessionName, devOutput, asJson) {
                 console.log(`  ☁ ${name.padEnd(16)} deployed                ${svc.src}`);
                 continue;
             }
-            const status = windowStatus[name] ?? 'unknown';
+            const l = liveness.get(name);
+            const status = l?.state ?? 'unknown';
             const icon = status === 'running' ? '●' : status === 'exited' ? '✗' : '?';
+            const statusCol = l?.state === 'exited' && l.exitCode !== null ? `exited(${l.exitCode})` : status;
             const addr = svc.port ? `:${svc.port}` : '';
-            console.log(`  ${icon} ${name.padEnd(16)} ${status.padEnd(10)} ${addr.padEnd(8)} ${svc.src}`);
+            let line = `  ${icon} ${name.padEnd(16)} ${statusCol.padEnd(10)} ${addr.padEnd(8)} ${svc.src}`;
+            if (l?.state === 'exited' && l.lastActivityEpoch !== null) {
+                line += `  (last output ${new Date(l.lastActivityEpoch * 1000).toLocaleTimeString()})`;
+            }
+            console.log(line);
         }
         console.log('');
         console.log('Commands:');
@@ -1530,10 +1797,15 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
         logError(`No active session: ${sessionName}. Run 'mesh dev' first.`);
         process.exit(1);
     }
-    if (opts?.refreshEnv) {
+    const waitMs = opts?.waitMs ?? RESTART_READY_TIMEOUT_MS;
+    const neverLaunched = !fs.existsSync(getServiceEnvFilePath(sessionName, serviceName));
+    if (neverLaunched && !opts?.refreshEnv && opts?.stack)
+        logInfo(`'${serviceName}' has no launch env file (never started) — rendering it from the stack.`);
+    const refreshEnv = opts?.refreshEnv || (neverLaunched && Boolean(opts?.stack));
+    if (refreshEnv && opts) {
         if (!opts.stack) {
             logError('--refresh-env: no stack resolved; keeping existing env and NOT restarting.');
-            return;
+            return null;
         }
         const pinned = opts.sessionState?.devOutput ?? devOutput;
         let fresh;
@@ -1543,24 +1815,52 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
         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;
+            return null;
         }
+        warnIfDevOutputStale(fresh, appRoot, opts.stack);
         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;
+            return null;
         }
         const temporalAuthVars = await resolveTemporalAuthVars(sessionName, merged);
+        const secretEnvVars = merged.secrets && Object.keys(merged.secrets).length > 0
+            ? await resolveSecrets(merged.secrets, merged.tunnels)
+            : {};
         const { taskQueueSuffix } = resolveWorktreeIdentity(appRoot);
         const serviceVars = {
+            ...pickLaunchHostEnv(process.env),
             ...getServiceEnvVars(mergedService, merged.tunnels),
+            ...secretEnvVars,
             ...temporalAuthVars,
             ...resolveDevUserVars(merged),
             ...(taskQueueSuffix ? { MESH_TASK_QUEUE_SUFFIX: taskQueueSuffix } : {}),
             ...awsEnv,
+            ...readTmuxSessionEnv(sessionName, ['KUBECONFIG', 'DEV_USER_TOKEN_URL']),
         };
-        writeEnvFile(getServiceEnvFilePath(sessionName, serviceName), serviceVars);
+        const envFilePathToRefresh = getServiceEnvFilePath(sessionName, serviceName);
+        let previousVars = null;
+        try {
+            previousVars = parseEnvFile(fs.readFileSync(envFilePathToRefresh, 'utf-8'));
+        }
+        catch {
+        }
+        if (previousVars) {
+            const changes = diffEnvFiles(previousVars, { ...serviceVars, ...readServiceOverrides(sessionName, serviceName) });
+            if (changes.length === 0) {
+                logInfo(`--refresh-env: the regenerated env for '${serviceName}' is identical to the running one.`);
+            }
+            else {
+                logInfo(`--refresh-env: '${serviceName}' env changes (${changes.length}):`);
+                for (const change of changes)
+                    console.log(`    ${change.detail}`);
+            }
+        }
+        const overrides = readServiceOverrides(sessionName, serviceName);
+        if (Object.keys(overrides).length)
+            logInfo(`'${serviceName}': applying ${Object.keys(overrides).length} override(s).`);
+        writeEnvFile(envFilePathToRefresh, { ...serviceVars, ...overrides });
         service = mergedService;
         logSuccess(`Regenerated env for '${serviceName}' from current stack/SSM outputs.`);
     }
@@ -1569,16 +1869,40 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
         execFileSync('tmux', ['respawn-pane', '-k', '-t', target], { stdio: 'ignore' });
     }
     catch {
-        logError(`Window '${serviceName}' not found in session.`);
-        process.exit(1);
+        try {
+            execFileSync('tmux', ['new-window', '-d', '-t', sessionName, '-n', serviceName], { stdio: 'ignore' });
+            logInfo(`Window '${serviceName}' did not exist — created it.`);
+        }
+        catch {
+            logError(`Window '${serviceName}' not found in session, and could not be created.`);
+            process.exit(1);
+        }
+    }
+    try {
+        execFileSync('tmux', ['clear-history', '-t', target], { stdio: 'ignore' });
+    }
+    catch {
+    }
+    const portHeldBeforeStart = waitMs > 0 &&
+        (await portHeldByAnother(service.port, {
+            portAccepts: isPortListening,
+            now: () => Date.now(),
+            sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        }));
+    if (portHeldBeforeStart) {
+        logWarn(`Port :${service.port} is still accepting connections with '${serviceName}' stopped — another process holds it. ` +
+            `The restarted service cannot bind it; whatever answers on :${service.port} is not this session's ${serviceName}.`);
+        logInfo(`Find the holder: lsof -nP -iTCP:${service.port} -sTCP:LISTEN`);
     }
     setTmuxEnv(sessionName, awsEnv);
     const cmd = service.command.join(' ');
     const envFilePath = getServiceEnvFilePath(sessionName, serviceName);
     let restartCmd;
     if (fs.existsSync(envFilePath)) {
-        const serviceDir = path.resolve(appRoot, rebaseServiceSrc(service.src, findMonorepoRoot()));
-        restartCmd = buildLaunchCommand(envFilePath, serviceDir, cmd, service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : undefined);
+        let serviceDir = path.resolve(appRoot, rebaseServiceSrc(service.src, findMonorepoRoot()));
+        if (!isLinkedDependencyDir(serviceDir, appRoot))
+            serviceDir = relinkedServiceDir(serviceDir, appRoot) ?? serviceDir;
+        restartCmd = buildLaunchCommand(envFilePath, serviceDir, cmd, service.env?.OTEL_RESOURCE_ATTRIBUTES ? logShipperPath() : undefined, pickLaunchHostEnv(process.env));
     }
     else {
         logWarn(`No launch env file for '${serviceName}' (${envFilePath}) — session predates env-file launches.`);
@@ -1587,7 +1911,78 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
         restartCmd = `${envPrefix(serviceVars)}${cmd}`;
     }
     execFileSync('tmux', ['send-keys', '-t', target, restartCmd, 'Enter']);
-    logSuccess(`Restarted: ${serviceName}`);
+    if (waitMs <= 0) {
+        logSuccess(`Restarted: ${serviceName} (not waiting for readiness — check \`mesh dev --status\`)`);
+        return null;
+    }
+    const readiness = await awaitServiceReadiness({
+        port: service.port,
+        portHeldBeforeStart,
+        readyMarker: service.port > 0 ? undefined : TEMPORAL_WORKER_RUNNING,
+        timeoutMs: waitMs,
+    }, {
+        liveness: () => classifyPaneLiveness(target, paneProcessQuery),
+        portAccepts: isPortListening,
+        paneOutput: () => capturePane(target),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    reportRestartReadiness(serviceName, service.port, readiness);
+    return readiness;
+}
+function capturePane(target, lines = 2000) {
+    try {
+        return execFileSync('tmux', ['capture-pane', '-p', '-t', target, '-S', `-${lines}`], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return '';
+    }
+}
+function reportRestartReadiness(serviceName, port, readiness) {
+    const secs = (ms) => `${(ms / 1000).toFixed(1)}s`;
+    switch (readiness.state) {
+        case 'ready': {
+            const how = readiness.via === 'port'
+                ? `listening on :${port}`
+                : readiness.via === 'marker'
+                    ? 'worker RUNNING'
+                    : 'process up';
+            logSuccess(`Restarted: ${serviceName} (${how} after ${secs(readiness.afterMs)})`);
+            return;
+        }
+        case 'exited': {
+            logError(`Restart FAILED: '${serviceName}' ${describePaneExit(readiness.liveness)} ${secs(readiness.afterMs)} after its command was typed.`);
+            const tail = paneTail(readiness.output);
+            if (tail.length > 0) {
+                logInfo(`Last output from '${serviceName}':`);
+                for (const line of tail)
+                    console.log(`    ${line}`);
+            }
+            logInfo(`Full output: mesh dev logs ${serviceName}`);
+            return;
+        }
+        case 'pending': {
+            const what = port > 0 ? `:${port} is not accepting connections` : 'no ready marker printed';
+            logWarn(`Restarted: ${serviceName}, but readiness is UNCONFIRMED — ${what} after ${secs(readiness.afterMs)} (process still up).`);
+            logInfo(`Watch it: mesh dev logs ${serviceName}   ·   mesh dev --status`);
+            return;
+        }
+        case 'port-held': {
+            logError(`Restart NOT confirmed: '${serviceName}' is up ${secs(readiness.afterMs)} after its command was typed, but :${port} was already held by another process — ` +
+                'it either failed to bind and is exiting, or moved to a port nothing dials.');
+            const tail = paneTail(readiness.output, 8);
+            for (const line of tail)
+                console.log(`    ${line}`);
+            logInfo(`Free :${port} (lsof -nP -iTCP:${port} -sTCP:LISTEN) and restart again, or relaunch: mesh dev --kill && mesh dev`);
+            return;
+        }
+        case 'unknown':
+            logWarn(`Restarted: ${serviceName}, but readiness could not be checked (${readiness.reason}).`);
+            return;
+    }
 }
 function showLogs(sessionName, serviceName, tail) {
     if (!sessionExists(sessionName)) {
@@ -1634,7 +2029,7 @@ function buildDoctorContext(appRoot, stack, sessionName) {
 export function registerDevCommand(program) {
     const dev = program
         .command('dev')
-        .description('Start local dev environment (reads Pulumi stack outputs)')
+        .description('Start local dev environment (reads Pulumi stack outputs). The env is rendered from the stack\'s STORED outputs — when they are older than the program (git HEAD) or the stack config, mesh dev warns to run `mesh deploy up --stack <stack>` first')
         .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())
@@ -1809,7 +2204,8 @@ export function registerDevCommand(program) {
                 mocks: selectedMocks,
             });
             if (options.dryRun) {
-                printDevPlan(sessionName, appRoot, worktree, await allocatePorts(rawDevOutput, worktree));
+                const plan = sessionPortPlan(sessionName);
+                printDevPlan(sessionName, appRoot, worktree, await allocatePorts(rawDevOutput, worktree, plan.remembered, undefined, plan.ownPorts));
                 for (const [name, decl] of Object.entries(selectedMocks)) {
                     const mode = externalMode(name, decl);
                     if (mode === 'local') {
@@ -1890,7 +2286,8 @@ export function registerDevCommand(program) {
                         ` — the Hub cannot author its roles, and a policy-engine app denies every check.`);
                 }
             }
-            const devOutput = await allocatePorts(rawDevOutput, worktree);
+            const plan = sessionPortPlan(sessionName);
+            const devOutput = await allocatePorts(rawDevOutput, worktree, plan.remembered, undefined, plan.ownPorts);
             for (const service of signInServices) {
                 const port = devOutput.services[service]?.port;
                 if (!port) {
@@ -2097,6 +2494,7 @@ export function registerDevCommand(program) {
                     externalProbeFiles,
                     ...(localDocs ? { localDocs } : {}),
                 });
+                saveSessionPortMemory(sessionName, devOutput);
                 console.log('');
                 logSuccess(`Dev session started (docker): ${sessionName}`);
                 console.log('');
@@ -2117,10 +2515,12 @@ export function registerDevCommand(program) {
                 devOutput: finalDevOutput,
                 startedAt: new Date().toISOString(),
                 runner: 'tmux',
+                cleanEnv: true,
                 composeExternals,
                 externalProbeFiles,
                 ...(localDocs ? { localDocs } : {}),
             });
+            saveSessionPortMemory(sessionName, finalDevOutput);
             return;
         }
         if (options.mock || options.externals) {
@@ -2270,7 +2670,9 @@ export function registerDevCommand(program) {
             await showStatus(sessionName, state?.devOutput ?? rawDevOutput, !!options.json);
             return;
         }
-        const devOutput = await allocatePorts(rawDevOutput, worktree);
+        warnIfDevOutputStale(rawDevOutput, appRoot, stack);
+        const plan = sessionPortPlan(sessionName);
+        const devOutput = await allocatePorts(rawDevOutput, worktree, plan.remembered, undefined, plan.ownPorts);
         transport = await gateVpnDirectReachability(transport, devOutput);
         if (options.dryRun) {
             printDevPlan(sessionName, appRoot, worktree, devOutput);
@@ -2337,28 +2739,22 @@ export function registerDevCommand(program) {
             stack,
             devOutput: finalDevOutput,
             startedAt: new Date().toISOString(),
+            cleanEnv: true,
             workflowFingerprint: fingerprintWorkflowSource(appRoot, finalDevOutput.services),
         });
+        saveSessionPortMemory(sessionName, finalDevOutput);
     });
     dev
         .command('logs <service>')
         .description('Show logs for a service')
         .option('--tail <lines>', 'Number of lines', '100')
         .action((service, opts) => {
-        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)));
+        const sessionName = sessionNameFor(findAppRoot(), dev.opts().session);
+        if (loadSessionState(sessionName)?.runner === 'docker') {
+            console.log(dockerDevLogs(sessionName, service, parseInt(opts.tail, 10)));
             return;
         }
-        if (sessionName) {
-            showLogs(sessionName, service, parseInt(opts.tail, 10));
-        }
-        else {
-            const appRoot = findAppRoot();
-            const projectName = getProjectName(appRoot);
-            showLogs(`${projectName}-dev`, service, parseInt(opts.tail, 10));
-        }
+        showLogs(sessionName, service, parseInt(opts.tail, 10));
     });
     dev
         .command('restart <service>')
@@ -2367,6 +2763,8 @@ export function registerDevCommand(program) {
         .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)')
+        .option('--wait <seconds>', 'How long to wait for the service to prove ready (port accepting, or a Temporal worker RUNNING) before reporting; an exit in that window fails the restart', String(RESTART_READY_TIMEOUT_MS / 1000))
+        .option('--no-wait', 'Return as soon as the command is typed, without checking readiness')
         .action(async (service, opts) => {
         let ctx = null;
         try {
@@ -2376,8 +2774,7 @@ export function registerDevCommand(program) {
                 applyAwsProfileOverride(parentProfile);
             }
             const appRoot = findAppRoot();
-            const projectName = getProjectName(appRoot);
-            const sessionName = parentSession ?? `${projectName}-dev`;
+            const sessionName = sessionNameFor(appRoot, parentSession);
             const state = loadSessionState(sessionName);
             if (state?.runner === 'docker') {
                 dockerDevRestart(sessionName, service);
@@ -2426,10 +2823,11 @@ export function registerDevCommand(program) {
                 : undefined;
             const awsEnv = buildChildAwsEnv(baseAwsEnv, resolved?.method ?? 'ambient', profileHint, zitadelOpts);
             const devOutput = state?.devOutput ?? getDevOutput(appRoot, stack, baseAwsEnv);
-            await restartService(sessionName, service, appRoot, devOutput, awsEnv, {
+            const readiness = await restartService(sessionName, service, appRoot, devOutput, awsEnv, {
                 refreshEnv: !!opts.refreshEnv,
                 stack,
                 sessionState: state,
+                waitMs: parseWaitSeconds(opts.wait, RESTART_READY_TIMEOUT_MS / 1000) * 1000,
             });
             if (/worker/i.test(service) && state) {
                 saveSessionState(sessionName, {
@@ -2437,6 +2835,8 @@ export function registerDevCommand(program) {
                     workflowFingerprint: fingerprintWorkflowSource(appRoot, state.devOutput?.services),
                 });
             }
+            if (readiness?.state === 'exited' || readiness?.state === 'port-held')
+                process.exit(1);
         }
         catch (err) {
             logError(`Failed to restart '${service}': ${err?.message ?? String(err)}`);
@@ -2447,7 +2847,7 @@ export function registerDevCommand(program) {
     });
     dev
         .command('doctor')
-        .description('Diagnose the dev session (creds, tunnels, config, ports, worktree, Temporal) — names the fix')
+        .description('Diagnose the dev session (creds, registry, config, ports, service processes, worktree, tunnels, 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')
@@ -2457,8 +2857,7 @@ export function registerDevCommand(program) {
             applyAwsProfileOverride(parentProfile);
         }
         const appRoot = findAppRoot();
-        const projectName = getProjectName(appRoot);
-        const sessionName = dev.opts().session ?? `${projectName}-dev`;
+        const sessionName = sessionNameFor(appRoot, dev.opts().session);
         const state = loadSessionState(sessionName);
         const stack = state?.stack ?? detectStack(appRoot, resolveStackOption(opts));
         const asJson = !!opts.json || !!dev.opts().json;