icoa-cli 2.19.356 → 2.19.357

package/dist/lib/exam-state.js

@@ -1 +1,273 @@
-import{readFileSync as t,writeFileSync as e,existsSync as n,unlinkSync as a,mkdirSync as r,chmodSync as o}from"node:fs";import{execFileSync as i}from"node:child_process";import{join as s}from"node:path";import{homedir as c}from"node:os";import{getIcoaDir as u}from"./config.js";export function practicalChatCommand(t,e){return e?"ctf4ai"===t?"ctf4ai":"ai4ctf"===t?"ai4ctf":"vla"===t?"ctf4eai":null:null}export function materializeAttachedData(t,a){if(!a)return null;let o;try{const i=getRealExamState(),u=i?.session?.workspaceDir,f=u&&n(u)?u:s(c(),"icoa-workspace");r(f,{recursive:!0}),o=s(f,`q${t}.txt`),e(o,a,"utf-8")}catch{return null}try{return i("docker",["cp",o,`icoa-sandbox:/home/competitor/challenges/q${t}.txt`],{stdio:"ignore",timeout:3e3}),`challenges/q${t}.txt`}catch{return o}}function f(){return s(u(),"exam-state.json")}function l(){return s(u(),"demo-state.json")}function m(t){return"demo-free"===t?l():f()}export function getRealExamState(){const e=f();if(!n(e))return null;try{const n=JSON.parse(t(e,"utf-8"));if("demo-free"===n?.session?.examId){try{a(e)}catch{}return null}return n}catch{return null}}export function getDemoState(){const e=l();if(!n(e))return null;try{return JSON.parse(t(e,"utf-8"))}catch{return null}}export function getExamState(){return getRealExamState()||getDemoState()}export function saveExamState(t){const n=m(t.session.examId);e(n,JSON.stringify(t,null,2));try{o(n,384)}catch{}}export function clearExamState(t){if(t){const e=m(t);n(e)&&a(e)}else{const t=getExamState();if(t){const e=m(t.session.examId);n(e)&&a(e)}}}function d(t){if(!t.session.durationMinutes)return null;const{deadlineServerMs:e,clockOffsetMs:n}=t.session;if("number"==typeof e&&"number"==typeof n)return new Date(e-n);const a=t.session.confirmedAt||t.session.startedAt,r=new Date(a).getTime();return new Date(r+60*t.session.durationMinutes*1e3)}export function getExamDeadline(){const t=getExamState();return t?d(t):null}export function getRealExamDeadline(){const t=getRealExamState();return t?d(t):null}let p=!1;export async function refetchQuestionDataIfStale(){const t=getRealExamState();if(!t)return null;if(p)return t;const e=t.session.token;if(!e)return t;if(!t.questions.some(t=>{if("ai4ctf"!==t.type&&"ctf4ai"!==t.type)return!1;const e=String(t.description||"");return(e.includes("attachedData")||/base64 blob/i.test(e))&&!t.attachedData}))return t;p=!0;try{const{getConfig:n}=await import("./config.js"),a=n(),r=a.ctfdUrl||"https://practice.icoa2026.au",o=a.language||"en",i=await fetch(`${r}/api/icoa/exam-token`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({token:e,deviceHash:"",lang:o}),signal:AbortSignal.timeout(8e3)});if(!i.ok)return t;const s=await i.json(),c=s?.data?.questions||[];if(0===c.length)return t;const u=new Map;for(const t of c)u.set(t.number,t);let f=0;for(const e of t.questions){const t=u.get(e.number);t&&(t.attachedData&&!e.attachedData&&(e.attachedData=t.attachedData,f++),t.description&&(!e.description||t.description.length>e.description.length)&&(e.description=t.description))}return f>0&&saveExamState(t),t}catch{return t}}
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync, chmodSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { getIcoaDir } from './config.js';
+/**
+ * Write a practical question's attachedData blob to the contestant's
+ * workspace so they can use shell / python / editor tooling on it without
+ * pasting the whole base64 back in on the command line.
+ *
+ * Because `!shell` / `!python3` inside the REPL runs in the sandbox
+ * container (which only mounts its own challenges volume, not the host's
+ * workspace), we also mirror the file into the sandbox at
+ * /home/competitor/challenges/q<n>.txt via `docker cp` when the sandbox
+ * is running. Returns the path students should reference —
+ * sandbox-visible when the sandbox is up, else host — so the
+ * "Ways to solve" block points at a file that actually exists wherever
+ * `!command` executes.
+ *
+ * Silent on failure: null means no workspace file was materialized, and
+ * callers skip the solve-paths guidance.
+ */
+/**
+ * Map a practical question's TYPE to the AI chat command a contestant should
+ * enter for it. The practical section is interleaved (standard paper:
+ * Q38 ctf4ai, Q39 ai4ctf, Q40 ctf4ai; Paper E: Q37-46 ai4ctf, Q47-48 ctf4ai),
+ * so routing by question NUMBER misroutes questions to the wrong engine — the
+ * root cause behind both the old printSectionIntro bug and the practical
+ * answer-nudge in repl.ts. Always route by type.
+ *
+ * Returns null for MCQ / short-answer / unknown types, and (when not a real
+ * exam, i.e. the demo) since the demo has no live AI chat sections.
+ */
+export function practicalChatCommand(qType, isReal) {
+    if (!isReal)
+        return null;
+    if (qType === 'ctf4ai')
+        return 'ctf4ai';
+    if (qType === 'ai4ctf')
+        return 'ai4ctf';
+    if (qType === 'vla')
+        return 'ctf4eai';
+    return null;
+}
+export function materializeAttachedData(qNum, data) {
+    if (!data)
+        return null;
+    let hostPath;
+    try {
+        // Prefer the active exam's per-exam tmpdir (L1 anti-cheat workspace) so
+        // contestants see their question file in the same dir their `!cmd`
+        // invocations land in. Falls back to ~/icoa-workspace pre-start.
+        const state = getRealExamState();
+        const examWorkspace = state?.session?.workspaceDir;
+        const workspace = examWorkspace && existsSync(examWorkspace) ? examWorkspace : join(homedir(), 'icoa-workspace');
+        mkdirSync(workspace, { recursive: true });
+        hostPath = join(workspace, `q${qNum}.txt`);
+        writeFileSync(hostPath, data, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    // If the sandbox container is up, copy the file inside so `!command`
+    // invocations can reach it at a stable path. Uses execFileSync (no
+    // shell) because qNum is numeric and hostPath is trusted, but we still
+    // avoid string concatenation into a shell. A no-op when the container
+    // isn't running — we just swallow any error and fall back to host.
+    try {
+        execFileSync('docker', ['cp', hostPath, `icoa-sandbox:/home/competitor/challenges/q${qNum}.txt`], {
+            stdio: 'ignore',
+            timeout: 3000,
+        });
+        return `challenges/q${qNum}.txt`;
+    }
+    catch {
+        return hostPath;
+    }
+}
+// Demo and real exam use separate state files so they don't block each other
+function stateFile() {
+    return join(getIcoaDir(), 'exam-state.json');
+}
+function demoStateFile() {
+    return join(getIcoaDir(), 'demo-state.json');
+}
+// Internal: pick the right file based on examId
+function resolveStateFile(examId) {
+    return examId === 'demo-free' ? demoStateFile() : stateFile();
+}
+export function getRealExamState() {
+    const f = stateFile();
+    if (!existsSync(f))
+        return null;
+    try {
+        const state = JSON.parse(readFileSync(f, 'utf-8'));
+        // Pre-v2.19.45 versions stored demo state in exam-state.json with
+        // examId='demo-free'. After v2.19.45 demo moved to demo-state.json.
+        // Ignore stale demo-tagged content found in the real-exam file —
+        // it's contamination from an old install. Also auto-clean the file.
+        if (state?.session?.examId === 'demo-free') {
+            try {
+                unlinkSync(f);
+            }
+            catch { }
+            return null;
+        }
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+export function getDemoState() {
+    const f = demoStateFile();
+    if (!existsSync(f))
+        return null;
+    try {
+        return JSON.parse(readFileSync(f, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function getExamState() {
+    // Real exam ALWAYS takes priority over demo when both exist.
+    // Reasoning: real exam is token-gated, has a timer, and represents a serious
+    // commitment. Demo is casual practice. If a real exam is in progress, all
+    // shared commands (exam q N, exam answer, ai4ctf, ctf4ai) must target the
+    // real exam — never silently fall back to demo questions, even if demo was
+    // run more recently. (Demo→Exam→Finals progression principle, exam.md §0)
+    const real = getRealExamState();
+    if (real)
+        return real;
+    return getDemoState();
+}
+export function saveExamState(state) {
+    const f = resolveStateFile(state.session.examId);
+    writeFileSync(f, JSON.stringify(state, null, 2));
+    // V16 (v2.19.181): exam-state.json holds session.token in plaintext.
+    // 0o600 so other users on shared hosts can't read it.
+    try {
+        chmodSync(f, 0o600);
+    }
+    catch {
+        /* ignore Windows / restricted FS */
+    }
+}
+export function clearExamState(examId) {
+    if (examId) {
+        const f = resolveStateFile(examId);
+        if (existsSync(f))
+            unlinkSync(f);
+    }
+    else {
+        // Clear the currently active exam
+        const state = getExamState();
+        if (state) {
+            const f = resolveStateFile(state.session.examId);
+            if (existsSync(f))
+                unlinkSync(f);
+        }
+    }
+}
+/** Pure: compute the deadline for a given exam state, or null if the
+ *  session has no time limit. Shared by getExamDeadline (priority-aware)
+ *  and getRealExamDeadline (real-exam file only). */
+function computeDeadline(state) {
+    if (!state.session.durationMinutes)
+        return null; // 0 = no time limit
+    // Preferred path: server-time sync succeeded at exam start. deadlineServerMs
+    // is the authoritative server-time moment of expiry. Convert back to local
+    // clock domain so existing callers (which compare against Date.now()) stay
+    // correct even if the local clock drifts from server.
+    const { deadlineServerMs, clockOffsetMs } = state.session;
+    if (typeof deadlineServerMs === 'number' && typeof clockOffsetMs === 'number') {
+        return new Date(deadlineServerMs - clockOffsetMs);
+    }
+    // Fallback: local-clock-only (pre-v2.19.85 behavior). Accurate as long as
+    // client and server clocks agree; off by the clock skew otherwise.
+    const startTime = state.session.confirmedAt || state.session.startedAt;
+    const start = new Date(startTime).getTime();
+    return new Date(start + state.session.durationMinutes * 60 * 1000);
+}
+export function getExamDeadline() {
+    const state = getExamState();
+    return state ? computeDeadline(state) : null;
+}
+/** Deadline read from the real-exam state file specifically, bypassing
+ *  getExamState()'s real-over-demo priority. Used by `exam demo` to
+ *  detect a parked expired real exam that would otherwise block demo. */
+export function getRealExamDeadline() {
+    const state = getRealExamState();
+    return state ? computeDeadline(state) : null;
+}
+/**
+ * Back-fill missing attachedData / description on practical questions by
+ * re-fetching from the server. Older state files (saved before v2.19.104)
+ * may have questions whose attachedData was dropped or never stored, leaving
+ * the contestant stuck on Q31-37 ("where is the attached file?"). This runs
+ * at most once per REPL session and is a no-op if:
+ *   - no session token is stored (can't authenticate the refetch)
+ *   - all practical questions already have attachedData
+ *   - the network is unreachable
+ * Returns the (possibly updated) state so callers can use it directly.
+ */
+let _resyncAttempted = false;
+export async function refetchQuestionDataIfStale() {
+    const state = getRealExamState();
+    if (!state)
+        return null;
+    if (_resyncAttempted)
+        return state;
+    const token = state.session.token;
+    if (!token)
+        return state;
+    // Only refetch if at least one practical question references attachedData
+    // but doesn't have it locally — otherwise we'd burn a server round-trip
+    // on every ai4ctf entry.
+    const needsRefetch = state.questions.some((q) => {
+        const isPractical = q.type === 'ai4ctf' || q.type === 'ctf4ai';
+        if (!isPractical)
+            return false;
+        const desc = String(q.description || '');
+        const mentionsAttached = desc.includes('attachedData') || /base64 blob/i.test(desc);
+        return mentionsAttached && !q.attachedData;
+    });
+    if (!needsRefetch)
+        return state;
+    _resyncAttempted = true;
+    try {
+        const { getConfig } = await import('./config.js');
+        const config = getConfig();
+        const serverUrl = config.ctfdUrl || 'https://practice.icoa2026.au';
+        const lang = config.language || 'en';
+        const res = await fetch(`${serverUrl}/api/icoa/exam-token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token, deviceHash: '', lang }),
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!res.ok)
+            return state;
+        const json = (await res.json());
+        const fresh = json?.data?.questions || [];
+        if (fresh.length === 0)
+            return state;
+        // Merge: for every local question, if the fresh copy has attachedData or
+        // a longer description, copy those fields in. Keep local answer state /
+        // eliminated options etc. untouched — we only patch read-only content.
+        const byNum = new Map();
+        for (const fq of fresh)
+            byNum.set(fq.number, fq);
+        let patched = 0;
+        for (const q of state.questions) {
+            const fq = byNum.get(q.number);
+            if (!fq)
+                continue;
+            if (fq.attachedData && !q.attachedData) {
+                q.attachedData = fq.attachedData;
+                patched++;
+            }
+            if (fq.description && (!q.description || fq.description.length > q.description.length)) {
+                q.description = fq.description;
+            }
+        }
+        if (patched > 0)
+            saveExamState(state);
+        return state;
+    }
+    catch {
+        return state;
+    }
+}

package/dist/lib/gemini.js

@@ -1 +1,247 @@
-import{GoogleGenAI as e}from"@google/genai";import chalk from"chalk";import{readFileSync as t}from"node:fs";import{dirname as n,join as o}from"node:path";import{fileURLToPath as a}from"node:url";import{getConfig as r,saveConfig as s}from"./config.js";import{getRealExamState as i}from"./exam-state.js";const c=n(a(import.meta.url));let l=null;function u(){if(l)return l;try{const e=JSON.parse(t(o(c,"..","..","package.json"),"utf-8"));l=e.version||"unknown"}catch{l="unknown"}return l}export async function translateText(e,t){throw new Error("Local AI model path has been disabled (2026-04-24). ICOA provides all AI server-side — no API key setup needed. Use `ai4ctf` (chat) or `exam` (with integrated help/hint) instead.")}export function setApiKey(e){s({geminiApiKey:e})}export async function createChatSession(e,t){const n=r();let o=t||"You are an AI teammate in the ICOA cybersecurity CTF competition (International Cyber Olympiad in AI 2026, Sydney).\n\nYou're a friendly, knowledgeable cybersecurity partner — like a fellow competitor sitting next to the user. Be conversational, encouraging, and collaborative.\n\nRULES:\n- Help the competitor think through challenges, brainstorm approaches, explain concepts\n- You MAY discuss vulnerability types, tools, techniques, and methodologies\n- You MAY suggest approaches and help debug code\n- Do NOT provide complete working exploits or full solution scripts\n- Do NOT provide flags or flag fragments\n- Never output anything matching flag format: icoa{...}\n- If you don't know something, say so honestly\n- Keep responses concise unless the user asks for detail\n- When the user opens a challenge, use the context to give relevant advice";e&&(o+=`\n\nThe competitor is currently working on:\nChallenge: ${e.name}\nCategory: ${e.category}`),o+='\n\nINTEGRITY — give method, not the produced answer:\n- You may name the tool/command/technique (e.g. "this is base64; run base64 -d on the file").\n- Do NOT perform a solution step for the competitor and hand back its result: never decode,\n  decrypt, deobfuscate, run, execute, or compute over data they paste or that is attached,\n  and then reveal the produced value. They must run it themselves and read the output.\n- Do NOT reveal the exact final answer, and never output icoa{...} / flag{...} in any case.\n- If asked to "just give the answer" / "solve it" / "decode this and tell me", refuse and\n  nudge them to do the step themselves.';const a=n.ctfdUrl||"https://practice.icoa2026.au",s=n.deviceFingerprint||"",c=n.geminiModel||"gemini-2.5-flash-lite",l=[];return{async sendMessage(e){l.push({role:"user",text:e});const t=i(),r={systemPrompt:o,messages:l,model:c,maxTokens:2048,deviceFingerprint:s};t?.session?.token&&(r.examToken=t.session.token);const p={"Content-Type":"application/json","User-Agent":`icoa-cli/${u()}`,"X-Device-Fingerprint":s};!r.examToken&&n.ctfdUrl&&n.token&&n.userName&&(r.account=n.userName,p.Authorization=`Token ${n.token}`);const d=e=>new Promise(t=>setTimeout(t,e)),h=[2e3,5e3];let m=null,g=null;for(let e=0;e<=h.length&&(m=await fetch(`${a}/api/icoa/ai/chat`,{method:"POST",headers:p,body:JSON.stringify(r),signal:AbortSignal.timeout(6e4)}),!m.ok&&429===m.status);e++)e<h.length?await d(h[e]):g=m;if(!m)throw new Error("AI proxy: no response");if(!m.ok){const e=(await m.json().catch(()=>({message:"AI proxy error"}))).message||`AI proxy returned ${m.status}`;if(401===m.status)throw new Error(`${chalk.yellow("⚠ ")}Exam token expired. Re-enter via \`exam <token>\`.`);if(403===m.status)throw new Error(chalk.yellow("⚠ ")+e);if(429===m.status)throw new Error(chalk.yellow("⏳ ")+e+chalk.gray(" (retried twice — quota burst, try again in ~30s)"));throw new Error(e)}const f=await m.json(),y=function(e){return e.replace(/icoa\{[^}]*\}/gi,"[FLAG REDACTED]")}(f.data?.text||""),w=f.data?.tokensUsed||0,v="number"==typeof f.data?.accountSpent?f.data.accountSpent:void 0,k="number"==typeof f.data?.accountCap?f.data.accountCap:void 0;return l.push({role:"model",text:y}),{text:y,tokensUsed:w,accountSpent:v,accountCap:k}}}}
+import { GoogleGenAI } from '@google/genai';
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfig, saveConfig } from './config.js';
+import { getRealExamState } from './exam-state.js';
+const __dirname_gemini = dirname(fileURLToPath(import.meta.url));
+let _cachedVersion = null;
+function getCliVersion() {
+    if (_cachedVersion)
+        return _cachedVersion;
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname_gemini, '..', '..', 'package.json'), 'utf-8'));
+        _cachedVersion = pkg.version || 'unknown';
+    }
+    catch {
+        _cachedVersion = 'unknown';
+    }
+    return _cachedVersion;
+}
+const SYSTEM_PROMPTS = {
+    A: `You are an AI assistant in a cybersecurity CTF competition called ICOA.
+You are providing Level A (General Guidance) to a competitor.
+
+STRICT RULES:
+- Only answer conceptual questions
+- Do NOT mention specific vulnerability names
+- Do NOT provide any code, commands, or tool usage
+- Do NOT mention specific attack techniques
+- Use questions to guide the competitor toward their own discovery
+- If the competitor asks you to solve the challenge, refuse and redirect
+- Never output anything matching flag format: icoa{...}`,
+    B: `You are an AI assistant in ICOA CTF, providing Level B (Deep Analysis).
+
+RULES:
+- You MAY identify specific vulnerability types (e.g., "buffer overflow")
+- You MAY suggest which category of tool to use (e.g., "a debugger")
+- Do NOT provide complete commands or working code
+- Do NOT provide exploit code or payloads
+- Do NOT provide flags or flag fragments
+- Never output anything matching: icoa{...}`,
+    C: `You are an AI assistant in ICOA CTF, providing Level C (Critical Assist).
+
+RULES:
+- You MAY provide the key conceptual breakthrough
+- You MAY name specific algorithms or approaches
+- Do NOT provide complete exploit code
+- Do NOT provide the flag
+- Never output anything matching: icoa{...}`,
+};
+function _buildSystemPrompt(level, context) {
+    let prompt = SYSTEM_PROMPTS[level];
+    if (context) {
+        prompt += `\n\nThe competitor is currently working on:\nChallenge: ${context.name}\nCategory: ${context.category}`;
+    }
+    prompt += METHOD_NOT_ANSWER_RULE;
+    return prompt;
+}
+function filterFlagPatterns(text) {
+    return text.replace(/icoa\{[^}]*\}/gi, '[FLAG REDACTED]');
+}
+// No DEFAULT_API_KEY in client code — keys stay server-side only.
+// 2026-04-24: **Local model path disabled**. All AI routes through the
+// server proxy at /api/icoa/ai/chat regardless of whether the user has
+// their own GEMINI_API_KEY. See reference_ai_models.md / feedback_icoa_all_keys.md.
+// ICOA centrally owns all AI keys; students do not need to configure anything.
+const LOCAL_MODEL_DISABLED_MESSAGE = 'Local AI model path has been disabled (2026-04-24). ' +
+    'ICOA provides all AI server-side — no API key setup needed. ' +
+    'Use `ai4ctf` (chat) or `exam` (with integrated help/hint) instead.';
+function getApiKey() {
+    // Returns empty string to disable Path A in createChatSession / generateHint.
+    // Preserved as a function to keep the call sites stable for future refactors.
+    return '';
+}
+function getClient(apiKey) {
+    return new GoogleGenAI({ apiKey });
+}
+/**
+ * @deprecated Runtime translation is disabled. Translations are pre-baked
+ * at build time via `panda/translate-*.js` scripts and shipped in
+ * `translations/<lang>/` — CLI never translates at runtime.
+ */
+export async function translateText(_text, _targetLang) {
+    throw new Error(LOCAL_MODEL_DISABLED_MESSAGE);
+}
+export function setApiKey(key) {
+    saveConfig({ geminiApiKey: key });
+}
+const CHAT_SYSTEM_PROMPT = `You are an AI teammate in the ICOA cybersecurity CTF competition (International Cyber Olympiad in AI 2026, Sydney).
+
+You're a friendly, knowledgeable cybersecurity partner — like a fellow competitor sitting next to the user. Be conversational, encouraging, and collaborative.
+
+RULES:
+- Help the competitor think through challenges, brainstorm approaches, explain concepts
+- You MAY discuss vulnerability types, tools, techniques, and methodologies
+- You MAY suggest approaches and help debug code
+- Do NOT provide complete working exploits or full solution scripts
+- Do NOT provide flags or flag fragments
+- Never output anything matching flag format: icoa{...}
+- If you don't know something, say so honestly
+- Keep responses concise unless the user asks for detail
+- When the user opens a challenge, use the context to give relevant advice`;
+// Shared "method, not answer" rule appended to every system prompt. The
+// server (token-api.py) enforces the authoritative copy of these rules so a
+// modified/curl client can't strip them; this client copy keeps the stock CLI
+// well-behaved without a server round-trip. Phrased to allow naming the
+// command but forbid performing the step and returning its result.
+const METHOD_NOT_ANSWER_RULE = `
+
+INTEGRITY — give method, not the produced answer:
+- You may name the tool/command/technique (e.g. "this is base64; run base64 -d on the file").
+- Do NOT perform a solution step for the competitor and hand back its result: never decode,
+  decrypt, deobfuscate, run, execute, or compute over data they paste or that is attached,
+  and then reveal the produced value. They must run it themselves and read the output.
+- Do NOT reveal the exact final answer, and never output icoa{...} / flag{...} in any case.
+- If asked to "just give the answer" / "solve it" / "decode this and tell me", refuse and
+  nudge them to do the step themselves.`;
+export async function createChatSession(context, customSystemPrompt) {
+    const config = getConfig();
+    const apiKey = getApiKey();
+    let systemPrompt = customSystemPrompt || CHAT_SYSTEM_PROMPT;
+    if (context) {
+        systemPrompt += `\n\nThe competitor is currently working on:\nChallenge: ${context.name}\nCategory: ${context.category}`;
+    }
+    // Always append the integrity rule (covers chat + exam custom prompts).
+    systemPrompt += METHOD_NOT_ANSWER_RULE;
+    // ─── Path A: user has their own key → direct Gemini SDK ───
+    if (apiKey) {
+        const modelName = config.geminiModel || 'gemini-2.5-flash-lite';
+        const ai = getClient(apiKey);
+        const chat = ai.chats.create({
+            model: modelName,
+            config: { systemInstruction: systemPrompt },
+        });
+        return {
+            async sendMessage(msg) {
+                const response = await chat.sendMessage({ message: msg });
+                const text = filterFlagPatterns(response.text ?? '');
+                const usage = response.usageMetadata;
+                const tokensUsed = usage?.totalTokenCount || (usage?.promptTokenCount || 0) + (usage?.candidatesTokenCount || 0);
+                return { text, tokensUsed };
+            },
+        };
+    }
+    // ─── Path B: no key → server proxy (key stays server-side) ───
+    const serverUrl = config.ctfdUrl || 'https://practice.icoa2026.au';
+    const fp = config.deviceFingerprint || '';
+    const modelName = config.geminiModel || 'gemini-2.5-flash-lite';
+    const messages = [];
+    return {
+        async sendMessage(msg) {
+            messages.push({ role: 'user', text: msg });
+            // Attach exam token if contestant is in a real exam — grants full
+            // 2048 maxTokens and higher rate limit. Demo/anonymous users rely on
+            // the User-Agent gate on the server side.
+            const realExam = getRealExamState();
+            const payload = {
+                systemPrompt,
+                messages,
+                model: modelName,
+                maxTokens: 2048,
+                deviceFingerprint: fp,
+            };
+            if (realExam?.session?.token) {
+                payload.examToken = realExam.session.token;
+            }
+            // CTFd-join account binding (2026-06-17, AU-camp audit). When connected
+            // to a CTFd event (no exam token), attribute AI usage to the logged-in
+            // account so the server can (a) audit per-student and (b) meter a
+            // per-account budget — a shared-NAT room can no longer pool unlimited
+            // AI. Ignored server-side when an exam token is present (exam-token
+            // budget wins); demo/practice has no CTFd login → no account → stays on
+            // the client 5k cap.
+            //
+            // 2026-06-20 (Olympic audit upgrade): also send the CTFd API token in an
+            // Authorization header so the server can VERIFY the account against CTFd's
+            // own tokens→users tables instead of trusting the self-reported username
+            // below. The header turns attribution from a forgeable signal into
+            // evidence (account_verified=1 server-side). payload.account stays as a
+            // fallback for any pre-upgrade server. Mirrors the /api/icoa/audit auth.
+            const reqHeaders = {
+                'Content-Type': 'application/json',
+                'User-Agent': `icoa-cli/${getCliVersion()}`,
+                'X-Device-Fingerprint': fp,
+            };
+            if (!payload.examToken && config.ctfdUrl && config.token && config.userName) {
+                payload.account = config.userName;
+                reqHeaders.Authorization = `Token ${config.token}`;
+            }
+            // V2.19.185: 429 retry-with-backoff. UZ Paper A (2026-05-17) had a
+            // sustained Gemini upstream quota burst that caused 45 client-visible
+            // 429s. Server-side key rotation eventually recovers, so a short
+            // backoff before retrying transparently absorbs most transient dips
+            // without the contestant ever seeing an error. We retry up to twice
+            // with 2s and 5s backoff (max ~7s added latency on a worst-case path).
+            // 401/403 are surfaced immediately — they need contestant action.
+            const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+            const BACKOFFS_MS = [2000, 5000];
+            let res = null;
+            let lastErr = null;
+            for (let attempt = 0; attempt <= BACKOFFS_MS.length; attempt++) {
+                res = await fetch(`${serverUrl}/api/icoa/ai/chat`, {
+                    method: 'POST',
+                    headers: reqHeaders,
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(60_000),
+                });
+                if (res.ok || res.status !== 429)
+                    break;
+                // 429 — try again after backoff if we have budget left
+                if (attempt < BACKOFFS_MS.length) {
+                    await sleepMs(BACKOFFS_MS[attempt]);
+                    continue;
+                }
+                // Out of retries — fall through to error handling below
+                lastErr = res;
+            }
+            if (!res)
+                throw new Error('AI proxy: no response');
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({ message: 'AI proxy error' })));
+                const msg = err.message || `AI proxy returned ${res.status}`;
+                if (res.status === 401) {
+                    throw new Error(`${chalk.yellow('⚠ ')}Exam token expired. Re-enter via \`exam <token>\`.`);
+                }
+                if (res.status === 403) {
+                    throw new Error(chalk.yellow('⚠ ') + msg);
+                }
+                if (res.status === 429) {
+                    throw new Error(chalk.yellow('⏳ ') + msg + chalk.gray(' (retried twice — quota burst, try again in ~30s)'));
+                }
+                throw new Error(msg);
+            }
+            const json = (await res.json());
+            const text = filterFlagPatterns(json.data?.text || '');
+            const tokensUsed = json.data?.tokensUsed || 0;
+            // Server-authoritative cumulative per-account spend (CTFd-join comp mode).
+            // Present only when the server metered a verified account; the client uses
+            // it to render a TRUE budget bar instead of a per-session counter.
+            const accountSpent = typeof json.data?.accountSpent === 'number' ? json.data.accountSpent : undefined;
+            const accountCap = typeof json.data?.accountCap === 'number' ? json.data.accountCap : undefined;
+            messages.push({ role: 'model', text });
+            return { text, tokensUsed, accountSpent, accountCap };
+        },
+    };
+}