Merge nucleic/calm-harbor-lynx into dev

Sources/NucleicCore/SessionController.swift

@@ -384,11 +384,15 @@ public actor SessionController {
             only on your own disposable VM, so they need NO approval. IMPORTANT — VMs are a scarce, \
             hard-capped resource: at most \(maxConcurrentVMs) can run concurrently across ALL agents, \
             so a VM you leave running idle blocks other agents (and your own later work) from booting \
-            one, and a fresh boot fails outright once the cap is hit. So the moment you're done with \
-            the Mac for this stretch of work, free the slot yourself: `suspend` it if you'll likely \
-            need it again soon (fast thaw, keeps state) or `stop` it if you're done for a while (frees \
-            RAM; a later command reboots it). Don't hold a VM you're not actively using. It's also \
-            torn down for you at session end, and `restart`/`kill` reset a wedged VM mid-session.
+            one, and a fresh boot fails outright once the cap is hit. NEVER leave a VM running that \
+            you are not actively using. The moment you finish a stretch of Mac work — even if you \
+            expect to come back to it in a few turns — `suspend` it. Suspend is the default: it \
+            freezes the VM in RAM, keeps all its state, and thaws in seconds. When you need the Mac \
+            again, `resume` it (or just issue any VM command, which auto-resumes) and pick up where \
+            you left off. Reach for `stop` only when you're done with the Mac for a long while and \
+            want its RAM back; a later command reboots it, losing in-VM state. Suspending between \
+            uses costs you almost nothing and is what keeps a slot free for other agents. The VM is \
+            also torn down for you at session end, and `restart`/`kill` reset a wedged VM mid-session.
             """ : ""
         // Agent-created containers: the lightest isolation, cheaper than any VM. Introduced before the
         // Linux-VM block so the ladder reads container → Linux VM → macOS VM.
@@ -428,10 +432,12 @@ public actor SessionController {
             You can manage that Linux VM's lifecycle with `linux_vm_control` — the sibling of \
             `mac_vm_control`, same ops (`status`, `stop`, `suspend`, `resume`, `restart`, `kill`) \
             acting on your own disposable Linux VM, no approval needed. The same scarcity rule \
-            applies: at most \(maxConcurrentVMs) VMs run concurrently across all agents, so `suspend` \
-            it (if you'll need it again soon) or `stop` it (if you're done for a while) the moment \
-            you finish with it — don't leave it running idle and blocking other agents. It's torn \
-            down for you at session end; `restart`/`kill` reset it mid-session.
+            applies: at most \(maxConcurrentVMs) VMs run concurrently across all agents, so NEVER \
+            leave one running that you aren't actively using. `suspend` it the moment you finish a \
+            stretch of work — that's the default, it keeps state and thaws in seconds — then `resume` \
+            it (or just issue any VM command, which auto-resumes) when you come back. Reach for \
+            `stop` only when you're done for a long while and want the RAM back. It's torn down for \
+            you at session end; `restart`/`kill` reset it mid-session.
             """ : ""
         // The escalation ladder — a short policy that ties the rungs together, naming only the tools
         // actually exposed this run so it never points the agent at an unavailable tool.