@cotal-ai/cli 0.16.0 → 0.17.0

package/dist/commands/up.js

@@ -2,11 +2,11 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createConnection, createServer } from "node:net";
 import { hostname } from "node:os";
-import { mkdirSync, writeFileSync, readFileSync, existsSync, openSync, statSync, readSync, closeSync, lstatSync, rmSync, } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, openSync, statSync, readSync, closeSync, lstatSync, rmSync, realpathSync, } from "node:fs";
 import { join, resolve } from "node:path";
-import { isReachable, DEFAULT_SERVER, CONTROL_ADMIN, createSpaceAuth, serverConfig, mintCreds, mintConnectionEvictorCreds, mintMembershipObserverCreds, newIdentity, setupSpaceStreams, standaloneConnectOpts, seedChannelRegistry, ensureDefaultDeliveryClass, mkSecretDir, writeSecretFile, } from "@cotal-ai/core";
+import { isReachable, DEFAULT_SERVER, createSpaceAuth, serverConfig, openServerConfig, validateTlsMaterial, mintCreds, mintLifecycleUid, DEV_OWNER, mintConnectionEvictorCreds, mintMembershipObserverCreds, newIdentity, setupSpaceStreams, standaloneConnectOpts, seedChannelRegistry, ensureDefaultDeliveryClass, mkSecretDir, writeSecretFile, } from "@cotal-ai/core";
 import { connect } from "@nats-io/transport-node";
-import { assertSingleSpaceBroker, assertUserAuthInfo, authDir, getSoleSpaceAuth, getSpaceAuth, hasUserAuthState, loadSoleSpaceAuth, putSpaceAuth, clearCurrent, findMesh, getCurrent, loadMeshes, MEMBERSHIP_RW_CREDS_KEY, recordMesh, removeMesh, setCurrent, userAuthStateDir, workspaceSecretStore, acquireMaintenanceLock, assertStoreIdentity, assessRestoreClaim, beginOrdinaryResume, bindOrdinaryResumeListener, consumeRetiredMaintenance, markOrdinaryResumeActive, markOrdinaryResumeDegraded, replaceDeadOrdinaryResumeListener, localProcessOwnerStatus, readMaintenanceJournal, readMaintenanceResumeDocument, readStoreIdentity, recordOrdinaryResumeManagerCommit, releaseMaintenanceLock, retireOrdinaryResume, sameStoreIdentity, } from "@cotal-ai/workspace";
+import { assertSingleSpaceBroker, assertUserAuthInfo, authDir, getSoleSpaceAuth, getSpaceAuth, hasUserAuthState, loadSoleSpaceAuth, putSpaceAuth, clearCurrent, findMesh, getCurrent, loadMeshes, MEMBERSHIP_RW_CREDS_KEY, recordMesh, meshesForRoot, removeMesh, rotateSystemCreds, setCurrent, staleSystemCreds, SYSTEM_CREDS_FILES, userAuthStateDir, workspaceSecretStore, acquireMaintenanceLock, assertStoreIdentity, assessRestoreClaim, beginOrdinaryResume, bindOrdinaryResumeListener, consumeRetiredMaintenance, markOrdinaryResumeActive, markOrdinaryResumeDegraded, replaceDeadOrdinaryResumeListener, localProcessOwnerStatus, readMaintenanceJournal, readMaintenanceResumeDocument, readStoreIdentity, recordOrdinaryResumeManagerCommit, releaseMaintenanceLock, retireOrdinaryResume, sameStoreIdentity, readBrokerPolicy, writeBrokerPolicy, } from "@cotal-ai/workspace";
 import { ensureAuthService, resolveAuthProvider, stopAuthService } from "../lib/auth-proc.js";
 import { resolveSpace } from "../lib/status.js";
 import { c } from "../ui.js";
