@mesh-tech/mesh-cli 0.20.1 → 0.20.3

package/dist/src/commands/dev.js

@@ -1,18 +1,3 @@
-/**
- * mesh dev — Pulumi-output-driven local development orchestrator
- *
- * 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
- *   mesh dev --headless       Start without attaching
- *   mesh dev --kill           Stop everything
- *   mesh dev --status         Show service health (--json for structured)
- *   mesh dev logs <service>   Tail a service's output
- *   mesh dev restart <svc>    Restart a single service
- */
 import { execFileSync, spawn, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as net from 'net';
@@ -44,16 +29,6 @@ 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';
-/**
- * The app's own services, as blackbox probe targets, so local uptime is real.
- *
- * Mock stand-ins are excluded: `--externals` already registers each of those
- * under its own external-service labels, and probing them twice would show one
- * dependency as two rows — one of which disappears when the mock does.
- *
- * Best-effort. A probe file is monitoring, not the app: failing to write one
- * must never take down a dev session that is otherwise working.
- */
 export function registerServiceProbes(devOutput, tenant, probeFiles) {
     const services = {};
     for (const [name, service] of Object.entries(devOutput.services)) {
@@ -75,20 +50,9 @@ export function registerServiceProbes(devOutput, tenant, probeFiles) {
         logWarn(`Could not register uptime probes for this session (${err instanceof Error ? err.message : err}) — the Hub will show no uptime for these services.`);
     }
 }
-/**
- * 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`);
@@ -139,16 +103,6 @@ function loadSessionState(sessionName) {
         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;
 }
@@ -171,11 +125,6 @@ function workflowChangeWouldStrand(priorState, appRoot, force) {
     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);
 }
@@ -192,28 +141,6 @@ function removeSessionState(sessionName) {
     }
     catch { }
 }
-/**
- * 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.
- */
 export async function isPortFree(port) {
     const bindSucceeds = (host) => new Promise((resolve) => {
         const server = net.createServer();
@@ -224,14 +151,10 @@ export async function isPortFree(port) {
         else
             server.listen(port, host, onListening);
     });
-    // 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.
- */
 async function findFreePort() {
     return new Promise((resolve, reject) => {
         const server = net.createServer();
@@ -242,7 +165,6 @@ async function findFreePort() {
         });
     });
 }
-/** 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();
@@ -261,16 +183,6 @@ function isPortListening(port) {
         s.connect(port, '127.0.0.1');
     });
 }
-/**
- * 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)
- */
 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)) {
@@ -278,30 +190,15 @@ export function rewriteOwnServicePort(service, oldPort, newPort) {
         }
     }
 }
-/**
- * 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
+    let blockCursor = 0;
     for (const [name, service] of Object.entries(allocated.services)) {
         if (service.port <= 0)
             continue;
-        // 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;
@@ -316,7 +213,6 @@ async function allocatePorts(devOutput, worktree) {
             }
         }
         else {
-            // 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))) {
@@ -326,36 +222,21 @@ async function allocatePorts(devOutput, worktree) {
                 }
             }
             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).
     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;
@@ -371,42 +252,10 @@ function rewriteCrossServicePorts(devOutput, portRemaps) {
         }
     }
 }
-/**
- * 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];
@@ -421,35 +270,18 @@ export function mergePinnedPorts(fresh, pinned) {
             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
-// ============================================================================
-/**
- * Find the monorepo root by walking up from cwd looking for the root
- * package.json (has "workspaces" or the well-known repo markers).
- */
 function findMonorepoRoot() {
     let dir = process.cwd();
     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'))) {
             return dir;
         }
-        // .git as fallback — but only if it's a directory (not a worktree file)
         const gitPath = path.join(dir, '.git');
         if (fs.existsSync(gitPath)) {
             return dir;
@@ -458,15 +290,8 @@ function findMonorepoRoot() {
     }
     return null;
 }
-/**
- * Discover Pulumi apps in the monorepo.
- * Scans:
- *   {tenants,tests/tenants}/<tenant>/apps/<app>/Pulumi.yaml
- *   apps/<app>/Pulumi.yaml (flat layout, tenant from stack config)
- */
 function discoverApps(monorepoRoot) {
     const apps = [];
-    // Helper: extract stacks and add an app entry
     function addApp(appDir, tenant) {
         const projectName = getProjectName(appDir);
         const stacks = fs
@@ -481,7 +306,6 @@ function discoverApps(monorepoRoot) {
             stacks,
         });
     }
