Recover enclosed Creative builders onto verified open surface sites

README.md

@@ -116,6 +116,12 @@ Os logs `[llm_metric]` registram bot, papel, latência e tokens reais por chamad
 de Curriculum, Action, Critic e Skill Manager. No Gemini CLI, a temperatura zero
 é aplicada por `modelConfigs.customOverrides`, além do cliente Voyager.
 
+Se as construções cercarem o bot, o helper procura uma área de superfície já
+carregada e livre, a 8–12 blocos por eixo. O voo Creative de recuperação verifica
+o volume do jogador em toda a rota, usa segmentos de até 0,4 bloco, sobe no máximo
+4 blocos para ultrapassar a construção e pousa em solo confirmado. Não destrói
+blocos, não teleporta e não altera a exploração horizontal do Curriculum.
+
 - CLI fixado em `@google/gemini-cli@0.61.0`, modelo efetivo `gemini-3.5-flash-lite`.
 - Segredos privados do Space: `GEMINI_BOT_KEY_1` a `GEMINI_BOT_KEY_6`.
 - Nenhuma chave deve ser salva no Git, no checkpoint ou nas saídas de status.

tests/test_voyager_navigation.js

@@ -61,6 +61,33 @@ vm.runInContext(fs.readFileSync(path.join(__dirname,'../voyager_place.js'),'utf8
     assert.equal(s.bot.blockAt(new Vec3(1,64,0)).name, 'snow_block');
     console.log('PASS pinned GoalPlaceBlock raycast, blocked-sector recovery and 4 real simulated world updates');
 
+    const enclosed = () => {
+        const f=fixture();
+        for(let y=64;y<=65;y++) for(let x=-2;x<=2;x++) for(let z=-2;z<=2;z++) {
+            if(Math.max(Math.abs(x),Math.abs(z))===2) f.blocks.set(new Vec3(x,y,z).toString(),'stone');
+        }
+        f.bot.physics={gravity:.08}; f.bot.clearControlStates=()=>{};
+        f.bot.creative={startFlying:()=>{f.bot.physics.gravity=0;},stopFlying:()=>{f.bot.physics.gravity=.08;},
+            flyTo:async p=>{assert(f.bot.entity.position.distanceTo(p)<=.401);f.bot.entity.position=p.clone();}};
+        return f;
+    };
+    const boxed=enclosed(), original=new Map(boxed.blocks);
+    await context.placeBlocks(boxed.bot,'snow_block',3);
+    assert.equal(boxed.bot.entity.position.y,64);
+    assert(boxed.bot.entity.position.x>=8);
+    assert.equal(boxed.bot.physics.gravity,.08);
+    for(const [key,value] of original) assert.equal(boxed.blocks.get(key),value);
+    assert.equal(boxed.bot._voyagerVerifiedActions.length,3);
+    const interrupted=enclosed();
+    interrupted.bot.creative.flyTo=async()=>{throw Error('disconnected');};
+    await assert.rejects(context.moveToOpenPlacementSite(interrupted.bot),/disconnected/);
+    assert.equal(interrupted.bot.physics.gravity,.08);
+    const unloaded=enclosed(), getBlock=unloaded.bot.blockAt;
+    unloaded.bot.blockAt=p=>Math.abs(p.x)>5 || Math.abs(p.z)>5 ? null : getBlock(p);
+    await assert.rejects(context.moveToOpenPlacementSite(unloaded.bot),/No known clear route/);
+    assert.equal(unloaded.bot.entity.position.y,64);
+    console.log('PASS enclosed Creative recovery, preserved builds, surface landing, unknown-chunk refusal and gravity cleanup');
+
     // The old 1.3.1 liquid constants are undefined on MC 1.19. Compare actual
     // physics integration, not a string/version assertion alone.
     const liquidWorld = {getBlock(p) {

voyager_place.js

@@ -39,7 +39,82 @@ async function placeItem(bot, name, position) {
     bot.save(`${name}_placed`);
 }
 
-async function placeBlocks(bot, name, count = 1) {
+async function moveToOpenPlacementSite(bot) {
+    // Construction can enclose a Creative bot. Recover over known blocks,
+    // without digging the build, teleporting, or exploring underground.
+    const start = bot.entity.position.clone();
+    const clear = (p) => {
+        if (![p.x,p.y,p.z].every(Number.isFinite)) return false;
+        for (let x=Math.floor(p.x-.3);x<=Math.floor(p.x+.3);x++) {
+            for (let y=Math.floor(p.y+.001);y<=Math.floor(p.y+1.799);y++) {
+                for (let z=Math.floor(p.z-.3);z<=Math.floor(p.z+.3);z++) {
+                    const b=bot.blockAt(new Vec3(x,y,z));
+                    if (!b || b.boundingBox !== 'empty' || ['water','lava'].includes(b.name)) return false;
+                }
+            }
+        }
+        return true;
+    };
+    const segment = (from,to) => {
+        const n=Math.max(1,Math.ceil(from.distanceTo(to)/.4)), points=[];
+        for(let i=1;i<=n;i++) {
+            const p=from.plus(to.minus(from).scaled(i/n));
+            if(!clear(p)) return null;
+            points.push(p);
+        }
+        return points;
+    };
+    const openSite = (p) => {
+        for(let dx=-2;dx<=2;dx++) for(let dz=-2;dz<=2;dz++) {
+            const q=p.offset(dx,0,dz), support=bot.blockAt(q.offset(0,-.01,0));
+            if(!support || support.boundingBox !== 'block' || !clear(q)) return false;
+        }
+        return true;
+    };
+    let route, landing;
+    for(const radius of [8,12]) {
+        for(const [dx,dz] of [[1,0],[0,1],[-1,0],[0,-1],[1,1],[-1,1],[-1,-1],[1,-1]]) {
+            for(let y=Math.floor(start.y);y>=Math.max(64,Math.floor(start.y)-2);y--) {
+                const target=new Vec3(Math.floor(start.x)+dx*radius+.5,y,Math.floor(start.z)+dz*radius+.5);
+                if(!openSite(target)) continue;
+                for(const rise of [2,3,4]) {
+                    const up=new Vec3(start.x,Math.floor(start.y)+rise,start.z);
+                    const across=new Vec3(target.x,up.y,target.z);
+                    const a=segment(start,up), b=a && segment(up,across), c=b && segment(across,target);
+                    if(c) {route=[...a,...b,...c];landing=target;break;}
+                }
+                if(route) break;
+            }
+            if(route) break;
+        }
+        if(route) break;
+    }
+    if(!route) throw new Error('No known clear route to an open surface construction site');
+    bot.pathfinder.setGoal(null);
+    bot.clearControlStates();
+    const deadline=Date.now()+20000;
+    bot.creative.startFlying();
+    try {
+        for(const p of route) {
+            if(Date.now()>deadline || !clear(p) || bot.entity.position.distanceTo(p)>.6) {
+                throw new Error('Construction recovery route changed; stopping flight');
+            }
+            // The documented Creative API has no collision avoidance: every
+            // segment is prechecked and shorter than its 0.5-block inner loop.
+            await bot.creative.flyTo(p);
+        }
+    } finally {
+        bot.creative.stopFlying();
+        bot.clearControlStates();
+    }
+    await bot.waitForTicks(4);
+    if(bot.entity.position.distanceTo(landing)>1 || !openSite(landing)) {
+        throw new Error('Construction recovery did not reach the verified surface site');
+    }
+    console.info(`[placement recovery] surface ${start} -> ${bot.entity.position}`);
+}
+
+async function placeBlocks(bot, name, count = 1, relocated = false) {
     if (!Number.isInteger(count) || count < 1 || count > 4) throw new Error("Place 1..4 blocks per task");
     const origin = bot.entity.position.floored();
     let placed = 0, attempts = 0, lastError = "No supported empty cells nearby";
@@ -65,6 +140,10 @@ async function placeBlocks(bot, name, count = 1) {
         distance: bot.entity.position.distanceTo(position),
     }));
     supported.sort((a,b) => Number(b.visible) - Number(a.visible) || a.distance - b.distance);
+    if (!relocated && !supported.some(c=>c.visible) && bot.game.gameMode === 'creative') {
+        await moveToOpenPlacementSite(bot);
+        return placeBlocks(bot,name,count,true);
+    }
     for (const {position} of supported) {
         try {
             await placeItem(bot,name,position);
@@ -79,5 +158,9 @@ async function placeBlocks(bot, name, count = 1) {
         }
         if (++attempts >= 24) break;
     }
+    if(!relocated && bot.game.gameMode === 'creative') {
+        await moveToOpenPlacementSite(bot);
+        return placeBlocks(bot,name,count-placed,true);
+    }
     throw new Error(`Placed ${placed}/${count} ${name}: ${lastError}; supported=${supported.length}, visible=${supported.filter(c=>c.visible).length}, position=${bot.entity.position}`);
 }