gipity 1.1.5 → 1.1.6

package/dist/agents/agy.js

@@ -0,0 +1,52 @@
+/** LLM_MODELS canonical id -> agy's own spaced --model display string, for the
+ *  subset of the Gemini catalog agy actually offers. Anything not listed here
+ *  passes through translateModel() unchanged - either it's already agy's own
+ *  format (a human typed it directly), or it's a Gemini id agy doesn't have an
+ *  equivalent for, in which case agy's own `--model` validation is the right
+ *  place to reject it, not a guess made here. */
+const MODEL_ID_TO_AGY_DISPLAY = {
+    'gemini-3.5-flash': 'Gemini 3.5 Flash (Medium)',
+    'gemini-3.1-pro-preview': 'Gemini 3.1 Pro (High)',
+};
+function translateModel(model) {
+    return MODEL_ID_TO_AGY_DISPLAY[model] ?? model;
+}
+function projectArgs(resume) {
+    return resume ? ['--conversation', resume] : ['--new-project'];
+}
+export const agyAdapter = {
+    key: 'agy',
+    source: 'agy',
+    displayName: 'Antigravity',
+    providerName: 'Google',
+    binary: 'agy',
+    buildInteractiveArgs({ resume, model }) {
+        const args = [...projectArgs(resume)];
+        if (model)
+            args.push('--model', translateModel(model));
+        return args;
+    },
+    buildHeadlessArgs({ message, resume, model, bypassApprovals }) {
+        const args = ['-p', message, ...projectArgs(resume)];
+        if (model)
+            args.push('--model', translateModel(model));
+        if (bypassApprovals)
+            args.push('--dangerously-skip-permissions');
+        return args;
+    },
+    sessionIdFromStreamEvent() {
+        // agy has no --json/--output-format flag (confirmed: `agy --help` lists
+        // none, and `-p` stdout is plain prose) - there is no stream to read a
+        // session id off. Capture relies entirely on hooks (see class comment).
+        return null;
+    },
+    hooksSupportedOnPlatform(platform) {
+        return platform !== 'win32'; // agy's hooks.json wiring is POSIX-only, like Codex's
+    },
+    // No stream-json ingest mapper for agy: hook capture carries the full
+    // conversationId on every event (confirmed live, including headless -p),
+    // so the daemon doesn't need to parse agy's stdout at all.
+    daemonStreamCapture: false,
+    installHint: 'see https://antigravity.google (Google account sign-in required)',
+};
+//# sourceMappingURL=agy.js.map

package/dist/agents/index.js

@@ -1,11 +1,13 @@
 import { claudeCodeAdapter } from './claude-code.js';
 import { codexAdapter } from './codex.js';
 import { grokAdapter } from './grok.js';