-    // 1. Tenant-scoped: {tenants,tests/tenants}/<tenant>/apps/<app>/
     const searchDirs = ['tenants', 'tests/tenants'];
     for (const searchDir of searchDirs) {
         const base = path.join(monorepoRoot, searchDir);
@@ -499,7 +323,6 @@ function discoverApps(monorepoRoot) {
             }
         }
     }
-    // 2. Flat layout: apps/<app>/ (tenant read from first stack config)
     const flatAppsDir = path.join(monorepoRoot, 'apps');
     if (fs.existsSync(flatAppsDir) && fs.statSync(flatAppsDir).isDirectory()) {
         for (const app of fs.readdirSync(flatAppsDir)) {
@@ -508,7 +331,6 @@ function discoverApps(monorepoRoot) {
                 continue;
             if (!fs.existsSync(path.join(appDir, 'Pulumi.yaml')))
                 continue;
-            // Read tenant from first stack config's mesh:tenant
             let tenant = 'unknown';
             const stackConfigs = fs
                 .readdirSync(appDir)
@@ -527,16 +349,11 @@ function discoverApps(monorepoRoot) {
     }
     return apps;
 }
-/**
- * Find the Pulumi app root by walking up from cwd looking for Pulumi.yaml.
- */
 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')))
             return resolved;
-        // Try relative to monorepo root
         const mono = findMonorepoRoot();
         if (mono) {
             const fromMono = path.resolve(mono, appPath);
@@ -556,9 +373,6 @@ function findAppRoot(appPath) {
     }
     return process.cwd();
 }
-/**
- * Read the Pulumi project name from Pulumi.yaml.
- */
 function getProjectName(appRoot) {
     const yamlPath = path.join(appRoot, 'Pulumi.yaml');
     if (!fs.existsSync(yamlPath))
@@ -567,13 +381,6 @@ function getProjectName(appRoot) {
     const match = content.match(/^name:\s*(.+)$/m);
     return match?.[1]?.trim() ?? path.basename(appRoot);
 }
-/**
- * Detect the current Pulumi stack from:
- *   1. --stage flag
- *   2. MESH_STAGE env var
- *   3. `pulumi stack --show-name` (currently-selected stack)
- *   4. Pulumi.<stack>.yaml files in the app root (if exactly one, use it)
- */
 function detectStack(appRoot, stageArg) {
     if (stageArg)
         return stageArg;
@@ -589,9 +396,7 @@ function detectStack(appRoot, stageArg) {
             return result;
     }
     catch {
-        // Fall through
     }
-    // Infer from Pulumi.<stack>.yaml config files
     try {
         const files = fs
             .readdirSync(appRoot)
@@ -605,17 +410,10 @@ function detectStack(appRoot, stageArg) {
         }
     }
     catch {
-        // Fall through
     }
     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,
@@ -626,9 +424,7 @@ function stackArgs(appRoot, stack) {
             return [];
     }
     catch {
-        // ignore
     }
-    // Try selecting the stack first (works with short names), then omit --stack
     try {
         execFileSync('pulumi', ['stack', 'select', stack], {
             cwd: appRoot,
@@ -638,22 +434,9 @@ function stackArgs(appRoot, stack) {
         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`.
- */
-/**
- * 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) {
@@ -664,7 +447,6 @@ class MissingStackOutputError extends Error {
 }
 function getDevOutput(appRoot, stack, awsEnv) {
     const sa = stackArgs(appRoot, stack);
-    // Try new format: export const app = env.register() → { dev: { ... } }
     try {
         const result = pulumiStackOutput(appRoot, 'app', sa, awsEnv);
         const appOutput = JSON.parse(result);
@@ -673,25 +455,15 @@ function getDevOutput(appRoot, stack, awsEnv) {
         }
     }
     catch {
-        // Fall through to legacy format
     }
-    // Legacy format: export const dev = ...
     try {
         const result = pulumiStackOutput(appRoot, 'dev', sa, awsEnv);
         return JSON.parse(result);
     }
     catch (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);
     }
 }
-// ============================================================================
-// tmux helpers
-// ============================================================================
 function hasTmux() {
     try {
         execFileSync('which', ['tmux'], { stdio: 'ignore' });
@@ -732,9 +504,6 @@ function applyAwsProfileOverride(profile) {
         delete process.env[key];
     }
 }
-/**
- * Collect AWS credentials from the current environment.
- */
 function getAwsEnvVars() {
     const result = {};
     const vars = [
@@ -752,28 +521,6 @@ function getAwsEnvVars() {
     }
     return result;
 }
-/**
- * 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)
@@ -784,8 +531,6 @@ export function buildChildAwsEnv(awsEnv, method, profile, opts) {
         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}`;
@@ -799,12 +544,6 @@ export function buildChildAwsEnv(awsEnv, method, profile, opts) {
             region,
             meshBin: opts.meshBin,
         });
-        // UPSERT a managed section; never rewrite the file. This file has a second
-        // writer — `mesh login --export` (the worker-start recipe evals it) — and
-        // the AWS SDK reads it ONCE per process, so a wholesale write here deletes
-        // that profile under a running worker, which then fails every LLM call until
-        // it is restarted. The key carries "(mesh dev)" so the two writers own two
-        // sections rather than replacing each other's.
         const existing = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
         const next = upsertManagedAwsConfigSection(stripBareProfile(existing, profileName), `${opts.context} (mesh dev)`, profileBlock);
         if (next !== existing)
@@ -826,20 +565,6 @@ export function buildChildAwsEnv(awsEnv, method, profile, opts) {
     }
     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;
@@ -849,32 +574,7 @@ function rebaseServiceSrc(src, monorepoRoot) {
     const rebased = path.join(monorepoRoot, rel);
     return fs.existsSync(rebased) ? rebased : src;
 }
-/**
- * Is `serviceDir` a package this app DEV-LINKED, rather than a stale sibling
- * worktree?
- *
- * Both look identical to the wrong-worktree guard — a source directory outside
- * the app's worktree — but only one is a mistake. A module that contributes a
- * dev service (`InfraContribution.devServices`) reports `resolvePackageRoot()`,
- * which is the package's REAL path; when that package is dev-linked from another
- * repo it legitimately lives there. Refusing it means a devService can run only
- * while its package is published — i.e. never while you are developing it, which
- * is the only time you need it.
- *
- * The test is proof, not a heuristic: read the directory's own package name and
- * ask whether THIS app resolves that name to THIS directory. A stale sibling
- * worktree cannot satisfy that — nothing in the app's `node_modules` points at
- * it — so the wrong-worktree guard keeps its teeth.
- *
- * @example
- * isLinkedDependencyDir("/repo/libs/infra-components/src/components/ai/redis", "/repo/apps/demo");
- * // → true when the app resolves @mesh-tech/infra-components to that directory
- */
 export function isLinkedDependencyDir(serviceDir, appRoot) {
-    // The service source is often INSIDE a package rather than its root — a redis
-    // component ships as `<infra-components>/src/components/ai/redis`. So find the
-    // enclosing package first (nearest ancestor with a named manifest), then ask
-    // whether the app resolves THAT name to THAT directory.
     let pkgRoot = null;
     let name = '';
     for (let dir = serviceDir;; dir = path.dirname(dir)) {
@@ -887,7 +587,6 @@ export function isLinkedDependencyDir(serviceDir, appRoot) {
             }
         }
         catch {
-            /* no manifest here; keep walking up */
         }
         const parent = path.dirname(dir);
         if (parent === dir)
@@ -895,44 +594,27 @@ export function isLinkedDependencyDir(serviceDir, appRoot) {
     }
     if (!pkgRoot)
         return false;
-    // Resolve from the app outward, so a package linked for a DIFFERENT app in the
-    // same repo does not vouch for this one.
     for (let dir = appRoot;; dir = path.dirname(dir)) {
         try {
             if (fs.realpathSync(path.join(dir, 'node_modules', name)) === pkgRoot)
                 return true;
         }
         catch {
-            /* not resolvable here; keep walking up */
         }
         const parent = path.dirname(dir);
         if (parent === dir)
             return false;
     }
 }
-/**
- * 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 = {};
     if (service.env) {
@@ -941,7 +623,6 @@ function getServiceEnvVars(service, tunnels) {
             if (spec.tunnel) {
                 const tunnel = tunnels[spec.tunnel];
                 if (tunnel) {
-                    // Rewrite to VPC endpoint (VPN provides direct access)
                     try {
                         const url = new URL(value);
                         if (url.hostname) {
@@ -963,24 +644,11 @@ function getServiceEnvVars(service, tunnels) {
     }
     return result;
 }
-/**
- * Set env vars on a tmux session. New windows inherit them.
- *
- * Use for truly shared vars (AWS creds, secrets). For per-service
- * vars like PORT, use envPrefix() instead to avoid cross-service leaks.
- */
 function setTmuxEnv(sessionName, vars) {
     for (const [key, value] of Object.entries(vars)) {
         execFileSync('tmux', ['set-environment', '-t', sessionName, key, value], { stdio: 'ignore' });
     }
 }
-/**
- * Build an `env K=V …` prefix string for per-service env vars.
- *
- * This scopes variables to the process instead of polluting the
- * tmux session environment (where the last service's PORT would
- * leak to every other service on restart).
- */
 function envPrefix(vars) {
     const entries = Object.entries(vars);
     if (entries.length === 0)
@@ -988,21 +656,11 @@ function envPrefix(vars) {
     const parts = entries.map(([k, v]) => `${k}=${shellEscape(v)}`);
     return `env ${parts.join(' ')} `;
 }
-/** Escape a value for shell interpolation. */
 function shellEscape(s) {
-    // If the value is safe, return as-is
     if (/^[a-zA-Z0-9_./:@=+,-]+$/.test(s))
         return s;
-    // Otherwise single-quote it, escaping any embedded single quotes
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
-// ============================================================================
-// Secret resolution
-// ============================================================================
-/**
- * Resolve secrets from Secrets Manager and return env var key→value pairs.
- * VPN provides direct access — no URL rewriting needed.
- */
 async function resolveSecrets(secrets) {
     const client = new SecretsManagerClient({});
     const resolved = {};
@@ -1026,16 +684,6 @@ async function resolveSecrets(secrets) {
     }
     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`;
@@ -1056,23 +704,12 @@ function resolveTemporalEncodingKey(tenant, env, appName) {
         }
     }
     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)}`),
@@ -1082,25 +719,13 @@ async function resolveTemporalAuthVars(sessionName, devOutput) {
         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) {
@@ -1114,43 +739,6 @@ async function resolveTemporalAuthVars(sessionName, devOutput) {
     }
     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.
- */
-/**
- * The `mesh login` context that issues this app's dev-user identity.
- *
- * It is the PLATFORM's name and env — `trabian.dev`, `mesh.dev` — because the
- * platform owns the Zitadel the app's services verify against, so a token from
- * any other issuer is well-formed and rejected. Not every app runs on the `mesh`
- * platform: a shared tenant on the `trabian` platform whose dev user came from
- * `identity.dev.mesh-platform.trabian.com` would be verified against
- * `identity.dev.trabian.meshtech.io`.
- *
- * That failure is invisible at injection time and only surfaces at the far end
- * of a cross-app call, as `Missing or invalid Authorization header — expected
- * Bearer token`: the token is well-formed and unexpired, just from the wrong
- * issuer.
- *
- * `name` is optional on the dev output, so fall back to `mesh`, which keeps
- * mesh-platform apps on the context they already use.
- */
 function loginContextFor(platform) {
     return `${platform.name ?? 'mesh'}.${platform.env}`;
 }
@@ -1174,54 +762,18 @@ function resolveDevUserVars(devOutput) {
             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 [];
@@ -1240,32 +792,13 @@ export function formatTunnelHealth(health) {
     }
     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')
@@ -1273,15 +806,6 @@ export async function firstUnroutableTunnel(tunnels) {
     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;
@@ -1291,15 +815,6 @@ export function resolveTransport(flag, ctx) {
     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" };
@@ -1309,17 +824,6 @@ export function reachabilityFallbackTransport(transport, temporalReachable, hasS
         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;
@@ -1344,11 +848,6 @@ async function gateVpnDirectReachability(transport, devOutput) {
     }
     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)
@@ -1370,13 +869,6 @@ export function preferredSsmLocalPort(remotePort) {
     }
     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)) {
@@ -1397,9 +889,6 @@ async function allocateSsmLocalPort(remotePort, reservedPorts) {
     }
     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' });
@@ -1409,24 +898,9 @@ function hasSessionManagerPlugin() {
         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.');
@@ -1441,8 +915,6 @@ async function startSsmTunnels(sessionName, devOutput) {
         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',
@@ -1450,8 +922,6 @@ async function startSsmTunnels(sessionName, devOutput) {
         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',
@@ -1467,10 +937,6 @@ async function startSsmTunnels(sessionName, devOutput) {
         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})`);
             }
@@ -1502,7 +968,6 @@ async function startSsmTunnels(sessionName, devOutput) {
         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',
@@ -1520,10 +985,8 @@ async function startSsmTunnels(sessionName, devOutput) {
             })}'`,
         ].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,
@@ -1532,20 +995,12 @@ async function startSsmTunnels(sessionName, devOutput) {
     }
     return rewritten;
 }
-/**
- * Update the DevBox host's Caddy reverse proxy config.
- *
- * Generates a Caddyfile so services are accessible at
- * http://{service}.{stack}.{app}.{tenant}-{env}.mesh.local
- * from the developer's Mac (via Tailscale + dnsmasq).
- */
 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 baseDomain = `${tenant}-${env}.mesh.local`;
-    // Build hostname → port map
     const services = {};
     for (const [name, service] of Object.entries(devOutput.services)) {
         if (service.port) {
@@ -1559,7 +1014,6 @@ async function updateDevboxProxy(devOutput, appRoot) {
     }
     if (Object.keys(services).length === 0)
         return;
-    // Generate Caddyfile
     const lines = [
         '# Auto-generated by mesh dev — do not edit manually.',
         '',
@@ -1575,8 +1029,6 @@ async function updateDevboxProxy(devOutput, appRoot) {
         lines.push('');
     }
     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',
@@ -1587,7 +1039,6 @@ async function updateDevboxProxy(devOutput, appRoot) {
         '-c',
         `cat > /etc/caddy/Caddyfile << 'CADDYEOF'\n${caddyfile}\nCADDYEOF`,
     ], { stdio: 'pipe' });
-    // Reload Caddy on the host via nsenter into PID 1's mount namespace
     execFileSync('docker', [
         'run',
         '--rm',
@@ -1612,17 +1063,14 @@ async function updateDevboxProxy(devOutput, appRoot) {
     }
 }
 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) {
@@ -1632,21 +1080,15 @@ async function setupSubdomainRouting(devOutput, appRoot) {
     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) {
@@ -1665,14 +1107,12 @@ async function setupSubdomainRouting(devOutput, appRoot) {
         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 {
@@ -1700,7 +1140,6 @@ async function setupSubdomainRouting(devOutput, appRoot) {
         });
         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));
@@ -1713,19 +1152,11 @@ async function setupSubdomainRouting(devOutput, appRoot) {
     }
     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);
@@ -1735,54 +1166,28 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         logWarn('No services defined in dev output.');
         return devOutput;
     }
-    // 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]);
-    // 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).');
         }
         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);
             }
@@ -1794,12 +1199,9 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         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)) {
             if (tunnel.host !== 'localhost')
-                continue; // not SSM-rewritten
+                continue;
             logInfo(`Waiting for tunnel ${tName} (localhost:${tunnel.port})...`);
             const ready = await waitForPort('localhost', tunnel.port, TUNNEL_READY_TIMEOUT_MS);
             if (!ready) {
@@ -1812,9 +1214,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         }
     }
     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:');
@@ -1827,22 +1227,14 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
             }
         }
     }
-    // Resolve secrets from Secrets Manager
     let secretEnvVars = {};
     if (devOutput.secrets && Object.keys(devOutput.secrets).length > 0) {
         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)}`),
@@ -1858,12 +1250,7 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     }
     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);
@@ -1871,29 +1258,11 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
                 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'
@@ -1903,10 +1272,6 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     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 });
@@ -1919,7 +1284,6 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
             `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));
         }
@@ -1933,21 +1297,14 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
     const monorepoRoot = findMonorepoRoot();
     for (const [name, service] of Object.entries(devOutput.services)) {
         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, 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;
             const outside = serviceDir !== worktreeRoot && !serviceDir.startsWith(wtRootWithSep);
-            // A dev-LINKED package is outside the worktree by construction, and is what
-            // this app runs either way — see `isLinkedDependencyDir`. Only an
-            // unexplained outside path is the wrong-worktree failure.
             if (outside && isLinkedDependencyDir(serviceDir, appRoot)) {
                 logInfo(`${name}: source is a dev-linked package (${serviceDir})`);
             }
@@ -1959,74 +1316,28 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
                 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 } : {}),
