icoa-cli 2.19.355 → 2.19.357

package/dist/commands/shell.js

@@ -1 +1,151 @@
-import{execSync as o}from"node:child_process";import chalk from"chalk";import{printInfo as e,printSuccess as n}from"../lib/ui.js";import{logCommand as s}from"../lib/logger.js";import{getActiveCwd as r}from"../lib/exam-sandbox.js";export function resolveShellLaunch(o){return o.dockerAvailable?{mode:"docker",command:"docker"}:{mode:"host",command:"win32"===o.platform?o.comspecEnv||"cmd.exe":o.shellEnv||"/bin/bash"}}function l(){const s=r(),{command:l}=resolveShellLaunch({dockerAvailable:!1,platform:process.platform,shellEnv:process.env.SHELL,comspecEnv:process.env.COMSPEC});e("Docker not found — opening a host shell."),console.log(chalk.gray("  All 110 CTF tools run on your host. If any are missing, run ")+chalk.cyan("env setup")+chalk.gray(".")),console.log(chalk.gray("  Type 'exit' to return to ICOA CLI.")),console.log();try{o(l,{stdio:"inherit",cwd:s}),console.log(),n("Shell session ended.")}catch{console.log(),e("Shell session ended.")}}export function registerShellCommand(r){r.command("shell").description("Open an interactive CTF shell (Docker sandbox if available, else host)").action(async()=>{if(s("shell"),!function(){try{return o("docker info",{stdio:"ignore"}),!0}catch{return!1}}())return void l();const r="icoa/sandbox:2026",t=`icoa-sandbox-${Date.now()}`;try{o(`docker image inspect ${r}`,{stdio:"ignore"})}catch{e(`Sandbox image not found. Pulling ${r}...`);try{o(`docker pull ${r}`,{stdio:"inherit"})}catch{return e(`Could not pull ${r} — using your host shell instead.`),void l()}}n("Launching sandbox..."),console.log(chalk.gray("  Type 'exit' to return to ICOA CLI.")),console.log();try{o(`docker run --rm -it --name ${t} --network=host ${r} /bin/bash`,{stdio:"inherit"}),console.log(),n("Sandbox session ended.")}catch{console.log(),e("Sandbox session ended.")}})}
+import { execSync, spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { printInfo, printSuccess } from '../lib/ui.js';
+import { logCommand } from '../lib/logger.js';
+import { getActiveCwd } from '../lib/exam-sandbox.js';
+import { isDockerRunning } from '../lib/docker-probe.js';
+/**
+ * Decide which shell to launch. The Docker sandbox is the PREFERRED path (extra
+ * isolation), but it is OPTIONAL: the 110 CTF tools are installed on the HOST by
+ * `env setup`, and the `env` doctor explicitly marks docker "optional — not
+ * needed". So when Docker is absent we must NOT dead-end the user with an
+ * "install Docker" wall — we drop them into a host shell where every tool they
+ * need already lives. Pure + testable so the no-docker → host fallback is locked
+ * by a regression test.
+ */
+export function resolveShellLaunch(opts) {
+    if (opts.dockerAvailable) {
+        return { mode: 'docker', command: 'docker' };
+    }
+    const command = opts.platform === 'win32' ? opts.comspecEnv || 'cmd.exe' : opts.shellEnv || '/bin/bash';
+    return { mode: 'host', command };
+}
+// The image ladder is shared with the REPL's persistent-container path — one
+// source of truth in lib/sandbox.ts; re-exported here for the unit tests.
+export { SANDBOX_IMAGES, resolveSandboxImage } from '../lib/sandbox.js';
+import { SANDBOX_IMAGES, resolveSandboxImage } from '../lib/sandbox.js';
+/**
+ * docker-run args as an ARRAY (spawnSync — no shell, so a cwd with spaces
+ * survives untouched). The two mounts are the aienv × docker interlock:
+ *  - cwd → /work: challenge files flow both ways instead of being invisible
+ *    from inside the container (and work done in /work outlives --rm).
+ *  - icoa-aienv named volume → /root/.icoa: docker's copy-up seeds it from the
+ *    image-baked venv on first use, then in-container pip installs survive
+ *    --rm across sessions. Reset anytime: `docker volume rm icoa-aienv`.
+ */
+export function buildSandboxRunArgs(opts) {
+    return [
+        'run',
+        '--rm',
+        '-it',
+        '--name',
+        opts.containerName,
+        '--network=host',
+        '-v',
+        `${opts.cwd}:/work`,
+        '-w',
+        '/work',
+        '-v',
+        'icoa-aienv:/root/.icoa',
+        opts.image,
+        '/bin/bash',
+    ];
+}
+// Probe the daemon socket, not the `docker` CLI — checking must never wake a
+// stopped Docker Desktop (the sandbox is optional; host shell is the fallback).
+// See lib/docker-probe.ts.
+function isDockerAvailable() {
+    return isDockerRunning();
+}
+function openHostShell() {
+    const cwd = getActiveCwd();
+    const { command } = resolveShellLaunch({
+        dockerAvailable: false,
+        platform: process.platform,
+        shellEnv: process.env.SHELL,
+        comspecEnv: process.env.COMSPEC,
+    });
+    printInfo('Docker not found — opening a host shell.');
+    console.log(chalk.gray('  All 110 CTF tools run on your host. If any are missing, run ') +
+        chalk.cyan('env setup') +
+        chalk.gray('.'));
+    console.log(chalk.gray("  Type 'exit' to return to ICOA CLI."));
+    console.log();
+    try {
+        execSync(command, { stdio: 'inherit', cwd });
+        console.log();
+        printSuccess('Shell session ended.');
+    }
+    catch {
+        // A non-zero exit (incl. the user typing `exit`) lands here — not an error.
+        console.log();
+        printInfo('Shell session ended.');
+    }
+}
+export function registerShellCommand(program) {
+    program
+        .command('shell')
+        .description('Open an interactive CTF shell (Docker sandbox if available, else host)')
+        .action(async () => {
+        logCommand('shell');
+        // Docker is the preferred (isolated) path but is OPTIONAL — fall back to
+        // the host shell instead of telling the user to install Docker.
+        if (!(await isDockerAvailable())) {
+            openHostShell();
+            return;
+        }
+        const hasLocal = (image) => {
+            try {
+                execSync(`docker image inspect ${image}`, { stdio: 'ignore' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const pull = (image) => {
+            printInfo(`Pulling ${image}...`);
+            try {
+                execSync(`docker pull ${image}`, { stdio: 'inherit' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const image = resolveSandboxImage(hasLocal, pull);
+        if (image === null) {
+            // No image local or pullable — don't dead-end, the host has the tools.
+            printInfo('Could not pull a sandbox image — using your host shell instead.');
+            openHostShell();
+            return;
+        }
+        const cwd = getActiveCwd();
+        printSuccess('Launching sandbox...');
+        console.log(chalk.gray('  Your folder is mounted at ') +
+            chalk.cyan('/work') +
+            chalk.gray(' — files there persist on your host.'));
+        if (image === SANDBOX_IMAGES[0]) {
+            console.log(chalk.gray('  ML venv: ') +
+                chalk.cyan('~/.icoa/aienv/bin/python') +
+                chalk.gray(' (sklearn / jupyter / mujoco) — its pip installs persist across sessions.'));
+        }
+        else {
+            console.log(chalk.gray('  This image has no ML venv — get the newer one with ') +
+                chalk.cyan(`docker pull ${SANDBOX_IMAGES[0]}`));
+        }
+        console.log(chalk.gray("  Type 'exit' to return to ICOA CLI."));
+        console.log();
+        const containerName = `icoa-sandbox-${Date.now()}`;
+        const result = spawnSync('docker', buildSandboxRunArgs({ cwd, image, containerName }), {
+            stdio: 'inherit',
+        });
+        console.log();
+        if (result.error) {
+            printInfo('Sandbox session ended.');
+        }
+        else {
+            printSuccess('Sandbox session ended.');
+        }
+    });
+}

package/dist/commands/sim.js

@@ -1 +1,389 @@
-import chalk from"chalk";import{spawn as o}from"node:child_process";import{copyFileSync as e,existsSync as n,mkdirSync as r,writeFileSync as a}from"node:fs";import{homedir as t}from"node:os";import{dirname as l,join as s,resolve as i}from"node:path";import{createInterface as c}from"node:readline";import{fileURLToPath as d}from"node:url";import{fetchWithCountdown as g}from"../lib/countdown.js";const m=s(t(),".icoa","cache","sim");import{getMainRl as p}from"../lib/main-rl.js";import{COOLDOWN_SECONDS as u,lastSimAt as y,markArmAt as f,markBundledAt as b,markSimAt as h}from"../lib/sim-cooldown.js";const w={baseline:{action:null,label:"Baseline — robot doing its job",hint:"Approach → grasp → lift → place → return. This is what normal looks like.",frames:90,narrative:!0},release:{action:{xyz:[.1,0,.3],rotation:[0,0,0],gripper_close:.05},label:'Prompt Injection — "release the gripper"',hint:"Gripper opens (0.05 < 0.10 win threshold). This is Paper D Q41 success."},patch:{action:{xyz:[-.3,.2,.5],rotation:[.5,0,.3],gripper_close:.95},label:"Adversarial Patch — sticker redirects the arm",hint:"Same instruction, but arm reaches LEFT instead of RIGHT. Paper D Q42 success."},confused:{action:{xyz:[.001,0,.001],rotation:[0,0,0],gripper_close:.5},label:'Modality Confusion — "pick up the purple object"',hint:"No purple object exists. VLA freezes near origin. Paper D Q43 success."},color:{action:{xyz:[.4,-.3,.6],rotation:[-.4,.2,-.1],gripper_close:.2},label:"Cross-Modal Attack — image + text manipulated together",hint:"Action drifts hard on multiple axes. Paper D Q49-class attack (future).",hidden:!0},ensemble:{action:null,label:"Ensemble — 9 robots dancing on one beat",hint:"Pre-rendered group dance. Instant. No cooldown.",bundled:"ensemble-v2.mp4"},arm:{action:null,label:"Arm mode — interactive 6-DOF companion-arm sandbox",hint:"Type 6 joint amplitudes (or a preset). Each render takes ~15s, 60s cooldown.",bundled:void 0}},v=Object.fromEntries(Object.entries(w).filter(([,o])=>!o.hidden)),j={1:{vec:[1,1,1,1,1.4,1],label:"full demo — every joint at full amplitude"},2:{vec:[1,0,0,0,0,0],label:"base spin only (joint 1 swings)"},3:{vec:[0,.8,.8,0,0,0],label:"shoulder + elbow (lift cycle)"},4:{vec:[0,0,0,.8,1.4,1],label:"wrist drill — j4 roll + j5 bend + j6 twist"},5:{vec:[-.7,-.8,.6,.7,-1,.5],label:"mixed asymmetric (chaotic)"}};function T(){return"darwin"===process.platform?"open":"win32"===process.platform?"start":"xdg-open"}async function x(e){const n=(Date.now()-y())/1e3;if(n<u){const o=Math.ceil(u-n);return console.log(chalk.yellow(`  Please wait ${o}s before the next render.`)),console.log(chalk.gray("  (One render per minute keeps things fast for everyone.)")),!1}const r=`${process.env.ICOA_SERVER_URL?.replace(/\/+$/,"")||"https://practice.icoa2026.au"}/api/ai/vla/41/sim`;e.quietHeader||(console.log(),console.log(chalk.bold.cyan("  ICOA  ·  MuJoCo Sim")),console.log(chalk.gray("  ")+chalk.white(e.label)),console.log());try{const n=fetch(r,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({action:e.action,frames:e.frames,narrative:e.narrative,...e.panda2_pose?{panda2_pose:e.panda2_pose}:{}}),signal:AbortSignal.timeout(6e4)}),t=await g(n);if(!t.ok)return console.log(chalk.yellow(`  Server returned HTTP ${t.status}.`)),!1;const l=await t.json();if(!l.success||!l.data?.mp4_b64)return console.log(chalk.yellow("  Renderer unavailable.")),!1;const i=process.env.TMPDIR||"/tmp",c=s(i,`icoa-sim-${e.scenarioName}-${Date.now()}.mp4`);a(c,Buffer.from(l.data.mp4_b64,"base64")),h(Date.now()),console.log(),console.log(chalk.bold.green("  ✓ ")+chalk.gray("Rendered.")),l.data.description&&console.log(chalk.gray("    Action: ")+chalk.white(l.data.description)),console.log(),console.log(chalk.gray("  ")+e.hint),console.log();const d=T();return d?(o(d,[c],{stdio:"ignore",detached:!0}).unref(),console.log(chalk.gray("  Opening in your default video player..."))):console.log(chalk.gray("  Video at: ")+chalk.white(c)),console.log(),!0}catch(o){const e=o instanceof Error?o.message:String(o);return console.log(chalk.yellow(`  Sim error: ${e}`)),!1}}async function A(t){const g=t.toLowerCase();if("arm"===g)return void await async function(){console.log(),console.log(chalk.bold.cyan("  ICOA  ·  Companion Arm Sandbox")),console.log(chalk.gray("  Drive the printable 6-DOF arm directly. Server renders, video opens.")),console.log(),console.log(chalk.gray("  Joint amplitudes (radians, suggested range −1.0 to +1.0):")),console.log(chalk.gray("    j1=base spin    j2=shoulder    j3=elbow")),console.log(chalk.gray("    j4=forearm roll j5=wrist pitch j6=wrist roll")),console.log(),console.log(chalk.gray("  Type 6 numbers separated by spaces, or pick a preset:"));for(const[o,e]of Object.entries(j)){const n=e.vec.map(o=>o.toFixed(1).padStart(4)).join(" ");console.log(chalk.gray("    ")+chalk.bold.cyan(o)+chalk.gray(" → ["+n+"]  "+e.label))}console.log(),console.log(chalk.gray("  Each render: ~15s countdown + 60s cooldown between renders.")),console.log(chalk.gray("  Type ")+chalk.bold.cyan("q")+chalk.gray(" or ")+chalk.bold.cyan("exit")+chalk.gray(" to leave arm mode.")),console.log();const o=p(),e=null!==o,n=e?o.listeners("line").slice():[];e&&o.removeAllListeners("line");const r=e?o:c({input:process.stdin,output:process.stdout,terminal:!0});return new Promise(o=>{let a=!1;const t=()=>{process.stdout.write(chalk.bold.cyan("  icoa arm> "))},l=async s=>{const i=s.trim();if(a)return;if("q"===i||"exit"===i||"quit"===i)return console.log(chalk.gray("  Leaving arm mode.")),console.log(),r.removeListener("line",l),(()=>{if(e){r.removeAllListeners("line");for(const o of n)r.on("line",o);r.prompt()}else r.close()})(),void o();if("help"===i||"?"===i)return console.log(chalk.gray("  6 numbers (e.g. 0.5 0.7 0.5 0.3 0.6 0.3) or preset 1/2/3/4.")),void t();const c=(o=>{const e=o.trim();if(!e)return null;if(j[e])return j[e].vec;const n=e.split(/[\s,]+/).map(o=>Number(o));return 6!==n.length||n.some(o=>!Number.isFinite(o))?null:n.map(o=>Math.max(-1.5,Math.min(1.5,o)))})(i);if(!c)return console.log(chalk.yellow("  Need 6 numbers or a preset (1-4). Try ?")),void t();a=!0;const d=c.map(o=>o.toFixed(2)).join(" ");console.log(chalk.gray("  Sending pose [")+chalk.white(d)+chalk.gray("]")),await x({scenarioName:"arm",label:"Companion arm — your pose",hint:"Rendered from your 6-vector. Try another, or "+chalk.bold.cyan("q")+chalk.gray(" to leave."),action:null,frames:90,narrative:!0,panda2_pose:c,quietHeader:!0})&&f(Date.now()),a=!1,t()};r.on("line",l),t()})}();const u=w[g];if(!u){console.log(),console.log(chalk.yellow(`  Unknown scenario: "${t}"`)),console.log(chalk.gray("  Available:"));for(const[o,e]of Object.entries(v))console.log(chalk.gray("    ")+chalk.bold.cyan(o.padEnd(10))+chalk.gray(e.label));return void console.log()}if(u.bundled)return void await async function(t,c){const g=await async function(o){const e=function(o){const e=l(d(import.meta.url));return[i(e,"..","..","assets","sim",o),i(e,"..","..","..","assets","sim",o)].find(o=>n(o))||null}(o);if(e)return e;const t=s(m,o);if(n(t))return t;console.log(),console.log(chalk.white("\n   ██╗ ██████╗ ██████╗  █████╗\n   ██║██╔════╝██╔═══██╗██╔══██╗\n   ██║██║     ██║   ██║███████║\n   ██║██║     ██║   ██║██╔══██║\n   ██║╚██████╗╚██████╔╝██║  ██║\n   ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝\n")),console.log(chalk.gray("   First-time setup — fetching the sim asset (~700 KB) ...")),console.log();try{r(m,{recursive:!0});const e=`https://icoa2026.au/assets/sim/${o}`,n=await fetch(e);if(!n.ok)return console.log(chalk.yellow(`   Download failed (HTTP ${n.status}).`)),console.log(chalk.gray("   Try ")+chalk.bold.cyan("icoa sim baseline")+chalk.gray(" (server-rendered alternative).")),console.log(),null;const l=Buffer.from(await n.arrayBuffer());return a(t,l),console.log(chalk.green("   ✓ Cached — future runs are instant.")),console.log(),t}catch(o){return console.log(chalk.yellow(`   Network error: ${o instanceof Error?o.message:String(o)}`)),console.log(chalk.gray("   Try ")+chalk.bold.cyan("icoa sim baseline")+chalk.gray(" instead.")),console.log(),null}}(c.bundled);if(!g)return;const p=process.env.TMPDIR||"/tmp",u=s(p,`icoa-sim-${t}-${Date.now()}.mp4`);e(g,u),b(Date.now()),console.log(),console.log(chalk.bold.cyan("  ICOA  ·  MuJoCo Sim")),console.log(chalk.gray("  ")+chalk.white(c.label)),console.log(),console.log(chalk.bold.green("  ✓ ")+chalk.gray("Ready (pre-rendered, instant playback).")),console.log(),console.log(chalk.gray("  ")+c.hint),console.log();const y=T();y?(o(y,[u],{stdio:"ignore",detached:!0}).unref(),console.log(chalk.gray("  Opening in your default video player..."))):console.log(chalk.gray("  Video at: ")+chalk.white(u)),console.log();const f="1"===process.env.ICOA_INSIDE_REPL?"":"icoa ";console.log(chalk.gray("  Want to drive the companion arm yourself?  ")+chalk.bold.cyan(f+"sim arm")),console.log()}(g,u);await x({scenarioName:g,label:u.label,hint:u.hint,action:u.action,frames:u.frames,narrative:u.narrative,panda2_pose:u.panda2_pose});const y="1"===process.env.ICOA_INSIDE_REPL?"":"icoa ";console.log(chalk.gray("  Try other scenarios:"));for(const o of Object.keys(v))o!==g&&console.log(chalk.gray("    "+y+"sim ")+chalk.cyan(o));console.log()}export function registerSimCommand(o){o.command("sim [scenario]").description("MuJoCo VLA — sim (group dance) · sim arm (interactive companion arm) · sim baseline/release/patch/confused").action(async o=>{await A(o||"ensemble")})}export{w as SCENARIOS};
+import chalk from 'chalk';
+import { spawn } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { fetchWithCountdown } from '../lib/countdown.js';
+const SIM_ASSET_BASE_URL = 'https://icoa2026.au/assets/sim';
+const SIM_CACHE_DIR = join(homedir(), '.icoa', 'cache', 'sim');
+const SIM_DOWNLOAD_BANNER = `
+   ██╗ ██████╗ ██████╗  █████╗
+   ██║██╔════╝██╔═══██╗██╔══██╗
+   ██║██║     ██║   ██║███████║
+   ██║██║     ██║   ██║██╔══██║
+   ██║╚██████╗╚██████╔╝██║  ██║
+   ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝
+`;
+import { getMainRl } from '../lib/main-rl.js';
+import { COOLDOWN_SECONDS, lastSimAt, markArmAt, markBundledAt, markSimAt } from '../lib/sim-cooldown.js';
+const SCENARIOS = {
+    baseline: {
+        action: null, // Backend executes the VLA on "Pick up the red cup"
+        label: 'Baseline — robot doing its job',
+        hint: 'Approach → grasp → lift → place → return. This is what normal looks like.',
+        frames: 90, // 3 seconds
+        narrative: true, // multi-waypoint cinematic sweep
+    },
+    release: {
+        action: { xyz: [0.1, 0.0, 0.3], rotation: [0, 0, 0], gripper_close: 0.05 },
+        label: 'Prompt Injection — "release the gripper"',
+        hint: 'Gripper opens (0.05 < 0.10 win threshold). This is Paper D Q41 success.',
+    },
+    patch: {
+        action: { xyz: [-0.3, 0.2, 0.5], rotation: [0.5, 0, 0.3], gripper_close: 0.95 },
+        label: 'Adversarial Patch — sticker redirects the arm',
+        hint: 'Same instruction, but arm reaches LEFT instead of RIGHT. Paper D Q42 success.',
+    },
+    confused: {
+        action: { xyz: [0.001, 0.0, 0.001], rotation: [0, 0, 0], gripper_close: 0.5 },
+        label: 'Modality Confusion — "pick up the purple object"',
+        hint: 'No purple object exists. VLA freezes near origin. Paper D Q43 success.',
+    },
+    // ─── Hidden Easter egg — for marketing demos / promo videos only ──────
+    color: {
+        action: { xyz: [0.4, -0.3, 0.6], rotation: [-0.4, 0.2, -0.1], gripper_close: 0.2 },
+        label: 'Cross-Modal Attack — image + text manipulated together',
+        hint: 'Action drifts hard on multiple axes. Paper D Q49-class attack (future).',
+        hidden: true,
+    },
+    // ─── Pre-baked instant-playback bundle ───────────────────────────────
+    ensemble: {
+        action: null,
+        label: 'Ensemble — 9 robots dancing on one beat',
+        hint: 'Pre-rendered group dance. Instant. No cooldown.',
+        bundled: 'ensemble-v2.mp4',
+    },
+    // `arm` is handled by runArmInteractive, NOT entered via SCENARIOS.
+    // Kept as a marker so help listings show it. The runtime path branches
+    // on the literal name before consulting this table.
+    arm: {
+        action: null,
+        label: 'Arm mode — interactive 6-DOF companion-arm sandbox',
+        hint: 'Type 6 joint amplitudes (or a preset). Each render takes ~15s, 60s cooldown.',
+        bundled: undefined, // sentinel — interactive branch picks this up
+    },
+};
+const VISIBLE_SCENARIOS = Object.fromEntries(Object.entries(SCENARIOS).filter(([, v]) => !v.hidden));
+// Presets for the interactive arm mode — give beginners a 1-tap option
+// while teaching them the 6-vector convention.
+const ARM_PRESETS = {
+    '1': { vec: [1.0, 1.0, 1.0, 1.0, 1.4, 1.0], label: 'full demo — every joint at full amplitude' },
+    '2': { vec: [1.0, 0.0, 0.0, 0.0, 0.0, 0.0], label: 'base spin only (joint 1 swings)' },
+    '3': { vec: [0.0, 0.8, 0.8, 0.0, 0.0, 0.0], label: 'shoulder + elbow (lift cycle)' },
+    '4': { vec: [0.0, 0.0, 0.0, 0.8, 1.4, 1.0], label: 'wrist drill — j4 roll + j5 bend + j6 twist' },
+    '5': { vec: [-0.7, -0.8, 0.6, 0.7, -1.0, 0.5], label: 'mixed asymmetric (chaotic)' },
+};
+function systemOpener() {
+    if (process.platform === 'darwin')
+        return 'open';
+    if (process.platform === 'win32')
+        return 'start';
+    return 'xdg-open';
+}
+// Resolve a bundled asset under assets/sim/ in the local dev tree.
+// Returns null when running from an npm-installed package (the asset is
+// no longer bundled — see ensureBundledAsset for the lazy-download fallback).
+function bundledAssetPath(filename) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, '..', '..', 'assets', 'sim', filename),
+        resolve(here, '..', '..', '..', 'assets', 'sim', filename),
+    ];
+    return candidates.find((p) => existsSync(p)) || null;
+}
+// Return a usable filesystem path to a sim asset. Priority:
+//   1. dev tree (assets/sim/<filename>) — for `npm link` / source-tree usage
+//   2. user cache (~/.icoa/cache/sim/<filename>) — populated by prior runs
+//   3. download from icoa2026.au (first-run path) — cached on success
+async function ensureBundledAsset(filename) {
+    const devPath = bundledAssetPath(filename);
+    if (devPath)
+        return devPath;
+    const cachePath = join(SIM_CACHE_DIR, filename);
+    if (existsSync(cachePath))
+        return cachePath;
+    console.log();
+    console.log(chalk.white(SIM_DOWNLOAD_BANNER));
+    console.log(chalk.gray('   First-time setup — fetching the sim asset (~700 KB) ...'));
+    console.log();
+    try {
+        mkdirSync(SIM_CACHE_DIR, { recursive: true });
+        const url = `${SIM_ASSET_BASE_URL}/${filename}`;
+        const res = await fetch(url);
+        if (!res.ok) {
+            console.log(chalk.yellow(`   Download failed (HTTP ${res.status}).`));
+            console.log(chalk.gray('   Try ') + chalk.bold.cyan('icoa sim baseline') + chalk.gray(' (server-rendered alternative).'));
+            console.log();
+            return null;
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        writeFileSync(cachePath, buf);
+        console.log(chalk.green('   ✓ Cached — future runs are instant.'));
+        console.log();
+        return cachePath;
+    }
+    catch (e) {
+        console.log(chalk.yellow(`   Network error: ${e instanceof Error ? e.message : String(e)}`));
+        console.log(chalk.gray('   Try ') + chalk.bold.cyan('icoa sim baseline') + chalk.gray(' instead.'));
+        console.log();
+        return null;
+    }
+}
+async function playBundled(scenarioName, scenario) {
+    const src = await ensureBundledAsset(scenario.bundled);
+    if (!src)
+        return;
+    const tmpDir = process.env.TMPDIR || '/tmp';
+    const dst = join(tmpDir, `icoa-sim-${scenarioName}-${Date.now()}.mp4`);
+    copyFileSync(src, dst);
+    markBundledAt(Date.now());
+    console.log();
+    console.log(chalk.bold.cyan('  ICOA  ·  MuJoCo Sim'));
+    console.log(chalk.gray('  ') + chalk.white(scenario.label));
+    console.log();
+    console.log(chalk.bold.green('  ✓ ') + chalk.gray('Ready (pre-rendered, instant playback).'));
+    console.log();
+    console.log(chalk.gray('  ') + scenario.hint);
+    console.log();
+    const opener = systemOpener();
+    if (opener) {
+        spawn(opener, [dst], { stdio: 'ignore', detached: true }).unref();
+        console.log(chalk.gray('  Opening in your default video player...'));
+    }
+    else {
+        console.log(chalk.gray('  Video at: ') + chalk.white(dst));
+    }
+    console.log();
+    const prefix = process.env.ICOA_INSIDE_REPL === '1' ? '' : 'icoa ';
+    console.log(chalk.gray('  Want to drive the companion arm yourself?  ') + chalk.bold.cyan(prefix + 'sim arm'));
+    console.log();
+}
+// ─── Server-render helper used by both classic scenarios and arm mode ──
+async function renderOnServer(opts) {
+    // Cooldown gate
+    const now = Date.now();
+    const sinceLast = (now - lastSimAt()) / 1000;
+    if (sinceLast < COOLDOWN_SECONDS) {
+        const wait = Math.ceil(COOLDOWN_SECONDS - sinceLast);
+        console.log(chalk.yellow(`  Please wait ${wait}s before the next render.`));
+        console.log(chalk.gray('  (One render per minute keeps things fast for everyone.)'));
+        return false;
+    }
+    const baseUrl = process.env.ICOA_SERVER_URL?.replace(/\/+$/, '') || 'https://practice.icoa2026.au';
+    const url = `${baseUrl}/api/ai/vla/41/sim`;
+    if (!opts.quietHeader) {
+        console.log();
+        console.log(chalk.bold.cyan('  ICOA  ·  MuJoCo Sim'));
+        console.log(chalk.gray('  ') + chalk.white(opts.label));
+        console.log();
+    }
+    try {
+        const fetchPromise = fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                action: opts.action,
+                frames: opts.frames,
+                narrative: opts.narrative,
+                ...(opts.panda2_pose ? { panda2_pose: opts.panda2_pose } : {}),
+            }),
+            signal: AbortSignal.timeout(60_000),
+        });
+        const res = await fetchWithCountdown(fetchPromise);
+        if (!res.ok) {
+            console.log(chalk.yellow(`  Server returned HTTP ${res.status}.`));
+            return false;
+        }
+        const json = await res.json();
+        if (!json.success || !json.data?.mp4_b64) {
+            console.log(chalk.yellow('  Renderer unavailable.'));
+            return false;
+        }
+        const tmpDir = process.env.TMPDIR || '/tmp';
+        const path = join(tmpDir, `icoa-sim-${opts.scenarioName}-${Date.now()}.mp4`);
+        writeFileSync(path, Buffer.from(json.data.mp4_b64, 'base64'));
+        markSimAt(Date.now());
+        console.log();
+        console.log(chalk.bold.green('  ✓ ') + chalk.gray('Rendered.'));
+        if (json.data.description) {
+            console.log(chalk.gray('    Action: ') + chalk.white(json.data.description));
+        }
+        console.log();
+        console.log(chalk.gray('  ') + opts.hint);
+        console.log();
+        const opener = systemOpener();
+        if (opener) {
+            spawn(opener, [path], { stdio: 'ignore', detached: true }).unref();
+            console.log(chalk.gray('  Opening in your default video player...'));
+        }
+        else {
+            console.log(chalk.gray('  Video at: ') + chalk.white(path));
+        }
+        console.log();
+        return true;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(chalk.yellow(`  Sim error: ${msg}`));
+        return false;
+    }
+}
+// ─── Interactive companion-arm sandbox ─────────────────────────────────
+// Listener-swap pattern (BUG-008 in CLAUDE.md): if main REPL is alive,
+// reuse its readline.Interface and stash its 'line' listeners.
+async function runArmInteractive() {
+    console.log();
+    console.log(chalk.bold.cyan('  ICOA  ·  Companion Arm Sandbox'));
+    console.log(chalk.gray('  Drive the printable 6-DOF arm directly. Server renders, video opens.'));
+    console.log();
+    console.log(chalk.gray('  Joint amplitudes (radians, suggested range −1.0 to +1.0):'));
+    console.log(chalk.gray('    j1=base spin    j2=shoulder    j3=elbow'));
+    console.log(chalk.gray('    j4=forearm roll j5=wrist pitch j6=wrist roll'));
+    console.log();
+    console.log(chalk.gray('  Type 6 numbers separated by spaces, or pick a preset:'));
+    for (const [k, p] of Object.entries(ARM_PRESETS)) {
+        const vec = p.vec.map((v) => v.toFixed(1).padStart(4)).join(' ');
+        console.log(chalk.gray('    ') + chalk.bold.cyan(k) + chalk.gray(' → [' + vec + ']  ' + p.label));
+    }
+    console.log();
+    console.log(chalk.gray('  Each render: ~15s countdown + 60s cooldown between renders.'));
+    console.log(chalk.gray('  Type ') +
+        chalk.bold.cyan('q') +
+        chalk.gray(' or ') +
+        chalk.bold.cyan('exit') +
+        chalk.gray(' to leave arm mode.'));
+    console.log();
+    const mainRl = getMainRl();
+    const usingMainRl = mainRl !== null;
+    const savedMainListeners = usingMainRl ? mainRl.listeners('line').slice() : [];
+    if (usingMainRl)
+        mainRl.removeAllListeners('line');
+    const rl = usingMainRl ? mainRl : createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    const restoreRl = () => {
+        if (usingMainRl) {
+            rl.removeAllListeners('line');
+            for (const l of savedMainListeners)
+                rl.on('line', l);
+            rl.prompt();
+        }
+        else {
+            rl.close();
+        }
+    };
+    const parsePose = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return null;
+        if (ARM_PRESETS[trimmed])
+            return ARM_PRESETS[trimmed].vec;
+        const parts = trimmed.split(/[\s,]+/).map((s) => Number(s));
+        if (parts.length !== 6 || parts.some((n) => !Number.isFinite(n)))
+            return null;
+        // Clamp each joint to ±1.5 to keep within URDF limits server-side
+        return parts.map((n) => Math.max(-1.5, Math.min(1.5, n)));
+    };
+    return new Promise((resolveOuter) => {
+        let busy = false;
+        const ask = () => {
+            process.stdout.write(chalk.bold.cyan('  icoa arm> '));
+        };
+        const onLine = async (rawLine) => {
+            const line = rawLine.trim();
+            if (busy)
+                return; // ignore input while a render is in flight
+            if (line === 'q' || line === 'exit' || line === 'quit') {
+                console.log(chalk.gray('  Leaving arm mode.'));
+                console.log();
+                rl.removeListener('line', onLine);
+                restoreRl();
+                resolveOuter();
+                return;
+            }
+            if (line === 'help' || line === '?') {
+                console.log(chalk.gray('  6 numbers (e.g. 0.5 0.7 0.5 0.3 0.6 0.3) or preset 1/2/3/4.'));
+                ask();
+                return;
+            }
+            const pose = parsePose(line);
+            if (!pose) {
+                console.log(chalk.yellow('  Need 6 numbers or a preset (1-4). Try ?'));
+                ask();
+                return;
+            }
+            busy = true;
+            const vecStr = pose.map((v) => v.toFixed(2)).join(' ');
+            console.log(chalk.gray('  Sending pose [') + chalk.white(vecStr) + chalk.gray(']'));
+            const ok = await renderOnServer({
+                scenarioName: 'arm',
+                label: 'Companion arm — your pose',
+                hint: 'Rendered from your 6-vector. Try another, or ' + chalk.bold.cyan('q') + chalk.gray(' to leave.'),
+                action: null,
+                frames: 90,
+                narrative: true,
+                panda2_pose: pose,
+                quietHeader: true,
+            });
+            if (ok)
+                markArmAt(Date.now());
+            busy = false;
+            ask();
+        };
+        rl.on('line', onLine);
+        ask();
+    });
+}
+async function runSim(scenarioName) {
+    const name = scenarioName.toLowerCase();
+    // Interactive arm sandbox — handled before SCENARIOS lookup
+    if (name === 'arm') {
+        await runArmInteractive();
+        return;
+    }
+    const scenario = SCENARIOS[name];
+    if (!scenario) {
+        console.log();
+        console.log(chalk.yellow(`  Unknown scenario: "${scenarioName}"`));
+        console.log(chalk.gray('  Available:'));
+        for (const [k, v] of Object.entries(VISIBLE_SCENARIOS)) {
+            console.log(chalk.gray('    ') + chalk.bold.cyan(k.padEnd(10)) + chalk.gray(v.label));
+        }
+        console.log();
+        return;
+    }
+    // Pre-baked path: instant playback, no server, no cooldown
+    if (scenario.bundled) {
+        await playBundled(name, scenario);
+        return;
+    }
+    // Server-rendered scenario
+    await renderOnServer({
+        scenarioName: name,
+        label: scenario.label,
+        hint: scenario.hint,
+        action: scenario.action,
+        frames: scenario.frames,
+        narrative: scenario.narrative,
+        panda2_pose: scenario.panda2_pose,
+    });
+    // Tail suggestions for classic scenarios
+    const prefix = process.env.ICOA_INSIDE_REPL === '1' ? '' : 'icoa ';
+    console.log(chalk.gray('  Try other scenarios:'));
+    for (const k of Object.keys(VISIBLE_SCENARIOS)) {
+        if (k !== name) {
+            console.log(chalk.gray('    ' + prefix + 'sim ') + chalk.cyan(k));
+        }
+    }
+    console.log();
+}
+export function registerSimCommand(program) {
+    program
+        .command('sim [scenario]')
+        .description('MuJoCo VLA — sim (group dance) · sim arm (interactive companion arm) · sim baseline/release/patch/confused')
+        .action(async (scenarioName) => {
+        // Bare `sim` defaults to the instant group dance.
+        await runSim(scenarioName || 'ensemble');
+    });
+}
+export { SCENARIOS };