diff --git a/init.lua b/init.lua
index cd43e69..990dc69 100644
--- a/init.lua
+++ b/init.lua
@@ -1287,4 +1287,18 @@ function init(ctx)         M.init(ctx)        end
 function update(ctx, dt)   M.update(ctx, dt)  end
 function render(ctx)       M.draw(ctx)        end
 
+-- Debug-drive hook (headless/agent testing): when SPOREL_DEBUG_DRIVE is set,
+-- expose the module state + the crafting/inventory/composition lib instances as
+-- a global so lua.eval scenarios can reach the backpack, world items, and the
+-- crafting API. `state` is a live table reference — its handles get populated in
+-- M.init, so reads after init see the real entities. No-op in normal runs.
+if os.getenv("SPOREL_DEBUG_DRIVE") then
+    _G.__vagrant = {
+        state       = state,
+        crafting    = crafting,
+        inventory   = inventory,
+        composition = composition,
+    }
+end
+
 return M