-            // AWS, for the same reason as the Temporal and dev-user overlays above: the
-            // sourced env file WINS over the tmux session env, so a service that reads this
-            // file gets whatever the file says and nothing else.
-            //
-            // It matters beyond the service's own process. A module dev service can hand
-            // credentials to something it starts — the workspaces manager gives each
-            // workspace's sidecar an AWS profile so Claude Code can reach Bedrock — and with
-            // no AWS_* here it silently has none to give. `buildChildAwsEnv` has already
-            // chosen the SELF-REFRESHING shape (a profile with `credential_process`, not a
-            // frozen STS triple), which is exactly what a long-lived child needs.
             ...awsEnv,
         };
         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}`, 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.
     if (process.env.DEVCONTAINER === '1') {
         try {
             await updateDevboxProxy(devOutput, appRoot);
@@ -2035,7 +1346,6 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
             logWarn(`Could not update devbox proxy: ${e.message}`);
         }
     }
-    // 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('');
@@ -2086,13 +1396,8 @@ async function startServices(sessionName, appRoot, devOutput, headless, awsEnv,
         console.log(`Stop with:    mesh dev --kill`);
         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.
- */
 async function showStatus(sessionName, devOutput, asJson) {
     if (!sessionExists(sessionName)) {
         if (asJson) {
@@ -2103,14 +1408,12 @@ async function showStatus(sessionName, devOutput, asJson) {
         }
         return;
     }
-    // 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');
     }
     catch {
-        // Session might have disappeared
     }
     const windowStatus = {};
     for (const line of windows) {
@@ -2119,8 +1422,6 @@ async function showStatus(sessionName, devOutput, asJson) {
             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) {
@@ -2173,9 +1474,6 @@ async function showStatus(sessionName, devOutput, asJson) {
         console.log('tmux: Ctrl+b n/p switch windows, d detach');
     }
 }
-/**
- * Restart a single service window.
- */
 async function restartService(sessionName, serviceName, appRoot, devOutput, awsEnv, opts) {
     let service = devOutput.services[serviceName];
     if (!service) {
@@ -2187,15 +1485,11 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
         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 {
@@ -2213,51 +1507,32 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
             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 } : {}),
-            // Same overlay as launch — a refresh that dropped these would take a working
-            // service's credentials away on restart, which is the hardest kind of change to
-            // attribute afterwards.
             ...awsEnv,
         };
         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' });
     }
     catch {
-        // Window might not exist yet
         logError(`Window '${serviceName}' not found in session.`);
         process.exit(1);
     }
-    // Refresh shared env (AWS creds may have rotated) on the session.
     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 {
@@ -2269,9 +1544,6 @@ async function restartService(sessionName, serviceName, appRoot, devOutput, awsE
     execFileSync('tmux', ['send-keys', '-t', target, restartCmd, 'Enter']);
     logSuccess(`Restarted: ${serviceName}`);
 }
-/**
- * Capture and display logs from a service window.
- */
 function showLogs(sessionName, serviceName, tail) {
     if (!sessionExists(sessionName)) {
         logError(`No active session: ${sessionName}. Run 'mesh dev' first.`);
@@ -2290,14 +1562,6 @@ function showLogs(sessionName, serviceName, tail) {
         process.exit(1);
     }
 }
-// ============================================================================
-// Command registration
-// ============================================================================
-/**
- * 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 buildDoctorContext(appRoot, stack, sessionName) {
     const state = loadSessionState(sessionName);
     const defaultDeployerRole = readStackConfig(appRoot, stack, 'mesh:deployerRole');
@@ -2342,23 +1606,16 @@ export function registerDevCommand(program) {
         .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') {
@@ -2377,7 +1634,6 @@ export function registerDevCommand(program) {
             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) {
@@ -2392,7 +1648,6 @@ export function registerDevCommand(program) {
                     }
                 }
                 catch {
-                    /* best effort */
                 }
                 if (sessionExists(sessionName)) {
                     killSession(sessionName);
@@ -2404,23 +1659,16 @@ export function registerDevCommand(program) {
                 removeSessionState(sessionName);
                 return;
             }
-            // --status with --session: use state file, no Pulumi needed
             const state = loadSessionState(sessionName);
             if (state) {
                 await showStatus(sessionName, state.devOutput, !!options.json);
                 return;
             }
-            // No state — fall through to normal flow
         }
         const appRoot = findAppRoot(options.app);
         const projectName = getProjectName(appRoot);
-        // 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);
@@ -2430,11 +1678,7 @@ export function registerDevCommand(program) {
                 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) {
@@ -2449,7 +1693,6 @@ export function registerDevCommand(program) {
                 }
             }
             catch {
-                /* best effort */
             }
             if (sessionExists(sessionName)) {
                 killSession(sessionName);
@@ -2464,17 +1707,8 @@ export function registerDevCommand(program) {
             }
             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') {
@@ -2494,20 +1728,8 @@ export function registerDevCommand(program) {
             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);
@@ -2532,22 +1754,14 @@ export function registerDevCommand(program) {
                     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') {
@@ -2560,26 +1774,14 @@ export function registerDevCommand(program) {
                 return;
             }
             let signInServices = [];
-            /** The app's own version — stamped on the registration like a deploy. */
             let appVersion;
-            // 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 = [];
-                // Services carrying a BROWSER login (package.json → mesh.auth.signIn).
-                // Registered after ports are allocated — the redirect URI is the port.
                 signInServices = [];
                 try {
                     const appPkg = JSON.parse(fs.readFileSync(path.join(appRoot, 'package.json'), 'utf-8'));
@@ -2593,12 +1795,8 @@ export function registerDevCommand(program) {
                         appVersion = appPkg.version;
                 }
                 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) {
@@ -2606,10 +1804,6 @@ export function registerDevCommand(program) {
                     ` — if the local Zitadel predates seeding, run: mesh stop --destroy && mesh start`);
             }
             const devOutput = await allocatePorts(rawDevOutput, worktree);
-            // Browser sign-in AFTER port allocation: the callback URL is the port a
-            // service actually listens on, and a stale URI is the difference between
-            // a working login and an "invalid redirect_uri" nobody can debug from
-            // the app side.
             for (const service of signInServices) {
                 const port = devOutput.services[service]?.port;
                 if (!port) {
@@ -2629,9 +1823,6 @@ export function registerDevCommand(program) {
                         ` — the Hub's Access → Sign-in tab will report this app has no login.`);
                 }
             }