+import { agyAdapter } from './agy.js';
 /** Picker/help order: Claude first (the default), then the others. */
 export const AGENT_ADAPTERS = [
     claudeCodeAdapter,
     codexAdapter,
     grokAdapter,
+    agyAdapter,
 ];
 export const AGENT_KEYS = AGENT_ADAPTERS.map(a => a.key);
 export function getAdapter(key) {

package/dist/api.js

@@ -366,12 +366,12 @@ export async function getAccountSlug() {
 /** Unauthenticated request (for login/verify, and anonymous-visitor calls like
  *  `fn call --anon`). extraHeaders lets callers attach non-auth headers such as
  *  X-App-Token; no Authorization header is ever sent. */
-export async function publicPost(path, body, extraHeaders) {
+export async function publicRequest(method, path, body, extraHeaders) {
     const url = `${baseUrl()}${path}`;
     const res = await fetch(url, {
-        method: 'POST',
+        method,
         headers: { ...clientHeaders(), 'Content-Type': 'application/json', ...extraHeaders },
-        body: JSON.stringify(body),
+        body: body === undefined ? undefined : JSON.stringify(body),
     });
     if (!res.ok) {
         const json = await res.json().catch(() => ({ error: { code: 'UNKNOWN', message: res.statusText } }));
@@ -380,4 +380,20 @@ export async function publicPost(path, body, extraHeaders) {
     }
     return res.json();
 }
+export function publicPost(path, body, extraHeaders) {
+    return publicRequest('POST', path, body, extraHeaders);
+}
+/** Mint the short-lived public app token the browser SDK uses, so a CLI call can
+ *  exercise the exact path a signed-out visitor hits. Best-effort: fully public
+ *  surfaces work with no token at all, and an auth-gated one should 401 with the
+ *  server's real reason rather than a CLI-invented one. */
+export async function mintAppToken(projectGuid) {
+    try {
+        const minted = await publicPost('/api/token', { app: projectGuid });
+        return { 'X-App-Token': minted.data.token };
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=api.js.map

package/dist/capture/sources/agy.js

@@ -0,0 +1,88 @@
+const USER_REQUEST_RE = /<USER_REQUEST>\s*([\s\S]*?)\s*<\/USER_REQUEST>/;
+function extractUserRequest(content) {
+    const m = USER_REQUEST_RE.exec(content);
+    return m ? m[1].trim() : content.trim();
+}
+function positional(conversationId, idx) {
+    return `${conversationId}#${idx}`;
+}
+function watermarkIndex(afterUuid, conversationId) {
+    if (!afterUuid || !conversationId)
+        return null;
+    const prefix = `${conversationId}#`;
+    if (!afterUuid.startsWith(prefix))
+        return null;
+    const idx = parseInt(afterUuid.slice(prefix.length), 10);
+    return Number.isInteger(idx) && idx >= 0 ? idx : null;
+}
+function lineToEntries(parsed, conversationId, idx) {
+    const ts = typeof parsed?.created_at === 'string' ? parsed.created_at : undefined;
+    const type = parsed?.type;
+    const content = parsed?.content;
+    const uuid = positional(conversationId, idx);
+    if (type === 'USER_INPUT' && typeof content === 'string' && content) {
+        const prompt = extractUserRequest(content);
+        if (!prompt)
+            return [];
+        return [{ kind: 'prompt', prompt, source_uuid: uuid, ...(ts ? { ts } : {}) }];
+    }
+    if (type === 'PLANNER_RESPONSE') {
+        if (typeof content !== 'string' || !content)
+            return []; // thinking-only turn, nothing user-visible
+        return [{
+                kind: 'assistant',
+                text: content,
+                blocks: [{ type: 'text', text: content }],
+                source_uuid: uuid,
+                ...(ts ? { ts } : {}),
+            }];
+    }
+    if (type === 'CODE_ACTION') {
+        if (typeof content !== 'string' || !content)
+            return [];
+        return [{ kind: 'system', content, source_uuid: uuid, ...(ts ? { ts } : {}) }];
+    }
+    return []; // CONVERSATION_HISTORY, EPHEMERAL_MESSAGE, CHECKPOINT, SYSTEM_MESSAGE, unknown
+}
+/** Same contract as the other source parsers: entries after `afterUuid`, the
+ *  new watermark, and whether the old watermark was still valid for this
+ *  file. `conversationId` comes from the hook payload (capture-runner passes
+ *  it as `hook.session_id`), not from the file content - agy's transcript
+ *  lines carry no conversation/session id field of their own. */
+export function parseTranscript(content, afterUuid, opts = {}) {
+    const conversationId = opts.conversationId ?? '';
+    const lines = content.split('\n');
+    // A watermark past EOF means the file was replaced by a shorter one under
+    // the same conversation id (mirrors the Codex parser's resume-rotation
+    // guard) - treat as not-found so the caller replays from the top instead of
+    // wedging forever.
+    let startAfter = watermarkIndex(afterUuid, conversationId);
+    if (startAfter !== null && startAfter >= lines.length)
+        startAfter = null;
+    const foundWatermark = afterUuid === null || startAfter !== null;
+    const out = [];
+    let lastIdx = startAfter;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (startAfter !== null && i <= startAfter)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        for (const e of lineToEntries(parsed, conversationId, i))
+            out.push(e);
+        lastIdx = i;
+    }
+    return {
+        entries: out,
+        lastUuid: lastIdx === null ? afterUuid : positional(conversationId, lastIdx),
+        foundWatermark,
+    };
+}
+//# sourceMappingURL=agy.js.map

package/dist/client-context.js

@@ -29,6 +29,15 @@ export function detectHarness() {
         return { harness: 'codex' };
     if (hasEnvPrefix('GROK_'))
         return { harness: 'grok', harnessSession: process.env.GROK_SESSION_ID };
+    // Antigravity (agy) injects ANTIGRAVITY_CONVERSATION_ID into every hook/tool
+    // subprocess it spawns (confirmed live). Check this exact var, not an
+    // 'ANTIGRAVITY_' prefix scan - the Antigravity IDE's own integrated terminal
+    // ambiently sets other ANTIGRAVITY_*-prefixed vars (e.g. ANTIGRAVITY_CLI_ALIAS)
+    // in every shell it spawns, which would false-positive for any user with the
+    // IDE open, even outside a real agy session/hook.
+    if (process.env.ANTIGRAVITY_CONVERSATION_ID) {
+        return { harness: 'agy', harnessSession: process.env.ANTIGRAVITY_CONVERSATION_ID };
+    }
     if (process.env.CURSOR_TRACE_ID || hasEnvPrefix('CURSOR_') || (process.env.TERM_PROGRAM ?? '').toLowerCase().includes('cursor')) {
         return { harness: 'cursor' };
     }

package/dist/commands/brand.js

@@ -0,0 +1,125 @@
+/**
+ * `gipity brand` - view or change the app's generated visual identity:
+ * favicons, the iOS Home Screen icon, the PWA manifest, and the 1200x630
+ * social share card (og-image) that X/iMessage/Slack show when the app's
+ * URL is shared.
+ *
+ * The default identity is deterministic (accent color from the project guid,
+ * glyph from the title's first character, small Gipity egg badge). `brand set`
+ * overrides pieces of it - most usefully the glyph (an emoji reads far more
+ * "this is my app" than a letter) and the accent color - then regenerates
+ * every asset server-side in one shot. Deploy afterwards to publish.
+ */
+import { Command } from 'commander';
+import { get, post } from '../api.js';
+import { resolveProjectContext } from '../config.js';
+import { bold, muted, success } from '../colors.js';
+import { run } from '../helpers/index.js';
+function printBrand(d) {
+    console.log(`${bold('Glyph:')}  ${d.resolved.glyph}${d.resolved.isEmoji ? muted(' (emoji)') : ''}`);
+    console.log(`${bold('Accent:')} ${d.resolved.accent}${d.branding.primary_color ? '' : muted(' (derived from project)')}`);
+    if (d.branding.app_name)
+        console.log(`${bold('Name:')}   ${d.branding.app_name}`);
+    if (d.branding.tagline)
+        console.log(`${bold('Tagline:')} ${d.branding.tagline}`);
+}
+const DEPLOY_HINT = 'Deploy to publish the new assets: gipity deploy dev';
+export const brandCommand = new Command('brand')
+    .description("The app's generated icons + share card (favicons, iOS icon, og-image)")
+    .addHelpText('after', `
+Examples:
+  gipity brand                                Show the current brand
+  gipity brand set --emoji 🦍                 Emoji icon + share card, regenerate all assets
+  gipity brand set --glyph R --color "#3b82f6"  Letter glyph on a blue accent
+  gipity brand set --tagline "Bananas at 60fps"  Subtitle on the share card
+  gipity brand apply                          Re-render assets from the stored brand
+  gipity brand apply --fix-head               Migrate an older app: assets + splice the
+                                              share/SEO tags into src/index.html
+
+Assets are generated server-side into src/images/ (+ src/manifest.webmanifest)
+and are versioned like any other file - rollback restores previous ones.`);
+brandCommand
+    .command('show', { isDefault: true })
+    .description('Show the stored brand and the resolved render spec')
+    .option('--project <guid-or-slug>', 'Target a specific project instead of cwd / Home')
+    .option('--json', 'Output raw JSON')
+    .action((opts) => run('Brand', async () => {
+    const { config } = await resolveProjectContext({ projectOverride: opts.project });
+    const res = await get(`/projects/${config.projectGuid}/brand`);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    printBrand(res.data);
+    console.log(muted(`\nAssets: ${(res.data.assets ?? []).join(', ')}`));
+    console.log(muted(`Change it: gipity brand set --emoji 🎨 | --glyph A | --color "#RRGGBB" | --tagline "..."`));
+}));
+brandCommand
+    .command('set')
+    .description('Change brand fields and regenerate all assets')
+    .option('--emoji <emoji>', 'Emoji glyph for the icon + share card (e.g. 🦍)')
+    .option('--glyph <char>', 'Letter/digit glyph (alias of --emoji, any single character)')
+    .option('--color <hex>', 'Accent color, #RRGGBB')
+    .option('--name <name>', 'Display name override (og/share title stays the page title)')
+    .option('--tagline <text>', 'One-line subtitle on the share card (max 120 chars)')
+    .option('--fix-head', 'Also splice the share/SEO head block into src/index.html (for apps installed before templates shipped it)')
+    .option('--no-regenerate', 'Store the fields without re-rendering assets')
+    .option('--project <guid-or-slug>', 'Target a specific project instead of cwd / Home')
+    .option('--json', 'Output raw JSON')
+    .action((opts) => run('Brand', async () => {
+    const { config } = await resolveProjectContext({ projectOverride: opts.project });
+    const body = {};
+    const glyph = opts.emoji ?? opts.glyph;
+    if (glyph)
+        body.icon_glyph = glyph;
+    if (opts.color)
+        body.primary_color = opts.color;
+    if (opts.name)
+        body.app_name = opts.name;
+    if (opts.tagline)
+        body.tagline = opts.tagline;
+    if (opts.regenerate === false)
+        body.regenerate = false;
+    if (opts.fixHead)
+        body.fix_head = true;
+    if (!glyph && !opts.color && !opts.name && !opts.tagline) {
+        console.error('Nothing to set - pass --emoji, --glyph, --color, --name, or --tagline. (gipity brand set --help; use gipity brand apply to just re-render)');
+        process.exitCode = 1;
+        return;
+    }
+    const res = await post(`/projects/${config.projectGuid}/brand`, body);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    printBrand(res.data);
+    reportFiles(res.data.files ?? []);
+}));
+brandCommand
+    .command('apply')
+    .description('Re-render all brand assets from the stored brand (no field changes)')
+    .option('--fix-head', 'Also splice the share/SEO head block into src/index.html (for apps installed before templates shipped it)')
+    .option('--project <guid-or-slug>', 'Target a specific project instead of cwd / Home')
+    .option('--json', 'Output raw JSON')
+    .action((opts) => run('Brand', async () => {
+    const { config } = await resolveProjectContext({ projectOverride: opts.project });
+    const body = opts.fixHead ? { fix_head: true } : {};
+    const res = await post(`/projects/${config.projectGuid}/brand`, body);
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    reportFiles(res.data.files ?? []);
+}));
+function reportFiles(files) {
+    if (!files.length) {
+        console.log(muted('\nStored (assets not regenerated - run gipity brand apply).'));
+        return;
+    }
+    console.log(success(`\n✓ Regenerated ${files.length} asset${files.length === 1 ? '' : 's'}.`));
+    if (files.includes('src/index.html')) {
+        console.log(success('✓ src/index.html head updated (page title/description preserved).'));
+    }
+    console.log(muted(`  ${DEPLOY_HINT}`));
+}
+//# sourceMappingURL=brand.js.map

package/dist/commands/build.js

@@ -968,7 +968,7 @@ async function pickAgent(lastUsed) {
         const notes = [];
         if (a.key === lastUsed)
             notes.push('last used');
-        if (a.key === 'codex' && !a.hooksSupportedOnPlatform(process.platform)) {
+        if ((a.key === 'codex' || a.key === 'agy') && !a.hooksSupportedOnPlatform(process.platform)) {
             notes.push('session recording unavailable on Windows');
         }
         const note = notes.length ? `  ${muted(`(${notes.join(', ')})`)}` : '';

package/dist/commands/fn.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { get, post, del, publicPost } from '../api.js';
+import { get, post, del, publicPost, mintAppToken } from '../api.js';
 import { getAuth } from '../auth.js';
 import { requireConfig, resolveApiBase } from '../config.js';
 import { error as clrError, bold, muted, success, warning } from '../colors.js';
@@ -62,13 +62,7 @@ fnCommand
  *  auth-gated function — the server's message is surfaced as-is, with no
  *  "run: gipity login" misdirection. */
 async function callAnon(projectGuid, name, body) {
-    let appToken;
-    try {
-        const minted = await publicPost('/api/token', { app: projectGuid });
-        appToken = minted.data.token;
-    }
-    catch { /* public functions work without a token; auth-gated ones will 401 with the real reason */ }
-    return publicPost(`/api/${projectGuid}/fn/${encodeURIComponent(name)}`, body, appToken ? { 'X-App-Token': appToken } : undefined);
+    return publicPost(`/api/${projectGuid}/fn/${encodeURIComponent(name)}`, body, await mintAppToken(projectGuid));
 }
 fnCommand
     .command('call <name> [body]')

package/dist/commands/init.js

@@ -23,7 +23,7 @@ function resolveTools(forFlag) {
 }
 export const initCommand = new Command('init')
     .description('Link this directory to a project')
-    .addHelpText('after', '\nWrites CLAUDE.md/AGENTS.md primer files so your AI coding tool understands Gipity, and installs the Gipity skills + file-sync hooks into the agent CLIs found on this machine (Claude Code, Codex, Grok).')
+    .addHelpText('after', '\nWrites CLAUDE.md/AGENTS.md primer files so your AI coding tool understands Gipity, and installs the Gipity skills + file-sync hooks into the agent CLIs found on this machine (Claude Code, Codex, Grok, Antigravity).')
     .argument('[name]', 'Project name/slug (defaults to current directory name)')
     .option('--agent <guid>', 'Agent GUID to use')
     .option('--no-capture', 'Don\'t record Claude Code sessions in this directory to your Gipity project (sets captureHooks: false in .gipity.json)')
@@ -177,7 +177,7 @@ Working with an existing Gipity project:
         }
         console.log(success(`Wrote primer files: ${primerSummary}.`));
         if (wantsClaude) {
-            console.log(success('Ready! Run your coding agent here (claude, codex, grok), or `gipity build` to launch one with a picker.'));
+            console.log(success('Ready! Run your coding agent here (claude, codex, grok, agy), or `gipity build` to launch one with a picker.'));
             // Recording happens by default (however Claude Code is launched), so
             // say so up front - consent should be explicit, not discovered later.
             if (opts.capture === false) {

package/dist/commands/key.js

@@ -0,0 +1,91 @@
+import { Command } from 'commander';
+import { get, post, del } from '../api.js';
+import { resolveProjectContext } from '../config.js';
+import { bold, muted, success, warning } from '../colors.js';
+import { run, printList } from '../helpers/index.js';
+/**
+ * Project API keys - the revocable secret a script, cron, or agent sends as
+ * `X-Api-Key` to write to YOUR app without a browser login.
+ *
+ * These are per-project and app-facing; `gipity token` mints account-level
+ * agent tokens (gip_at_*) that drive the CLI itself. Without this command the
+ * only mint path was raw curl, so agents asked for "a key I can generate and
+ * revoke" built their own key table instead of using the platform's.
+ */
+export const keyCommand = new Command('key')
+    .description('Manage project API keys for scripts and agents (X-Api-Key)')
+    .addHelpText('after', `
+Give a script, cron, or agent write access to your app without a login:
+
+  gipity key create "laptop importer" --role editor
+  # the script sends:  X-Api-Key: <the key printed once above>
+
+Inside a function the caller shows up as ctx.auth.via === 'api_key' with
+ctx.auth.apiKeyName set to the key's name - stamp that on rows to tell
+script-written entries from hand-entered ones. Never build your own key table.
+
+Account-level tokens that run the CLI headlessly are a different thing: see
+gipity token --help.`);
+const fmtDate = (d) => (d ? new Date(d).toLocaleDateString() : 'never');
+const projectOpt = ['--project <guid-or-slug>', 'Target a specific project instead of cwd / Home'];
+async function projectGuid(opts) {
+    const { config } = await resolveProjectContext({ projectOverride: opts.project });
+    return config.projectGuid;
+}
+keyCommand
+    .command('create <name>')
+    .description('Mint a project API key (shown once). Give it a name you will recognize later')
+    .option('--role <role>', 'viewer | editor | owner (default: viewer)', 'viewer')
+    .option('--expires-days <n>', 'Days until the key expires (default: never)')
+    .option(...projectOpt)
+    .option('--json', 'Output as JSON')
+    .action((name, opts) => run('Create', async () => {
+    const body = { name, role: opts.role };
+    if (opts.expiresDays !== undefined) {
+        const days = parseInt(opts.expiresDays, 10);
+        if (!Number.isFinite(days) || days <= 0)
+            throw new Error('--expires-days must be a positive number of days');
+        body.expires_in_days = days;
+    }
+    const res = await post(`/projects/${await projectGuid(opts)}/api-keys`, body);
+    const k = res.data;
+    if (opts.json) {
+        console.log(JSON.stringify(k));
+        return;
+    }
+    const expNote = k.expires_at ? ` (expires ${fmtDate(k.expires_at)})` : ' (never expires)';
+    console.log(success(`Created API key ${bold(k.short_guid)} "${k.name}" as ${k.role}${muted(expNote)}.`));
+    console.log('');
+    console.log(k.key);
+    console.log('');
+    console.log(muted('Send it from your script on every request:'));
+    console.log(muted(`  curl -H "X-Api-Key: ${k.key}" ...`));
+    console.log(muted(`Revoke it any time: gipity key revoke ${k.short_guid}`));
+    console.log('');
+    console.log(warning('Copy it now - it will not be shown again.'));
+}));
+keyCommand
+    .command('list')
+    .alias('ls')
+    .description('List this project\'s API keys (values are never shown again)')
+    .option(...projectOpt)
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('List', async () => {
+    const res = await get(`/projects/${await projectGuid(opts)}/api-keys`);
+    printList(res.data, opts, 'No API keys. Mint one with: gipity key create "my script" --role editor', (k) => `${bold(k.short_guid)}  ${k.name}  ${muted(`${k.role}  ${k.prefix}…  last used ${fmtDate(k.last_used_at)}  expires ${fmtDate(k.expires_at)}`)}`);
+}));
+keyCommand
+    .command('revoke <short_guid>')
+    .alias('rm')
+    .description('Revoke a project API key (instant, irreversible)')
+    .option(...projectOpt)
+    .option('--json', 'Output as JSON')
+    .action((shortGuid, opts) => run('Revoke', async () => {
+    await del(`/projects/${await projectGuid(opts)}/api-keys/${encodeURIComponent(shortGuid)}`);
+    if (opts.json) {
+        console.log(JSON.stringify({ short_guid: shortGuid, revoked: true }));
+        return;
+    }
+    console.log(success(`Revoked API key ${bold(shortGuid)}.`));
+}));
+//# sourceMappingURL=key.js.map

package/dist/commands/page-eval.js

@@ -257,6 +257,31 @@ export function budgetOverrunHint(reason, usedBudgetMs) {
         `(up to ${EVAL_SCRIPT_BUDGET_MAX_MS}), e.g. --timeout ${EVAL_SCRIPT_BUDGET_MAX_MS} — ` +
         `or gate on a ready signal instead: --wait-for '<selector>' --wait-timeout ${MAX_WAIT_MS}.`;
 }
+/** The server aborts a script whose page navigated out from under it, and tells
+ *  the caller to "split the check into two evals". For the case that actually
+ *  produces this (seed state, reload, assert the state came back), that advice
+ *  sends the caller down the wrong road: two evals are two independent page
+ *  sessions, so the second one has to re-seed before it can read anything, and
+ *  the thing being verified (a real reload restoring real persisted state) is
+ *  never exercised. `--reload` is the primitive for it: one page load, reloaded
+ *  IN PLACE with storage preserved, second expression against the post-reload
+ *  DOM. Name it here, at the exact moment the caller hand-rolled it. */
+export function navigationAbortHint(reason) {
+    if (!/navigated or reloaded/i.test(reason))
+        return null;
+    return `If you were verifying that state SURVIVES a reload, that is what --reload is for (one command, one page): ` +
+        `gipity page eval "<url>" '<seed/assert expr>' --reload '<assert-restored expr>'. ` +
+        `It reloads the page in place (localStorage/sessionStorage/cookies preserved) and reports the second result ` +
+        `separately. Splitting into two 'page eval' calls does NOT do this: each call is its own browser session, so ` +
+        `the second one starts from empty storage and never exercises the restore path.`;
+}
+/** True when the submitted script already drives the app's clock itself
+ *  (`core.advance(seconds)` on the 3D templates, the imported `advance(seconds)`
+ *  on the 2D one). Such a script does not care what the renderer paints at, so
+ *  the slow-render warning below has nothing to tell it. Exported for tests. */
+export function stepsDeterministically(script) {
+    return /\badvance\s*\(/.test(script);
+}
 /** The headless browser paints slowly, and what that MEANS depends on what the
  *  page is doing — so the one-size warning was actively misleading on a --camera
  *  run. A vision app has no loop to step: its pipeline is driven by camera
@@ -273,6 +298,8 @@ export function budgetOverrunHint(reason, usedBudgetMs) {
  *  deterministic way to wait (--wait-for) instead of inviting a wall-clock
  *  escalation that is guaranteed to be wasted. Exported for tests. */
 export function slowRenderMessage(fps, o) {
+    if (!o.camera && stepsDeterministically(o.script ?? ''))
+        return null;
     if (o.camera) {
         const frames = Math.max(1, Math.round(fps * (o.waitMs / 1000)));
         return `${warning('⚠ Slow render:')} page painted at ${fps} fps, so the app's vision pipeline ran on roughly `
@@ -382,7 +409,7 @@ export const pageEvalCommand = new Command('eval')
     .option('--file <path>', `Read the script body from a file instead of the inline <expr> arg (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<'EOF' ... EOF) with no tmp file. Runs as an async function body, so top-level return/await work. Same post-load budget as <expr> (--timeout).`)
     .option('--step <expr>', `Run another expression against the SAME loaded page, after <expr> (repeat, max ${MAX_EVAL_STEPS}). Whatever that page load paid for — a vision model coming up, a game booting, a socket connecting — stays up for every step, so an N-part check costs ONE page load instead of N. Each step gets its own in-page budget and its own reported result.`, (val, prev) => [...prev, val], [])
     .option('--fixture <path>', 'Host a local file and expose it to the eval as `fixtureUrl` (and under `fixtures` by basename) to fetch in-page. For verifying a render/parse path against a real binary (an MP3, an image) - no size limit, auto-deleted after the run. The hosted URL has permissive CORS, so `new Image(); img.crossOrigin="anonymous"; img.src=fixtureUrl` decodes untainted for a canvas/pixel read - this is the UPLOAD analog of --camera: feed a known photo/video to a file-upload vision app (web-vision-detect) and run its detector, no need to deploy a throwaway test asset into the app. Repeat for several files (single-value so it never swallows the inline <expr>).', (val, prev) => [...prev, val], [])
-    .option('--reload <expr>', 'After the first eval, reload the page IN PLACE (localStorage/sessionStorage/cookies preserved) and evaluate this second expression against the post-reload DOM. One command verifies persisted state survives a reload: seed/assert state with <expr>, then assert the restored UI here.')
+    .option('--reload <expr>', 'After the first eval, reload the page IN PLACE (localStorage/sessionStorage/cookies preserved) and evaluate this second expression against the post-reload DOM. One command verifies persisted state survives a reload ("remember it when I come back"): seed/assert state with <expr>, then assert the restored UI here. This is the ONLY way to check that - reloading inside the body aborts the eval (the result is lost with the old page), and two separate `page eval` calls are two fresh browser profiles, so the second starts from empty storage.')
     .option('--reload-file <path>', 'Read the post-reload expression from a file instead of inline --reload (mutually exclusive)')
     .option('--camera <path>', `Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser's WEBCAM feed, so a camera app's real pipeline (getUserMedia → MediaPipe/YOLOX → your app logic) runs headlessly on a frame you choose. Implies --fake-media and waits ${CAMERA_DEFAULT_WAIT_MS / 1000}s for the vision model to load. No frame handy? gipity generate image "a hand making a closed fist, palm to camera".`)
     .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so a voice/camera app runs headlessly instead of hitting its no-camera path. The feed is a built-in test pattern (and a tone) — nothing a vision model can recognize; to drive a vision app use --camera <path> instead.')
@@ -589,7 +616,10 @@ export const pageEvalCommand = new Command('eval')
             // raises it — and the flag is what the caller needs next. Name it, with
             // the value THIS run used, so the retry is an edit rather than a guess.
             const msg = err?.message ?? '';
-            const hint = budgetOverrunHint(msg, scriptBudgetMs);
+            const hint = budgetOverrunHint(msg, scriptBudgetMs)
+                // A script aborted by its own reload is nearly always a persistence
+                // check hand-rolled without --reload; point at the flag that does it.
+                ?? (reloadExpr === undefined ? navigationAbortHint(msg) : null);
             if (!hint)
                 throw err;
             throw new Error(`${msg}\n${hint}`);
@@ -632,8 +662,17 @@ export const pageEvalCommand = new Command('eval')
         // page's rAF loop is its clock, and engines cap the per-frame delta, so
         // `setTimeout(2000)` may advance only a fraction of a second of app time.
         // Without this line the eval returns a plausible-looking false negative.
+        // A script that already steps the loop itself is immune to all of that, so
+        // slowRenderMessage returns null for it rather than prescribing the fix it
+        // is already applying.
         if (d.slowRender) {
-            console.log(slowRenderMessage(d.slowRender.fps, { camera: !!camera, waitMs }));
+            const slow = slowRenderMessage(d.slowRender.fps, {
+                camera: !!camera,
+                waitMs,
+                script: [expr, ...steps, reloadExpr ?? ''].join('\n'),
+            });
+            if (slow)
+                console.log(slow);
         }
         // Identity line on EVERY run: without it an agent can't distinguish
         // "signed-in eval" from "--auth silently no-op'd against the anonymous