@@ -32,12 +32,15 @@ export const upFlags = [
     { name: "space", type: "string", value: "<s>", description: "space name (default: the folder's)" },
     { name: "store-dir", type: "string", value: "<dir>", description: "JetStream store directory" },
     { name: "channels", type: "string", value: "<path>", description: "channel-registry seed file (JSON; default .cotal/channels.json)" },
+    { name: "tls-cert", type: "string", value: "<file>", description: "serve the broker over TLS with this certificate (requires --tls-key)" },
+    { name: "tls-key", type: "string", value: "<file>", description: "the private key for --tls-cert" },
     { name: "restore", type: "string", value: "<dir>", description: "restore an offline backup before exposing the normal listener" },
     { name: "restore-only", type: "string", value: "<registry>", description: "restore only the registry component" },
     { name: "accept-missing-source", type: "boolean", description: "explicit disaster consent when the inode-bound preserved source is absent" },
     { name: "open", type: "boolean", description: "unauthenticated dev mesh (no JWT/ACLs)" },
     { name: "user-auth", type: "boolean", description: "per-USER auth: login + bearer through the space's auth service" },
     { name: "idp", type: "string", value: "<url>", description: "with --user-auth: the IdP auth base URL to pin (first enable)" },
+    { name: "rotate-sys", type: "boolean", description: "renew the expired/expiring $SYS creds by rotating the system account (agents, data and creds survive; needs a stopped mesh)" },
     { name: "detach", type: "boolean", description: "run in the background (stop with `cotal down`)" },
     { name: "runtime", type: "string", value: "<name>", description: "agent runtime for the mesh manager (default pty; extension runtimes are explicit-only, see `cotal runtimes`); with -f overrides the manifest's runtime" },
     { name: "file", type: "string", short: "f", value: "<cotal.yaml>", description: "launch a whole mesh from a manifest" },
@@ -63,6 +66,13 @@ export async function up(args) {
     if (values.restore) {
         if (values.file || values.channels)
             throw new Error("--restore cannot be combined with --file/-f or --channels");
+        // A restore REINSTATES a trust root from an artifact; a rotation SUPERSEDES the one on disk.
+        // Together they would restore a system account and retire it in the same command, leaving the
+        // operator unable to say which authority the mesh actually came up on, and the artifact's own
+        // $SYS creds overwritten by the rotation before anyone verified the restore. Restore, verify,
+        // then rotate as its own deliberate step.
+        if (values["rotate-sys"])
+            throw new Error("--restore cannot be combined with --rotate-sys - restore the space and verify it first, then rotate: `cotal down` then `cotal up --rotate-sys`");
         // A restore rewrites the shared store and the trust root under it, from an artifact that names
         // one space (see `cotal backup`) - it cannot leave the root's other tenants standing.
         assertSingleSpaceBroker(authDir(cotalRoot()), "cotal up --restore");
@@ -93,8 +103,22 @@ export async function up(args) {
     }
     if (values["restore-only"] || values["accept-missing-source"])
         throw new Error("--restore-only and --accept-missing-source require --restore <dir>");
+    // MAINTENANCE RE-ENTRY. `--restore` is refused with `--rotate-sys` above, but that guard only sees
+    // the EXPLICIT flag: a restore/resume re-entry arrives with `restore` cleared and an `__*Attempt`
+    // set, and an auto-recovered journal reaches the same place with no restore flag ever typed. Both
+    // re-entries then hit adopt-the-live-listener paths that RETURN before `authSetup`, so the flag
+    // would be accepted, nothing would rotate, and the command would exit 0. That is the silent
+    // success this whole change exists to remove, so it is refused here, before any attempt state is
+    // read. A rotation is a stopped, fresh boot; a half-finished maintenance attempt is neither.
+    if (values["rotate-sys"] && (values.__restoreAttempt || values.__ordinaryResumeAttempt))
+        throw new Error("--rotate-sys cannot run during a restore/resume re-entry - finish or roll back the maintenance attempt, then `cotal down` and `cotal up --rotate-sys`");
     if (!values.__restoreAttempt && !values.__ordinaryResumeAttempt && !values.file) {
         const root = cotalRoot();
+        // Same refusal for the AUTO-recovered journal, raised before the recovery is prepared and
+        // re-entered, so the operator reads one clear error instead of one thrown from inside a nested
+        // `up` that has already begun adopting a maintenance attempt.
+        if (values["rotate-sys"] && readMaintenanceJournal(root))
+            throw new Error("--rotate-sys is refused while this root has a maintenance attempt to recover - finish or roll back that attempt (`cotal up` alone recovers it), then `cotal down` and `cotal up --rotate-sys`");
         const lock = acquireMaintenanceLock(root);
         let pending;
         let recoveredRestore;
@@ -304,6 +328,77 @@ export async function up(args) {
     if (values.idp && !wantUser && !values.file) {
         throw new Error('--idp is for user-auth spaces; pair it with --user-auth, or set broker.auth: "user" in a manifest');
     }
+    // An open mesh has no operator, no system account, and no $SYS creds, so there is nothing to
+    // rotate; the request is a misunderstanding to name, never a silent no-op that reports success.
+    if (values["rotate-sys"] && values.open) {
+        throw new Error("--rotate-sys is for auth meshes: an open mesh (--open) has no system account or $SYS credentials to rotate");
+    }
+    // THE EFFECTIVE PROJECT ROOT IS PINNED BEFORE THE TRANSPORT IS DECIDED.
+    //
+    // `ensureRootForSpace` may create `cwd/.cotal` when the nearest ancestor root already owns a
+    // different auth space — the child becomes its own mesh root. That pin used to run AFTER
+    // `resolveTransport`, so a TLS policy was written to the PARENT root while the listener and
+    // MeshEntry landed on the CHILD. First `up --tls-*` looked green (transport was in memory);
+    // `down` then bare `up` from the child found no policy and served plaintext, rewriting
+    // `tlsRequired: false`. Same class as B4/B5: operator-visible TLS success, silent cleartext on
+    // the documented retain path. Also polluted the parent's policy file.
+    //
+    // Dry-run must not pin (mkdir is a mutation). Validation still uses whatever root is visible;
+    // persistence is already suppressed below.
+    if (!values["dry-run"]) {
+        const spaceForRoot = values.space ?? resolveSpace(process.cwd());
+        if (values.file) {
+            try {
+                const prepared = loadManifest(resolve(values.file));
+                const space = values.space ?? prepared.manifest.space;
+                const open = Boolean(values.open) || prepared.manifest.broker?.auth === false;
+                ensureRootForSpace(!open, space);
+            }
+            catch {
+                // Manifest errors are reported by the -f path with the same load; do not double-print.
+            }
+        }
+        else {
+            ensureRootForSpace(!values.open, spaceForRoot);
+        }
+    }
+    // THE TRANSPORT IS DECIDED HERE, ABOVE EVERY BRANCH, AND THIS POSITION IS THE FIX.
+    //
+    // It used to be resolved inside the foreground path only, which meant three routes to a listener
+    // never saw it: `up -f` (manifest), `up --detach`, and the already-running refresh. Each accepted
+    // `--tls-cert`/`--tls-key`, validated nothing, and served PLAINTEXT while printing `✓ mesh up`.
+    // Every one of those was a separate exit from the same room, and closing them one at a time is
+    // what produced three rounds of the same defect.
+    //
+    // A guard only fences what comes AFTER it, so the decision has to dominate the branch rather than
+    // sit in one arm of it. The dial-host SAN is deliberately NOT checked here — the effective host is
+    // not known until a route picks it — so each route re-asserts it via `assertServesDialHost` once
+    // it does. Decide early so nothing can skip it; check late so it checks the right host.
+    // `persist` is false on a dry run, and that is a REGRESSION THIS HOIST CAUSED. Before the move,
+    // `resolveTransport` ran inside the launch path and a `--dry-run` never reached it. Hoisting it
+    // above the branch is what makes the transport dominate every route — and it also put a WRITE in
+    // front of a command whose entire contract is "mutate nothing", so `up -f --dry-run --tls-cert`
+    // printed "Dry run - nothing was changed" and left a broker-policy.json behind.
+    //
+    // Validation still runs: a dry run should absolutely refuse an expired or unreadable cert, and
+    // reporting that is the point of it. Only the persistence is suppressed. An instrument that
+    // modifies what it inspects is a defect even when everything it reports is true.
+    //
+    // The root argument is the PINNED root (or the walked root on dry-run). One root for policy,
+    // auth, store, and MeshEntry — never a second walk that can disagree after a later pin.
+    //
+    // PERSIST IS ALWAYS FALSE HERE (commit-after-apply). resolveTransport used to write the policy
+    // before the already-running refresh branch could refuse a transport change, so a failed
+    // `up --tls-*` against a live plaintext mesh left tls-required on disk; the next bare `up`
+    // printed "TLS: inheriting" / "TLS: serving" / green already-running over a cleartext listener
+    // (S5). Decide and validate early so every branch sees the transport; write only after a
+    // matching listener is started and proved (`commitTransportPolicy`), never on a refuse path.
+    // `quiet` suppresses the serving/inheriting lines until that commit (or a dry-run announce).
+    const meshRoot = cotalRoot();
+    const transport = resolveTransport(values, undefined, meshRoot, {
+        persist: false,
+        quiet: true,
+    });
     // `up -f cotal.yaml` is a distinct path: bring up a FRESH mesh described by a manifest (broker +
     // channels + booted agents). It owns the whole space; deploying onto a RUNNING mesh is `spawn -f`.
     // CLI flags override the manifest (flag > manifest > default) so the same file runs at a different
@@ -311,6 +406,7 @@ export async function up(args) {
     if (values.file) {
         if (values["dry-run"]) {
             await upManifest(values.file, {
+                transport,
                 dryRun: true,
                 server: values.server,
                 host: values.host,
@@ -319,6 +415,7 @@ export async function up(args) {
                 open: values.open,
                 userAuth: wantUser,
                 idp: values.idp,
+                rotateSys: values["rotate-sys"],
             });
             return;
         }
@@ -326,6 +423,7 @@ export async function up(args) {
         try {
             assertOrdinaryUpAllowed(cotalRoot());
             await upManifest(values.file, {
+                transport,
                 dryRun: Boolean(values["dry-run"]),
                 server: values.server,
                 host: values.host,
@@ -334,6 +432,7 @@ export async function up(args) {
                 open: values.open,
                 userAuth: wantUser,
                 idp: values.idp,
+                rotateSys: values["rotate-sys"],
             });
         }
         finally {
@@ -417,6 +516,40 @@ export async function up(args) {
                     console.error(c.red(`✗ mesh "${held.space}" is already running at ${server} with ${label} - a running broker can't change auth mode; \`cotal down\` it first, then \`cotal up ${wantUser ? "--user-auth" : "--open"}\``));
                     process.exit(1);
                 }
+                // A rotation retires the system account this LIVE broker was started on, and only a broker
+                // (re)started from the rewritten config carries the successor. Rotating under a running mesh
+                // would leave the record and the creds a generation ahead of the broker: every $SYS client
+                // denied, with `doctor auth` reporting freshly-minted creds. Refuse with the two-step recipe.
+                if (values["rotate-sys"]) {
+                    console.error(c.red(`✗ mesh "${held.space}" is already running at ${server} - a running broker can't rotate its system account (it would keep serving the retired one); \`cotal down\` it first, then \`cotal up --rotate-sys\``));
+                    process.exit(1);
+                }
+                // A running broker cannot change its transport either, and for exactly the reason it cannot
+                // change its auth mode: the listener's TLS config was fixed when nats-server read its config
+                // file. This branch starts nothing, so `--tls-cert`/`--tls-key` here can only be a request to
+                // change something that is already decided — and answering it with `✓ mesh up` told the
+                // operator they had TLS while the live broker went on serving whatever it was started with.
+                //
+                // Refuse rather than warn. The whole feature is that a command accepting a TLS flag either
+                // encrypts or refuses to start; printing a success line over an unchanged plaintext listener
+                // is the precise outcome that must be unreachable.
+                if (values["tls-cert"] || values["tls-key"]) {
+                    console.error(c.red(`✗ mesh "${held.space}" is already running at ${server} - a running broker can't change its transport; \`cotal down\` it first, then \`cotal up --tls-cert <cert> --tls-key <key>\``));
+                    process.exit(1);
+                }
+                // Live INFO must agree with the recorded/requested transport. A bare refresh that greets
+                // "already running" over a plaintext listener while policy claims TLS is S5's second half —
+                // the refuse left a durable lie and this path used to reprint TLS success over cleartext.
+                const liveTls = await liveListenerRequiresTls(server);
+                const wantTls = transport.kind === "tls-required" || held.tlsRequired === true;
+                if (wantTls && liveTls === false) {
+                    console.error(c.red(`✗ mesh "${held.space}" at ${server} is recorded/expected TLS-required but the live listener is plaintext - refuse rather than claim it is up; \`cotal down\` then \`cotal up --tls-cert <cert> --tls-key <key>\` (or fix the broker)`));
+                    process.exit(1);
+                }
+                if (!wantTls && liveTls === true) {
+                    console.error(c.red(`✗ mesh "${held.space}" at ${server} is serving TLS but this mesh is recorded plaintext - \`cotal down\` then re-up with matching flags`));
+                    process.exit(1);
+                }
                 console.log(c.green(`✓ mesh "${held.space}" already running at ${server}`));
                 // USER MODE: re-upping IS the documented recovery for a dead auth service (the provider's
                 // failure copy says "restart it with `cotal up`"), so a refresh must re-ensure the service —
@@ -480,10 +613,26 @@ export async function up(args) {
                 const heldAttachHost = attachHostFor(held.space, values.host);
                 // A broker was already answering here — this branch starts nothing, so it must not claim the
                 // record as ours (see `Provenance`).
-                recordOurMesh({ space: held.space, server, root, mode: held.mode, ...(userAuth ? { userAuth } : {}), ...(heldAttachHost ? { attachHost: heldAttachHost } : {}), ts: new Date().toISOString() }, "refresh");
+                // `tlsRequired` is CARRIED FORWARD, not re-derived. This branch starts no listener, so it has
+                // no transport decision to record — and `recordOurMesh` writes the entry whole, so omitting
+                // the field here would erase the requirement on every bare refresh, exactly the way dropping
+                // `attachHost` would silently demote the mesh to loopback.
+                recordOurMesh({ space: held.space, server, root, mode: held.mode, ...(held.tlsRequired !== undefined ? { tlsRequired: held.tlsRequired } : {}), ...(userAuth ? { userAuth } : {}), ...(heldAttachHost ? { attachHost: heldAttachHost } : {}), ts: new Date().toISOString() }, "refresh");
                 return;
             }
             const who = held ? `mesh "${held.space}" (${held.root})` : "a broker not started here";
+            // Reaching here with `--rotate-sys` means something IS answering at the requested address and it
+            // is not this root's recorded mesh (that case was refused above). The ordinary response is to pick
+            // a free port and carry on, which for a rotation is the wrong instinct: the unidentified listener
+            // may be a `nats-server -c <root>/.cotal/auth/server.conf` started by hand, holding THIS root's
+            // config and JetStream store while writing neither a pidfile nor a registry row. Rotating around
+            // it retires the account it is still serving and opens its store a second time. Nothing available
+            // here can identify it (that is what unidentified means), so refuse instead of stepping past it.
+            if (values["rotate-sys"]) {
+                console.error(c.red(`✗ ${server} is answering and it is not this root's recorded mesh (${who})`) +
+                    c.dim(" - `--rotate-sys` will not start on another port around an unidentified broker: it may be serving this root's own server.conf and JetStream store. Stop whatever is listening there (`cotal down` if it was started here), then rotate."));
+                process.exit(1);
+            }
             if (values.server === undefined && (!held || held.root !== root)) {
                 const next = await serverWithFreePort(server, host);
                 console.log(c.dim(`${server} is already in use by ${who}; starting "${space}" at ${next} instead`));
@@ -497,11 +646,13 @@ export async function up(args) {
         if (values.detach) {
             const restored = resumeAttempt ? pendingRestores.get(resumeAttempt) : undefined;
             const { pid, source, authService, controlPlane, delivery, manager } = await startMeshDetached({
+                transport,
                 server,
                 storeDir: values["store-dir"],
                 space: values.space,
                 open: values.open,
                 userAuth: wantUser ? { idpUrl: values.idp } : undefined,
+                rotateSys: values["rotate-sys"],
                 channels: values.channels,
                 // The RAW flag, not the loopback-defaulted `host` above: `startMeshDetached` applies the same
                 // default itself, and what it records must distinguish "the operator asked for this address"
@@ -527,6 +678,7 @@ export async function up(args) {
                 } : {}),
                 skipPostStart: Boolean(resumeAttempt),
             });
+            // Transport policy is committed inside startMeshDetached before delivery launch (S5+S9).
             console.log(c.dim(`Started nats-server (${source}).`));
             console.log(c.green(renderDetachedSummary({ pid, delivery, authService: wantUser && authService, manager })));
             if (restored && process.env.COTAL_SMOKE_FAIL_AFTER_RESTORE_LISTENER_READY === "1")
@@ -556,11 +708,19 @@ export async function up(args) {
         mkdirSync(storeDir, { recursive: true });
         await claimSpace(space, server, cotalRoot());
         const seedFile = loadChannelsFile(values.channels);
-        const setup = useAuth ? await authSetup(storeDir, server, space, host, wantUser ? { idpUrl: values.idp } : undefined) : undefined;
+        // Decided above the branch; the dial host is only settled here (a port collision may have moved
+        // the server, and the hostname is what the certificate has to match).
+        assertServesDialHost(transport, new URL(server).hostname);
+        const setup = useAuth ? await authSetup(storeDir, server, space, host, wantUser ? { idpUrl: values.idp } : undefined, transport, values["rotate-sys"]) : undefined;
         const port = Number(new URL(server).port) || 4222;
         const restored = resumeAttempt ? pendingRestores.get(resumeAttempt) : undefined;
+        // Both modes go through a RENDERER, never bare CLI flags. Open mode used to start from
+        // `-js -sd … -p … -a …`, which never called a renderer at all — so the required transport union
+        // protected the auth path and was silent on the open one, and a cert/key pair passed to an
+        // open-mode `up` would have been accepted while the listener came up in cleartext.
+        const confPath = setup ? setup.confPath : writeOpenBrokerConf(storeDir, { port, host, transport });
         const natsArgs = [
-            ...(setup ? ["-c", setup.confPath] : ["-js", "-sd", storeDir, "-p", String(port), "-a", host]),
+            "-c", confPath,
             ...(restored ? ["--name", restored.serverName]
                 : ordinaryAttempt ? ["--name", ordinaryAttempt.serverName]
                     : []),
@@ -611,8 +771,9 @@ export async function up(args) {
             void stopDelivery()
                 .catch((e) => console.error(`! delivery teardown: ${e.message}`))
                 .then(() => {
-                stopManager();
-                stopAuthService(space);
+                void stopManager()
+                    .then(() => stopAuthService(space))
+                    .catch((e) => console.error(`! teardown: ${e.message}`));
                 child.kill("SIGTERM");
             });
         };
@@ -624,8 +785,8 @@ export async function up(args) {
             rmSync(cotalPath("nats.pid"), { force: true });
             // Logged, never silently swallowed; the daemon kill runs in stopDelivery's finally regardless.
             await stopDelivery().catch((e) => console.error(`! delivery teardown: ${e.message}`));
-            stopManager();
-            stopAuthService(space);
+            await stopManager().catch((e) => console.error(`! manager teardown: ${e.message}`));
+            await stopAuthService(space).catch((e) => console.error(`! auth teardown: ${e.message}`));
             // Only unrecord if the registry still points at THIS broker. A newer broker for the same space
             // (a concurrent `up`, or a different-port re-up that recorded after us) may have replaced our
             // record — removing by name would clobber the live winner and hide it from the registry.
@@ -651,6 +812,8 @@ export async function up(args) {
         }
         if (restored)
             await provePreparedRestoreListener(restored);
+        // Listener ready — commit the transport decision (S5: not before start).
+        commitTransportPolicy(meshRoot, transport);
         {
             if (!resumeAttempt)
                 await postStart(server, space, setup, seedFile);
@@ -671,6 +834,11 @@ export async function up(args) {
             recordOurMesh({
                 space, server, root: cotalRoot(),
                 mode: setup?.prepared ? "user" : useAuth ? "auth" : "open",
+                // Written ALWAYS, as a boolean, unlike `attachHost` below. Absence and `false` resolve
+                // identically for clients, so an omitted field would be indistinguishable from a deliberate
+                // plaintext mesh — and this is the one field whose whole purpose is that the answer was
+                // stated rather than defaulted.
+                tlsRequired: transport.kind === "tls-required",
                 ...(svc.userAuth ? { userAuth: svc.userAuth } : {}),
                 // Only a real decision is persisted — an explicit `--host` now, or one carried forward from a
                 // previous launch. The bare case stays absent rather than recording the loopback default as
@@ -690,6 +858,8 @@ export async function up(args) {
                 attachHost: effectiveAttachHost,
                 resumeAttempt,
                 resumeCommitToken: restored?.managerCommit?.durableCommitToken ?? ordinaryAttempt?.managerCommit?.durableCommitToken,
+                transport,
+                wsPort: setup?.wsPort, // P2 item 6: the console session client's broker ws port
             });
             if (restored && process.env.COTAL_SMOKE_FAIL_AFTER_RESTORE_LISTENER_READY === "1")
                 throw new Error("smoke-injected failure after restore listener readiness");
@@ -755,10 +925,15 @@ async function resumeControlAuth(root, mode) {
     if (!auth)
         throw new Error("same-principal resume requires the existing space trust material");
     const identity = newIdentity();
+    // The instrument's ep caller triple (1c.2b): the admin instrument's rows are lifecycle-keyed,
+    // and the triple rides back so the resume/preservation calls take askManager's ep path.
+    const uid = mintLifecycleUid();
     return {
         creds: await mintCreds(auth, identity, "control-caller-admin", {
+            lifecycleUid: uid,
             expiresAt: Math.floor((Date.now() + 30 * 60 * 1000) / 1000),
         }),
+        epCaller: { owner: DEV_OWNER, actor: identity.id, uid },
     };
 }
 function restoreListenerOwner(pid, nonce, startedAt) {
@@ -910,7 +1085,7 @@ async function provePreparedRestoreListener(prepared) {
     const auth = await resumeControlAuth(prepared.root, prepared.mode);
     const nc = await connect({
         servers: prepared.server,
-        ...standaloneConnectOpts(auth),
+        ...standaloneConnectOpts({ ...auth, /* not yet wired to a recorded transport - see broker-policy/MeshEntry work */ tls: false }),
         maxReconnectAttempts: 0,
     });
     try {
@@ -992,7 +1167,7 @@ async function proveOrdinaryResumeListener(pending) {
     const auth = await resumeControlAuth(pending.root, pending.mode);
     const nc = await connect({
         servers: pending.server,
-        ...standaloneConnectOpts(auth),
+        ...standaloneConnectOpts({ ...auth, /* not yet wired to a recorded transport - see broker-policy/MeshEntry work */ tls: false }),
         maxReconnectAttempts: 0,
     });
     try {
@@ -1025,6 +1200,8 @@ async function resumeProvenOrdinaryListener(pending) {
         server: pending.server,
         root: pending.root,
         mode: pending.mode,
+        // Adopted from the recorded policy: this path proves and re-adopts a listener it did not start.
+        tlsRequired: adoptedTlsRequired(pending.root),
         ...(svc.userAuth ? { userAuth: svc.userAuth } : {}),
         ...(adoptAttachHost ? { attachHost: adoptAttachHost } : {}),
         ts: new Date().toISOString(),
@@ -1064,6 +1241,9 @@ async function resumeProvenRestoreListener(prepared) {
         server: prepared.server,
         root: prepared.root,
         mode: prepared.mode,
+        // Same as the ordinary-resume path: a restore adopts an existing listener, so the requirement
+        // comes from the policy that listener was started from, never from a default.
+        tlsRequired: adoptedTlsRequired(prepared.root),
         ...(svc.userAuth ? { userAuth: svc.userAuth } : {}),
         ...(restoreAttachHost ? { attachHost: restoreAttachHost } : {}),
         ts: new Date().toISOString(),
@@ -1129,7 +1309,7 @@ async function completeResumeActivation(attemptId, healthy, reason, server) {
     const auth = await resumeControlAuth(pending.root, pending.mode);
     const readinessDeadline = Date.now() + 20_000;
     for (;;) {
-        const ready = await askManager(pending.space, server, "ps", undefined, auth, CONTROL_ADMIN, 2_000);
+        const ready = await askManager(pending.space, server, "ps", undefined, auth, "any", 2_000);
         if (!ready.error?.startsWith("no manager reachable"))
             break;
         if (Date.now() >= readinessDeadline) {
@@ -1143,7 +1323,7 @@ async function completeResumeActivation(attemptId, healthy, reason, server) {
         inventory: restored?.selection === "registry"
             ? { ...pending.inventory, agents: [] }
             : pending.inventory,
-    }, auth, CONTROL_ADMIN, 10 * 60 * 1000);
+    }, auth, "any", 10 * 60 * 1000);
     if (!resumed.ok) {
         const detail = resumed.data ? ` (${JSON.stringify(resumed.data)})` : "";
         const message = `${resumed.error ?? "retained-agent resume failed"}${detail}`;
@@ -1171,7 +1351,7 @@ async function completeResumeActivation(attemptId, healthy, reason, server) {
         }
     }
     if (!managerCommit) {
-        const committed = await askManager(pending.space, server, "commitResume", { attemptId }, auth, CONTROL_ADMIN, 40_000);
+        const committed = await askManager(pending.space, server, "commitResume", { attemptId }, auth, "any", 40_000);
         if (!committed.ok) {
             const message = committed.error ?? "manager resume commit failed";
             markPendingResumeDegraded(attemptId, message);
@@ -1201,7 +1381,7 @@ async function completeResumeActivation(attemptId, healthy, reason, server) {
             process.exit(89);
     }
     else {
-        const recommitted = await askManager(pending.space, server, "commitResume", { attemptId }, auth, CONTROL_ADMIN, 40_000);
+        const recommitted = await askManager(pending.space, server, "commitResume", { attemptId }, auth, "any", 40_000);
         // A surviving manager that already finalized legitimately answers {state:"active"} with the
         // exact durable token: accept both committed shapes idempotently, then reissue the token-bound
         // finalize (itself idempotent) below.
@@ -1213,7 +1393,7 @@ async function completeResumeActivation(attemptId, healthy, reason, server) {
         if (!exactToken)
             throw new Error(`replacement manager did not recover the durable commit token for attempt ${attemptId}`);
     }
-    const finalized = await askManager(pending.space, server, "finalizeResume", { attemptId, durableCommitToken: managerCommit.durableCommitToken }, auth, CONTROL_ADMIN, 40_000);
+    const finalized = await askManager(pending.space, server, "finalizeResume", { attemptId, durableCommitToken: managerCommit.durableCommitToken }, auth, "any", 40_000);
     if (!finalized.ok)
         throw new Error(finalized.error ?? `manager resume finalize failed for attempt ${attemptId}`);
     if (!isManagerFinalizeResult(finalized.data, attemptId))
@@ -1305,7 +1485,21 @@ async function upManifest(file, opts) {
     const open = m.broker?.auth === false; // default is auth
     const userAuth = m.broker?.auth === "user" ? { idpUrl: opts.idp ?? m.broker?.idp } : undefined; // flag > manifest
     const runtime = m.runtime ?? "pty";
+    // The open-mesh refusal must be RE-STATED here, not only against the CLI `--open` flag: on this
+    // path openness comes from the MANIFEST (`broker.auth: false`), which the flag-level guard cannot
+    // see. Without it, `cotal up -f open.yaml --rotate-sys` boots an open broker, exits 0 and rotates
+    // nothing: a rotation ask answered with silent success, the exact failure class this change
+    // exists to remove. Before the dry-run print and before anything boots.
+    if (opts.rotateSys && open)
+        throw new Error("--rotate-sys is for auth meshes: this manifest sets broker.auth: false (open), so there is no system account or $SYS credentials to rotate");
     if (opts.dryRun) {
+        // Dial-host SAN must refuse here too (S6). The real route runs assertServesDialHost after
+        // the plan is computed; dry-run used to return before that check and green-lit a launch
+        // the applying command refuses. Validate against the effective server; still no writes.
+        // Announce only AFTER the dial-host check so a wrong-SAN dry-run does not print TLS: serving.
+        assertServesDialHost(opts.transport, new URL(server).hostname);
+        if (opts.transport.kind === "tls-required")
+            announceTransport(opts.transport);
         console.log(renderUpPlan(eff, server));
         return;
     }
@@ -1332,7 +1526,10 @@ async function upManifest(file, opts) {
     if (userAuth) {
         try {
             mkdirSync(cotalPath("nats"), { recursive: true });
-            const setup = await authSetup(cotalPath("nats"), server, m.space, host, userAuth);
+            // NO `rotateSys` here on purpose: this is an owner-derivation pre-resolve that runs BEFORE the
+            // real boot, and the boot below carries the flag. Rotating in both would burn two generations
+            // per `up -f --rotate-sys` and retire the account the first pass just minted creds against.
+            const setup = await authSetup(cotalPath("nats"), server, m.space, host, userAuth, assertServesDialHost(opts.transport, new URL(server).hostname));
             owner = await resolveAuthProvider().ownerForLogin({ store: workspaceSecretStore(cotalRoot()), dir: setup.stateDir, space: m.space });
         }
         catch (e) {
@@ -1350,19 +1547,20 @@ async function upManifest(file, opts) {
     // A leftover detached manager (its broker is gone — the reachability check above proved nothing
     // lives at this address) would win the fresh mesh's lease and the launch manager would refuse.
     // Stop it, so the manager started below WITH the launch spec is THE manager.
-    stopManager();
+    await stopManager();
     let pid;
     let controlPlane = false;
     let authService = true;
     try {
         // `m.broker?.host`, not the defaulted `host`: same reason as the flag path — only a host the
         // manifest actually declared is an exposure decision worth persisting.
-        ({ pid, controlPlane, authService } = await startMeshDetached({ server, space: m.space, open, userAuth, host: m.broker?.host, seed: manifestToChannels(eff), runtime, launch: specPath }));
+        ({ pid, controlPlane, authService } = await startMeshDetached({ transport: opts.transport, server, space: m.space, open, userAuth, rotateSys: opts.rotateSys, host: m.broker?.host, seed: manifestToChannels(eff), runtime, launch: specPath }));
     }
     catch (e) {
         console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
+    // Transport committed inside startMeshDetached before delivery (S5+S9).
     console.log(c.green(`✓ mesh "${m.space}" up at ${server}`) + c.dim(` (broker pid ${pid})`));
     console.log(c.dim(`  seeded ${m.channels.length} channel(s): ${m.channels.map((ch) => "#" + ch.name).join(", ")}`));
     // Never claim a launch the control plane can't deliver: the manager carries the launch spec, so a
@@ -1418,7 +1616,12 @@ function applyUpOverrides(prepared, o) {
  *  caller whose output claims a manager (the `up -f` launching line) can tell the truth. */
 async function startDeliveryWithBroker(space, server, mgr) {
     try {
-        await ensureControlPlane({ space, server, ...mgr });
+        // Prefer the in-memory decision for a fresh apply (policy may not be on disk yet — S9).
+        // Fall back to the recorded policy for resume/restore/refresh paths that start no new listener.
+        const tls = mgr?.transport?.kind === "tls-required" ||
+            readBrokerPolicy(cotalRoot())?.transport.kind === "tls-required";
+        const { transport: _t, ...mgrRest } = mgr ?? {};
+        await ensureControlPlane({ space, server, tls, ...mgrRest });
         return true;
     }
     catch (e) {
@@ -1436,9 +1639,17 @@ async function startDeliveryWithBroker(space, server, mgr) {
  * log file and forwarded — the child writes to the file (not a pipe), so it survives the
  * parent exiting.
  */
-export async function startMeshDetached(opts = {}) {
+export async function startMeshDetached(
+// The `= {}` default is gone with the optional transport: an options object that can be omitted
+// entirely cannot carry a mandatory decision.
+opts) {
     const server = opts.server ?? DEFAULT_SERVER;
     const useAuth = !opts.open;
+    // Belt on the one boot that both renders the broker config and can be reached by any caller: an
+    // open boot skips `authSetup` entirely, so a `rotateSys` arriving here would be dropped in silence
+    // rather than refused. Callers guard this too; this is the seam that cannot be bypassed.
+    if (opts.rotateSys && !useAuth)
+        throw new Error("startMeshDetached: --rotate-sys is for auth meshes; an open mesh has no system account or $SYS credentials to rotate");
     const space = opts.space ?? resolveSpace(process.cwd());
     ensureRootForSpace(useAuth, space); // may pin the cwd as this space's root — before any cotalPath use
     refuseOpenOverUserState(Boolean(opts.open), space);
@@ -1447,10 +1658,17 @@ export async function startMeshDetached(opts = {}) {
     await claimSpace(space, server, cotalRoot());
     const seedFile = opts.seed ?? loadChannelsFile(opts.channels);
     const host = opts.host ?? "127.0.0.1";
-    const setup = useAuth ? await authSetup(storeDir, server, space, host, opts.userAuth) : undefined;
+    // The transport arrives decided. The dial-host SAN is re-checked here because THIS is where the
+    // effective server is finally known — a manifest may name a different host than the flags did, and
+    // a certificate that is valid for one is not thereby valid for the other.
+    const transport = assertServesDialHost(opts.transport, new URL(server).hostname);
+    const setup = useAuth ? await authSetup(storeDir, server, space, host, opts.userAuth, transport, opts.rotateSys) : undefined;
     const port = Number(new URL(server).port) || 4222;
+    // Same rule as the foreground path: every route to a listener names its transport (see
+    // `writeOpenBrokerConf`). Detach must not be the mode where the fence quietly does not apply.
+    const confPath = setup ? setup.confPath : writeOpenBrokerConf(storeDir, { port, host, transport });
     const args = [
-        ...(setup ? ["-c", setup.confPath] : ["-js", "-sd", storeDir, "-p", String(port), "-a", host]),
+        "-c", confPath,
         ...(opts.boundListener ? ["--name", opts.boundListener.serverName] : []),
     ];
     const { bin, source } = await resolveNatsServer();
@@ -1489,8 +1707,37 @@ export async function startMeshDetached(opts = {}) {
         writeFileSync(cotalPath("nats.pid"), String(child.pid));
     if (opts.boundListener)
         await opts.boundListener.verify();
-    if (!opts.skipPostStart)
-        await postStart(server, space, setup, seedFile);
+    // POST-START MUST NOT LEAVE AN ORPHAN LISTENER.
+    //
+    // Everything above has already bound the port and written `nats.pid`, but NOTHING has recorded the
+    // mesh yet — `recordOurMesh` is below. So a throw between here and there used to exit non-zero
+    // while leaving a live broker holding the port with no registry entry, which `cotal down` cannot
+    // reach because `down` works from the registry. A third state between "started" and "refused",
+    // and the operator's only recourse is to hunt a pid.
+    //
+    // This is reachable BECAUSE of TLS and cannot happen on `main`: the post-start client verifies the
+    // certificate, so a private CA without `NODE_EXTRA_CA_CERTS` fails here — after the listener is up.
+    // The feature introduced the state, so the feature tears it down.
+    //
+    // Deliberately narrow: this is a teardown on the failure path, not a restructuring of the launch
+    // sequence. The listener is stopped and the pid file removed, then the original error is rethrown
+    // unchanged — the operator needs the certificate error, not a message about cleanup.
+    if (!opts.skipPostStart) {
+        try {
+            await postStart(server, space, setup, seedFile);
+        }
+        catch (e) {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch { /* already gone */ }
+            try {
+                rmSync(cotalPath("nats.pid"), { force: true });
+            }
+            catch { /* best effort */ }
+            throw e;
+        }
+    }
     // USER MODE: the auth service comes up FIRST among the daemons (see the foreground path).
     const svc = await startUserAuthService(space, server, setup);
     // Record BEFORE the control plane: the manager's fail-closed mode detection needs the
@@ -1503,11 +1750,17 @@ export async function startMeshDetached(opts = {}) {
     recordOurMesh({
         space, server, root: cotalRoot(),
         mode: setup?.prepared ? "user" : useAuth ? "auth" : "open",
+        // The detached listener is started from `transport` a few lines above, so this is the same
+        // decision that shaped the config file — not a re-derivation.
+        tlsRequired: transport.kind === "tls-required",
         ...(svc.userAuth ? { userAuth: svc.userAuth } : {}),
         // Persist only a real decision — declared now, or carried forward — never the loopback default.
         ...(effectiveAttachHost ? { attachHost: effectiveAttachHost } : {}),
         ts: new Date().toISOString(),
     }, "started");
+    // Commit policy BEFORE delivery launch (S9). Listener is proved; refuse paths never reach here.
+    // startDeliveryWithBroker also receives `transport` so it does not depend on the file alone.
+    commitTransportPolicy(cotalRoot(), transport);
     // Bring up the delivery daemon WITH the detached broker (auth mode only; `cotal down` tears both down).
     const controlPlane = await startDeliveryWithBroker(space, server, {
         runtime: opts.runtime,
@@ -1516,6 +1769,8 @@ export async function startMeshDetached(opts = {}) {
         attachHost: effectiveAttachHost,
         resumeAttempt: opts.resumeAttempt,
         resumeCommitToken: opts.resumeCommitToken,
+        transport,
+        wsPort: setup?.wsPort, // P2 item 6: the console session client's broker ws port
     });
     return {
         server,
@@ -1539,28 +1794,42 @@ function refuseOpenOverUserState(open, space) {
     const stateDir = userAuthStateDir(cotalRoot(), space);
     throw new Error(`space "${space}" has user auth enabled (state under ${stateDir}) - \`--open\` would serve its streams without auth. Start it with \`cotal up --user-auth\`, or remove that directory deliberately to disable user auth (existing logins/grants die with it)`);
 }
-/** Today a root's `.cotal/auth` is created for one space (its account is space-bound), so an
- *  explicit `--space` naming a different space cannot run against this root's trust material — the
- *  registry would point a `spawn --space` at mismatched creds. A mismatch only exists when
- *  `--space` was given (the default IS this root's space): clear intent for a different mesh. When
- *  the root was merely inherited from an ancestor folder (the cwd has no `.cotal` of its own),
- *  honor that intent — make the cwd the new space's own root. Only a folder that itself holds the
- *  other space's material refuses. (When multi-space-per-root lands, that refusal becomes
- *  provision-the-new-space instead.) */
-function ensureRootForSpace(useAuth, space) {
-    if (!useAuth)
-        return;
+/** Pin cwd as its own mesh root when the nearest ancestor root already belongs to a DIFFERENT
+ *  space — mode-independent.
+ *
+ *  Auth path: a root's `.cotal/auth` is space-bound, so an explicit `--space` naming another space
+ *  cannot share that trust material. Open path: the same ancestor still owns policy, store, pid
+ *  and MeshEntry; reusing it for a second space collides those (S4 open arm — child `--open --tls-*`
+ *  wrote the parent's broker-policy and nats.pid while a second broker shared the JetStream store).
+ *
+ *  A mismatch only exists when the resolved space differs from what the ancestor already hosts.
+ *  When the root was merely inherited (cwd has no `.cotal`), honor the new-space intent by making
+ *  cwd its own root. Only a folder that itself holds the other space's material refuses.
+ *  (When multi-space-per-root lands, that refusal becomes provision-the-new-space instead.) */
+function ensureRootForSpace(_useAuth, space) {
     const root = cotalRoot();
-    const existing = loadSoleSpaceAuth(authDir(root));
-    if (!existing || existing.space === space)
-        return;
     const cwd = process.cwd();
+    // What space does this root already host? Prefer auth material; fall back to a live MeshEntry
+    // whose root is this directory (open meshes have no auth dir).
+    const existingAuth = loadSoleSpaceAuth(authDir(root));
+    const existingSpace = existingAuth?.space ??
+        loadMeshes().find((m) => m.root === root || realpathSafe(m.root) === realpathSafe(root))?.space;
+    if (!existingSpace || existingSpace === space)
+        return;
     if (root !== cwd) {
         mkdirSync(join(cwd, ".cotal"), { recursive: true });
-        console.log(c.dim(`nearest mesh root ${root} is space "${existing.space}" - making this folder its own root for "${space}"`));
+        console.log(c.dim(`nearest mesh root ${root} is space "${existingSpace}" - making this folder its own root for "${space}"`));
         return;
     }
-    throw new Error(`this folder is the root of space "${existing.space}" (${authDir(root)}), so it can't also run "${space}" - drop \`--space\` to run "${existing.space}", or start "${space}" from a different folder (it becomes that mesh's own root)`);
+    throw new Error(`this folder is the root of space "${existingSpace}" (${root}/.cotal), so it can't also run "${space}" - drop \`--space\` to run "${existingSpace}", or start "${space}" from a different folder (it becomes that mesh's own root)`);
+}
+function realpathSafe(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
 }
 /** A space name maps to one mesh in the registry (the key `--space`/`use`/`down` act on). Before
  *  starting a broker, refuse to reuse a space already claimed by a DIFFERENT live mesh — a stale/dead
@@ -1745,8 +2014,219 @@ function loadChannelsFile(explicit) {
  *  SPACE-SCOPED state dir (`.cotal/auth/<space>/` — the multi-space-ready layout; nothing user-auth
  *  lives flat) and preload its extra account(s) into the broker config. The inverse is fail-closed:
  *  a space whose user-auth state exists MUST keep being started with --user-auth — regenerating the
- *  config without the callout account would silently break every sentinel connect. */
-async function authSetup(storeDir, server, space, host = "127.0.0.1", user) {
+ *  config without the callout account would silently break every sentinel connect.
+ *
+ *  `rotateSys` (`cotal up --rotate-sys`) is the class-3 renewal for an EXISTING space: rotate the
+ *  system account, re-mint `membership-observer.creds` + `connection-evictor.creds` against the
+ *  successor, and render the config from the ROTATED record so the broker this `up` starts is the one
+ *  that trusts them. It belongs here because this is the single site that both owns the trust record
+ *  and renders `server.conf`; anywhere else would publish creds the live broker cannot honor. */
+/**
+ * Turn the `--tls-cert`/`--tls-key` pair into a validated {@link BrokerTransport}, or `plaintext`
+ * when neither was given.
+ *
+ * REFUSES BEFORE LAUNCH, never after. Everything it rejects would otherwise become a running broker
+ * in some wrong state, and the two failure modes are not symmetrical: a broker that will not start
+ * is an operator reading an error, while a broker that starts wrong is an operator believing they
+ * have TLS. So the validation is deliberately ours and deliberately early.
+ *
+ * `validateTlsMaterial` does the substantive checks — readability, private-key mode, PEM pair
+ * match, validity window, dial-host SAN — because nats-server's are not sufficient. Missing,
+ * unreadable and mismatched pairs do stop it before it opens a listener, but an EXPIRED certificate
+ * does not: it reports the config valid, starts, logs "Server is ready" and "TLS required", and
+ * only the client then fails. An expired cert must never yield "mesh up".
+ *
+ * @param dialHost the hostname clients will verify against, which is NOT the bind host — a broker
+ *                 may bind `0.0.0.0` while clients dial `broker.example`.
+ */
+function resolveTransport(values, dialHost, root, 
+/** `persist` defaults false (commit-after-apply). `quiet` suppresses serving/inheriting lines
+ *  until the caller announces after a successful apply. */
+opts = {}) {
+    const certFile = values["tls-cert"], keyFile = values["tls-key"];
+    const quiet = opts.quiet === true;
+    // NO FLAGS: inherit the RECORDED decision rather than defaulting to plaintext. This is the half
+    // that makes a bare `cotal up` after a `cotal down` keep serving TLS. Without it the decision
+    // lives only in the argv of whichever invocation first made it, and the most ordinary operator
+    // gesture there is - stop the mesh, start it again - silently downgrades a broker that was
+    // deliberately put on TLS. `readBrokerPolicy` refuses rather than degrading if the recorded
+    // material has gone missing, so a moved cert fails loud here instead of coming up in cleartext.
+    if (!certFile && !keyFile) {
+        let recorded;
+        try {
+            recorded = readBrokerPolicy(root);
+        }
+        catch (e) {
+            console.error(c.red(`✗ ${e instanceof Error ? e.message : String(e)}`));
+            process.exit(1);
+        }
+        if (recorded?.transport.kind === "tls-required") {
+            if (!quiet)
+                console.log(c.dim("TLS: inheriting the recorded broker policy (no --tls-cert/--tls-key given)"));
+            return validateRecorded(recorded.transport, dialHost, { quiet });
+        }
+        return { kind: "plaintext" };
+    }
+    // Half a pair is a mistake, never a configuration. Refusing names the missing half rather than
+    // failing later inside nats-server with a message about a file the operator did not mention.
+    if (!certFile || !keyFile) {
+        console.error(c.red(`✗ --tls-cert and --tls-key must be given together (missing ${certFile ? "--tls-key" : "--tls-cert"})`));
+        process.exit(1);
+    }
+    const transport = { kind: "tls-required", certFile: resolve(certFile), keyFile: resolve(keyFile) };
+    const validated = validateRecorded(transport, dialHost, { quiet });
+    // RECORD only when the caller has already applied the transport (started a matching listener).
+    // Eager write here is S5: a refuse path cannot unwrite, and the next bare up inherits fiction.
+    if (opts.persist === true)
+        writeBrokerPolicy(root, { version: 1, transport: validated });
+    return validated;
+}
+/** Persist + announce a transport that has been APPLIED (listener started and proved). */
+function commitTransportPolicy(root, transport) {
+    if (transport.kind !== "tls-required")
+        return;
+    writeBrokerPolicy(root, { version: 1, transport });
+    announceTransport(transport);
+}
+function announceTransport(transport) {
+    if (transport.kind !== "tls-required")
+        return;
+    try {
+        const material = validateTlsMaterial(transport, {});
+        console.log(c.dim(`TLS: serving ${material.subject}, valid until ${material.notAfter.toISOString()}`));
+    }
+    catch {
+        // Already validated at decide-time; announce is best-effort display.
+    }
+}
+/** Read the live INFO greeting and report whether the listener requires TLS.
+ *  `undefined` means no usable INFO (timeout / closed) — caller treats as unknown. */
+async function liveListenerRequiresTls(server, timeoutMs = 2000) {
+    let host;
+    let port;
+    try {
+        const u = new URL(server);
+        host = u.hostname || "127.0.0.1";
+        port = Number(u.port) || 4222;
+    }
+    catch {
+        return undefined;
+    }
+    return await new Promise((res) => {
+        const sock = createConnection({ host, port });
+        let buf = "";
+        const done = (v) => {
+            try {
+                sock.destroy();
+            }
+            catch { /* */ }
+            res(v);
+        };
+        sock.setTimeout(timeoutMs, () => done(undefined));
+        sock.on("error", () => done(undefined));
+        sock.on("close", () => done(undefined));
+        sock.on("data", (d) => {
+            buf += d.toString("utf8");
+            const nl = buf.indexOf("\r\n");
+            if (nl < 0)
+                return;
+            const line = buf.slice(0, nl);
+            try {
+                const info = JSON.parse(line.replace(/^INFO\s+/, ""));
+                done(info.tls_required === true);
+            }
+            catch {
+                done(undefined);
+            }
+        });
+    });
+}
+/**
+ * Re-assert that `transport` is valid for the host clients will actually dial, and exit loudly if
+ * not. A no-op for plaintext.
+ *
+ * This exists because the transport is decided ONCE, early, before the route is known, so that no
+ * route can be reached without one — but the effective dial host is decided LATE and differs per
+ * route: a manifest may set `broker.host`, and a certificate valid for the flag-derived host is not
+ * thereby valid for that one. Deciding early and checking late is the only ordering that satisfies
+ * both, so the check is deliberately separate from the decision rather than folded into it.
+ *
+ * Quiet on success: `resolveTransport` already printed what is being served, and a second identical
+ * line reads like a second broker.
+ */
+function assertServesDialHost(transport, dialHost) {
+    if (transport.kind !== "tls-required" || dialHost === undefined)
+        return transport;
+    try {
+        validateTlsMaterial(transport, { dialHost });
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+    }
+    return transport;
+}
+/**
+ * The client-side TLS requirement to persist for a listener THIS PROCESS DID NOT START — the
+ * restore and ordinary-resume paths, which adopt a broker that is already listening.
+ *
+ * They have no `transport` in scope because they never decided one, so the honest source is the
+ * recorded policy: the listener they are adopting was started from it. Reading it here is what stops
+ * a resume from writing a registry entry that says "plaintext" over a broker serving TLS — clients
+ * resolved from that entry would then connect without requiring it, which is the downgrade this
+ * feature exists to prevent, arriving by way of a recovery path rather than a launch.
+ *
+ * Fails loud on an unusable policy for the same reason `resolveTransport` does: a resume that cannot
+ * tell what it is adopting must not guess.
+ */
+function adoptedTlsRequired(root) {
+    try {
+        return readBrokerPolicy(root)?.transport.kind === "tls-required";
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+    }
+}
+/** Validate a TLS pair and exit loudly on anything wrong. Shared by the flag path and the
+ *  recorded-policy path so a cert that rots on disk is caught on the NEXT `up`, not only on the
+ *  one that first configured it. */
+function validateRecorded(transport, dialHost, opts = {}) {
+    try {
+        const material = validateTlsMaterial(transport, dialHost !== undefined ? { dialHost } : {});
+        if (!opts.quiet)
+            console.log(c.dim(`TLS: serving ${material.subject}, valid until ${material.notAfter.toISOString()}`));
+    }
+    catch (e) {
+        // Surface the CERTIFICATE cause. A TLS failure reported as a generic startup error invites the
+        // wrong remedy - operators go looking at ports and firewalls when the answer is the cert.
+        console.error(c.red(`✗ ${e instanceof Error ? e.message : String(e)}`));
+        process.exit(1);
+    }
+    return transport;
+}
+/**
+ * Render and write the config for an OPEN (no-auth) broker, returning its path.
+ *
+ * The `authSetup` sibling for the no-auth mode. Open mode previously launched nats-server from
+ * bare CLI flags and so never passed through any renderer — meaning the REQUIRED transport union
+ * on the config renderers covered the auth path only, and a `--tls-cert`/`--tls-key` pair given to
+ * an open-mode `up` would have been accepted while the broker came up in cleartext. Routing open
+ * mode through a renderer is what makes the union total: there is now no route to a listener that
+ * does not state its transport.
+ */
+function writeOpenBrokerConf(storeDir, opts) {
+    const confPath = resolve(storeDir, "..", "server-open.conf");
+    writeFileSync(confPath, openServerConfig({ port: opts.port, host: opts.host, storeDir, transport: opts.transport }));
+    return confPath;
+}
+async function authSetup(storeDir, server, space, host = "127.0.0.1", user, 
+// NON-OPTIONAL, and it used to default to `{ kind: "plaintext" }`. That default was the hole: the
+// manifest path called this with five arguments and silently got a cleartext listener while the
+// operator's `--tls-cert` sat validated and unused. A default here cannot be right, because the
+// safe value and the common value are different values — every caller knows its transport, and
+// the one that does not is the one that must not compile.
+transport, rotateSys = false) {
     const dir = authDir(cotalRoot()); // the broker config (server.conf) still lands under the FS auth dir
     const store = workspaceSecretStore(cotalRoot());
     let auth = await getSpaceAuth(store, space);
@@ -1754,7 +2234,58 @@ async function authSetup(storeDir, server, space, host = "127.0.0.1", user) {
         auth = await createSpaceAuth(space);
         await putSpaceAuth(store, auth); // strips the $SYS seed at rest, but leaves the in-memory `auth` intact …
         await provisionMembershipCreds(auth, cotalRoot()); // … so the observer can still be minted here (fresh-space only)
-    }
+        // A fresh space's $SYS material was just minted from the seed that only exists in this branch, so
+        // the ASK is already satisfied, so say so rather than rotating a one-second-old account, and never
+        // report a rotation that did not happen.
+        if (rotateSys)
+            console.log(c.dim("• --rotate-sys: this space is new, so its $SYS creds were just minted - nothing to rotate"));
+    }
+    else if (rotateSys) {
+        // Third and last of the stopped-broker checks, at the one point every rotation path converges on.
+        // The other two live in `up`'s reachable-listener branch: this root's recorded mesh at the
+        // requested address, and any UNIDENTIFIED listener there (which refuses rather than free-porting
+        // around a broker that may be serving this root's own server.conf and store). This one reads the
+        // root's ownership records for a broker at an address nobody probed. It reports what those
+        // records say, not what the process table says (see its own comment for the residual), and fails
+        // CLOSED, so an ambiguous record refuses exactly like a live one.
+        await assertRootBrokerStopped(cotalRoot());
+        // Fails loud: a caller that swallowed this would boot the broker on the RETIRED system account
+        // while `doctor auth` reported the rotation as done.
+        const rot = await rotateSystemCreds(cotalRoot(), space);
+        auth = rot.auth; // the config below MUST be rendered from the successor, never the pre-rotation copy
+        console.log(c.green(`✓ rotated the system account for "${space}"`) +
+            c.dim(` (generation ${rot.gen}) - re-minted ${SYSTEM_CREDS_FILES.join(" + ")}${rot.expiresAt ? `, valid to ${new Date(rot.expiresAt * 1000).toISOString().slice(0, 10)}` : ""}`));
+        // Say exactly what is true. The retirement is CONFIG-LOAD-BOUND: an old cred dies against any
+        // broker that loads the successor config, which is every broker started from this root from here
+        // on, but a stale nats-server still holding the pre-rotation config in memory would keep
+        // honoring it, so "now dead" without that qualifier oversells the guarantee.
+        console.log(c.dim("  the data account, every agent cred and the JetStream store are untouched. The OLD $SYS creds are refused by any broker that loads this config; a stale broker still running the previous config would still honor them, so stop those first."));
+        // A full backup binds to the trust chain it was taken against: `rootChainCommitment` hashes the
+        // operator JWT and the system account, both of which just changed, so `cotal up --restore`
+        // refuses every full artifact taken before this moment. That is correct (it is a different trust
+        // root), but it is only obvious to someone who has read the fingerprint code, and rotation is
+        // now a routine 30-day act rather than a once-per-space event. Say it at the moment it becomes
+        // true, not in a doc the operator reads after the restore has already failed.
+        console.log(c.dim("  NOTE: full backups taken before this rotation can no longer be restored (they are bound to the retired trust chain) - take a fresh `cotal backup` once the mesh is up."));
+    }
+    // The $SYS creds must be signed by the system account THIS boot is about to put in `server.conf`.
+    // A rotation that committed the trust record and then died leaves them stale, unexpired, and
+    // broker-dead and, crash-before-either-write, stale in a way that no comparison between the two
+    // FILES can see (they agree with each other; they just disagree with the record). This is the one
+    // place holding both, on the one path that renders the config, so it is where the split is caught.
+    //
+    // REFUSE, do not warn. A warning is what the `--detach` path turns into an unread log line under a
+    // green "✓ running in the background", which is the false success this whole change exists to
+    // remove. And what stays broken is not only the display feed: live connection EVICTION rides the
+    // same pair, so booting here would silently downgrade revocation to deny-new for the life of the
+    // mesh. The repo's posture is to throw rather than degrade, and the recovery is one command that
+    // this message names.
+    const stale = staleSystemCreds(cotalRoot(), auth.sys.pub);
+    if (stale.length)
+        throw new Error(`${stale.map((x) => `${x.file} (signed by ${x.iss ? `${x.iss.slice(0, 12)}…` : "an unreadable issuer"})`).join(", ")} ` +
+            `${stale.length === 1 ? "is" : "are"} not signed by this space's system account (${auth.sys.pub.slice(0, 12)}…) - ` +
+            "an interrupted rotation left the $SYS creds behind the trust record, so the broker would deny them and live eviction + the membership feed would stay down. " +
+            "Re-run the rotation to land a complete generation: `cotal up --rotate-sys`");
     const stateDir = userAuthStateDir(cotalRoot(), space); // the provider's space-scoped state dir
     if (!user && hasUserAuthState(cotalRoot(), space)) {
         throw new Error(`space "${space}" has user auth enabled (state under ${stateDir}) - start it with \`cotal up --user-auth\`, or remove that directory deliberately to disable user auth (existing logins/grants die with it)`);
@@ -1780,13 +2311,73 @@ async function authSetup(storeDir, server, space, host = "127.0.0.1", user) {
         }
     }
     const port = Number(new URL(server).port) || 4222;
+    // P2 item 6: allocate the broker's loopback WebSocket listener port — the console page becomes a
+    // mesh §13.6 session client over it (a NEW same-host attack surface, localhost-bound, no TLS). The
+    // manager's establisher builds its wsUrl from this; threaded to `supervise --ws-port`.
+    const wsPort = await freePort(host);
     const confPath = resolve(dir, "server.conf");
-    writeFileSync(confPath, serverConfig(auth, [auth], { port, storeDir, host, ...(prepared ? { extraAccounts: prepared.extraAccounts } : {}) }));
+    writeFileSync(confPath, serverConfig(auth, [auth], { transport, port, storeDir, host, wsPort, wsHost: host, ...(prepared ? { extraAccounts: prepared.extraAccounts } : {}) }));
     // Ephemeral setup cred: used only to probe reachability, pre-create the space streams/buckets
     // (setupSpaceStreams) and seed the channel registry (seedChannelRegistry) — all within the
     // enumerated `provisioner` scope. No broad `manager` residual for the up path.
     const creds = await mintCreds(auth, newIdentity(), "provisioner");
-    return { confPath, creds, ...(prepared ? { prepared, stateDir } : {}) };
+    return { confPath, creds, wsPort, ...(prepared ? { prepared, stateDir } : {}) };
+}
+/**
+ * Refuse the rotation if this root's own bookkeeping still shows a broker running. This is a
+ * BEST-EFFORT check over Cotal-managed ownership records, NOT a proof that no process is serving this
+ * root, and the difference matters: a survivor keeps honoring the retired account from memory, and a
+ * second broker on the successor opens that survivor's JetStream store underneath it.
+ *
+ * Two records, because either alone has a blind spot. The PID FILE catches a broker this root started
+ * whose registry row was lost. The REGISTRY sweep catches one recorded for this root at some OTHER
+ * address, which no probe of the requested URL would reach. Both fail CLOSED: an unreadable or
+ * malformed pid file refuses exactly like a live one, since "cannot tell" and "still running" have
+ * the same consequence.
+ *
+ * WHAT IT CANNOT SEE, stated because an earlier version of this comment claimed otherwise: both
+ * records are mutable, and neither is written by a broker started outside `cotal up`. Delete both
+ * while the process lives, or run `nats-server -c <root>/.cotal/auth/server.conf` by hand, and this
+ * returns success having probed nothing. The requested address is covered separately (an unidentified
+ * listener there refuses the rotation rather than moving to a free port), which leaves a hand-started
+ * broker on a DIFFERENT port as the honest residual. Closing that needs something a survivor holds
+ * and cannot delete, an exclusive store lock, which does not exist today; until it does, do not run
+ * `nats-server` against this root's config outside `cotal up`.
+ *
+ * Not a general `up` guard: an ordinary boot adopting or replacing a listener is a supported flow with
+ * its own claim machinery. This is specifically the precondition for retiring an authority.
+ */
+async function assertRootBrokerStopped(root) {
+    const pidPath = join(root, ".cotal", "nats.pid");
+    if (existsSync(pidPath)) {
+        let raw;
+        try {
+            raw = readFileSync(pidPath, "utf8").trim();
+        }
+        catch (e) {
+            throw new Error(`--rotate-sys: ${pidPath} exists but cannot be read (${e.message}) - refusing to rotate while a broker for this root may still be running; \`cotal down\` first`);
+        }
+        const pid = Number(raw);
+        if (!Number.isInteger(pid) || pid <= 0)
+            throw new Error(`--rotate-sys: ${pidPath} does not hold a pid (${JSON.stringify(raw)}) - refusing to rotate while a broker for this root may still be running; \`cotal down\` first`);
+        let live;
+        try {
+            process.kill(pid, 0); // signal 0 is a liveness probe, it signals nothing
+            live = true;
+        }
+        catch (e) {
+            // EPERM means the process EXISTS and is not ours to signal, i.e. alive for this purpose.
+            live = e.code === "EPERM";
+        }
+        if (live)
+            throw new Error(`--rotate-sys: this root's broker is still running (pid ${pid}) - it would keep serving the retired system account, and a second broker would share its JetStream store. Stop it first: \`cotal down\``);
+    }
+    // A broker recorded for this root at ANY address, still answering. The rotate refusal earlier in
+    // `up` only sees the URL this invocation asked for; this sees the ones it did not.
+    for (const m of meshesForRoot(root)) {
+        if (await isReachable(m.server))
+            throw new Error(`--rotate-sys: mesh "${m.space}" for this root is still reachable at ${m.server} - stop it first (\`cotal down\`), then rotate`);
+    }
 }
 /** Mint the two scoped creds the delivery daemon's membership feed loads (broker-sourced graph
  *  membership), at the FRESH `cotal up` while the in-memory `$SYS` signing seed still exists:
@@ -1815,9 +2406,9 @@ async function provisionMembershipCreds(auth, root) {
         // deny-new-only (durable reauth) — surfaced loudly by the removal path, never silent.
         const evictor = await mintConnectionEvictorCreds(auth, newIdentity());
         mkSecretDir(cotalPath()); // harden .cotal/ before the creds land (born under a private ACL, no race)
-        writeSecretFile(cotalPath("membership-observer.creds"), observer);
+        writeSecretFile(cotalPath(SYSTEM_CREDS_FILES[0]), observer);
         await workspaceSecretStore(root).put(MEMBERSHIP_RW_CREDS_KEY, rw); // migrated kind: through the seam (0600 FS put)
-        writeSecretFile(cotalPath("connection-evictor.creds"), evictor);
+        writeSecretFile(cotalPath(SYSTEM_CREDS_FILES[1]), evictor);
         writeSecretFile(cotalPath("membership.json"), JSON.stringify({ accountId: auth.account.pub }));
     }
     catch (e) {