-            // 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,
@@ -2640,8 +1831,6 @@ export function registerDevCommand(program) {
                     services: Object.keys(devOutput.services),
                     ports: Object.fromEntries(Object.entries(devOutput.services).map(([name, svc]) => [name, svc.port])),
                     kinds: Object.fromEntries(Object.entries(devOutput.services).flatMap(([name, svc]) => svc.kind ? [[name, svc.kind]] : [])),
-                    // 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),
@@ -2650,13 +1839,6 @@ export function registerDevCommand(program) {
             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)) {
@@ -2665,8 +1847,6 @@ export function registerDevCommand(program) {
                     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);
@@ -2706,28 +1886,20 @@ export function registerDevCommand(program) {
                         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
+                        throw err;
                     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);
@@ -2753,8 +1925,7 @@ export function registerDevCommand(program) {
                 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' });
+            const finalDevOutput = await startServices(sessionName, appRoot, devOutput, !!options.headless, localAwsEnv(), { transport: 'vpn-direct' });
             registerServiceProbes(finalDevOutput, localTenant, externalProbeFiles);
             saveSessionState(sessionName, {
                 appRoot,
@@ -2768,15 +1939,10 @@ export function registerDevCommand(program) {
             return;
         }
         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.');
+            logWarn('--externals/--mock is local-mode only for now (tethered dev outputs do not carry external declarations yet). Continuing without them.');
         }
         const stack = detectStack(appRoot, resolveStackOption(options));
         logInfo(`Project: ${projectName}, Stack: ${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) {
@@ -2791,19 +1957,8 @@ export function registerDevCommand(program) {
             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');
@@ -2821,9 +1976,6 @@ export function registerDevCommand(program) {
         }
         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);
@@ -2841,10 +1993,7 @@ export function registerDevCommand(program) {
             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(),
@@ -2871,14 +2020,8 @@ export function registerDevCommand(program) {
             }
         }
         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,
@@ -2899,26 +2042,11 @@ export function registerDevCommand(program) {
                 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);
@@ -2939,18 +2067,12 @@ export function registerDevCommand(program) {
         }
         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})`);
@@ -2958,30 +2080,17 @@ export function registerDevCommand(program) {
             }
             throw err;
         }
-        // --status — use persisted state (has allocated ports), fall back to raw
         if (options.status) {
             const state = loadSessionState(sessionName);
             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;
         }
-        // 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';
@@ -2989,8 +2098,6 @@ export function registerDevCommand(program) {
             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);
@@ -3001,10 +2108,6 @@ export function registerDevCommand(program) {
                     : 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 };
@@ -3012,15 +2115,9 @@ export function registerDevCommand(program) {
             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) {
@@ -3046,19 +2143,10 @@ export function registerDevCommand(program) {
                 };
             }
         }
-        // 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,
@@ -3067,13 +2155,11 @@ export function registerDevCommand(program) {
             workflowFingerprint: fingerprintWorkflowSource(appRoot, finalDevOutput.services),
         });
     });
