big cli/tui gaps project

1 files changed, 9 insertions, 0 deletions

diff --git a/src/extension_loader.zig b/src/extension_loader.zig
index 1c29ceb..25c01e3 100644
--- a/src/extension_loader.zig
+++ b/src/extension_loader.zig
@@ -32,6 +32,15 @@
 //!      policy), call `entry.activate()`.
 //!
 //! Symlinks: followed normally. Dotfiles and `_`-prefixed files: skipped.
+//!
+//! ## Lifetime contract (extension authors, read this)
+//!
+//! The Lua state lives exactly as long as the session. `/new` and `/resume`
+//! tear the interpreter down and boot a fresh one through this same loader —
+//! entry evaluation and `activate()` run again, against the new session's
+//! agent. Module-global registries and other Lua-side state are therefore
+//! per-session by construction; nothing survives a session switch except
+//! what an extension itself persisted outside the VM.
 
 const std = @import("std");
 const panto = @import("panto");