-    // Subcommand: logs
     dev
         .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') {
@@ -3089,7 +2175,6 @@ export function registerDevCommand(program) {
             showLogs(`${projectName}-dev`, service, parseInt(opts.tail, 10));
         }
     });
-    // Subcommand: restart
     dev
         .command('restart <service>')
         .description('Restart a service')
@@ -3098,11 +2183,8 @@ export function registerDevCommand(program) {
         .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) {
@@ -3117,22 +2199,11 @@ export function registerDevCommand(program) {
                 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;
@@ -3145,10 +2216,6 @@ export function registerDevCommand(program) {
                 });
             }
             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 ??
@@ -3156,15 +2223,10 @@ export function registerDevCommand(program) {
                 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
@@ -3176,18 +2238,12 @@ export function registerDevCommand(program) {
                 }
                 : 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,
@@ -3196,16 +2252,12 @@ export function registerDevCommand(program) {
             }
         }
         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')
@@ -3222,19 +2274,15 @@ export function registerDevCommand(program) {
         const sessionName = dev.opts().session ?? `${projectName}-dev`;
         const state = loadSessionState(sessionName);
         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')
         .action(() => {
-        // --json is on the parent dev command
         const asJson = dev.opts().json;
         const mono = findMonorepoRoot();
         if (!mono) {
@@ -3243,7 +2291,6 @@ export function registerDevCommand(program) {
         }
         const apps = discoverApps(mono);
         if (asJson) {
-            // Include running state for each app
             const result = apps.map((app) => {
                 const sessionName = `${app.name}-dev`;
                 return {
@@ -3271,7 +2318,6 @@ export function registerDevCommand(program) {
             console.log('');
         }
     });
-    // Subcommand: test-user — retrieve Temporal test user credentials
     dev
         .command('test-user [name]')
         .description('Get Temporal test user credentials (from Pulumi-managed test users)')
@@ -3283,7 +2329,6 @@ export function registerDevCommand(program) {
         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,
@@ -3317,7 +2362,6 @@ export function registerDevCommand(program) {
             }
         }
         else {
-            // Get a specific test user
             try {
                 const resp = await ssm.send(new GetParameterCommand({
                     Name: `${basePath}/${name}`,
@@ -3328,7 +2372,6 @@ export function registerDevCommand(program) {
                     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));
@@ -3357,4 +2400,3 @@ export function registerDevCommand(program) {
         }
     });
 }
-//# sourceMappingURL=dev.js.map