gipity 1.1.3 → 1.1.5

package/dist/commands/job.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { get, post, del, getBaseUrl, getAuthHeader } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, bold, muted, success, warning as warn } from '../colors.js';
-import { run, printList } from '../helpers/index.js';
+import { run, printList, resolveBody, parseDuration } from '../helpers/index.js';
 export const jobCommand = new Command('job')
     .description('Run long jobs (CPU/GPU)')
     .addHelpText('after', '\nCPU sandbox or GPU (gpu-small=L4, gpu-medium=A10G, gpu-large=A100, gpu-huge=H100). Declared in the gipity.yaml jobs: phase; submit and poll via the subcommands below.');
@@ -23,14 +23,14 @@ jobCommand
 }));
 jobCommand
     .command('submit <name> [body]')
-    .description('Submit a job (returns a run guid; poll with `job status <guid>`)')
-    .option('--data <json>', 'JSON input body')
+    .description('Submit a job (returns a run guid; block on it with `job wait <guid>`)')
+    .option('-d, --data <json>', 'JSON input body: inline JSON, @file to read a file, or @- / - for stdin')
+    .option('--file <field=@path>', 'Attach a file as { data, media_type } under <field> (the vision/media service shape), repeatable, e.g. --file image=@scan.png', (v, acc) => (acc || []).concat(v))
     .option('--idempotency-key <key>', 'Idempotency key (replays return the existing run)')
     .option('--json', 'Output as JSON')
     .action((name, bodyArg, opts) => run('Submit', async () => {
     const config = requireConfig();
-    const raw = bodyArg || opts.data || '{}';
-    const input = JSON.parse(raw);
+    const input = resolveBody(bodyArg || opts.data, opts.file);
     const body = { input };
     if (opts.idempotencyKey)
         body.idempotency_key = opts.idempotencyKey;
@@ -41,6 +41,12 @@ jobCommand
     else {
         const tag = res.data.replayed ? warn(' (replayed)') : '';
         console.log(`${bold(res.data.run_guid)}  ${muted(res.data.status)}${tag}`);
+        // Awaiting the run is the natural next step after every submit; point the
+        // agent at the blocking command so it doesn't hand-roll a status poll loop.
+        const TERMINAL = new Set(['success', 'failed', 'cancelled', 'canceled', 'error']);
+        if (!TERMINAL.has(res.data.status)) {
+            console.error(muted(`Block until it finishes: gipity job wait ${res.data.run_guid}`));
+        }
     }
 }));
 jobCommand
@@ -57,8 +63,13 @@ jobCommand
     const r = res.data;
     const statusColor = r.status === 'success' ? success : r.status === 'failed' ? clrError : muted;
     console.log(`${statusColor(r.status)}  ${muted(r.guid)}`);
-    if (r.progress_pct != null)
-        console.log(`progress: ${Math.round(r.progress_pct * 100)}%${r.progress_message ? ` (${r.progress_message})` : ''}`);
+    if (r.progress_pct != null) {
+        const prog = `${Math.round(r.progress_pct * 100)}%${r.progress_message ? ` (${r.progress_message})` : ''}`;
+        // A failed run can have reported 100% (done) right before dying; a bare
+        // "progress: 100% (done)" next to status=failed reads as success. Label it.
+        const failedish = r.status === 'failed' || r.status === 'cancelled' || r.status === 'canceled' || r.status === 'error';
+        console.log(failedish ? `last progress before ${r.status}: ${prog}` : `progress: ${prog}`);
+    }
     if (r.duration_ms != null)
         console.log(`duration: ${r.duration_ms}ms`);
     if (r.error)
@@ -66,6 +77,71 @@ jobCommand
     if (r.output)
         console.log(`output: ${JSON.stringify(r.output)}`);
 }));
+jobCommand
+    .command('wait <runGuid>')
+    .description('Block until a job run finishes, or exit at --timeout so the shell never hangs (poll again to keep waiting)')
+    .option('--timeout <seconds>', 'Max seconds to wait before giving up and reporting current progress. Bare number = seconds; an explicit unit (90s) means the same here and on `sandbox run --timeout`.', '90')
+    .option('--interval <seconds>', 'Seconds between polls', '3')
+    .option('--json', 'Output as JSON')
+    .action((runGuid, opts) => run('Wait', async () => {
+    const config = requireConfig();
+    // Terminal states end the wait; anything else means "still working, keep polling".
+    const TERMINAL = new Set(['success', 'failed', 'cancelled', 'canceled', 'error']);
+    const durOpt = parseDuration(opts.timeout, 's');
+    const timeoutSec = durOpt ? Math.max(1, Math.round(durOpt.value)) : parseInt(opts.timeout, 10);
+    const timeout = Number.isFinite(timeoutSec) && timeoutSec > 0 ? timeoutSec : 90;
+    const interval = Math.max(1, parseInt(opts.interval, 10) || 3);
+    const deadline = Date.now() + timeout * 1000;
+    const fetchRun = async () => (await get(`/projects/${config.projectGuid}/jobs/runs/${encodeURIComponent(runGuid)}`)).data;
+    let r = await fetchRun();
+    let lastProgress = '';
+    while (!TERMINAL.has(r.status) && Date.now() < deadline) {
+        // Surface progress changes to stderr so an agent watching sees liveness
+        // without the poll noise polluting the machine-readable stdout result.
+        if (!opts.json) {
+            const prog = r.progress_pct != null
+                ? `${Math.round(r.progress_pct * 100)}%${r.progress_message ? ` (${r.progress_message})` : ''}`
+                : r.status;
+            if (prog !== lastProgress) {
+                console.error(muted(`... ${prog}`));
+                lastProgress = prog;
+            }
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise(res => setTimeout(res, Math.min(interval * 1000, remaining)));
+        r = await fetchRun();
+    }
+    const done = TERMINAL.has(r.status);
+    if (opts.json) {
+        console.log(JSON.stringify(done ? r : { ...r, waiting: true, timed_out: true }));
+    }
+    else if (!done) {
+        // Not an error - the job is simply still going. Say so plainly and tell
+        // the agent exactly how to resume, then exit non-zero so a chained `&&`
+        // doesn't proceed as if the run had finished.
+        const prog = r.progress_pct != null ? ` ${Math.round(r.progress_pct * 100)}%` : '';
+        console.log(`${warn('still running')}${prog}${r.progress_message ? ` (${r.progress_message})` : ''}  ${muted(runGuid)}`);
+        console.log(muted(`Not finished after ${timeout}s. Run \`gipity job wait ${runGuid}\` again to keep waiting.`));
+    }
+    else {
+        const statusColor = r.status === 'success' ? success : clrError;
+        console.log(`${statusColor(r.status)}  ${muted(r.guid)}`);
+        if (r.duration_ms != null)
+            console.log(`duration: ${r.duration_ms}ms`);
+        if (r.error)
+            console.log(`${clrError('error:')} ${r.error}`);
+        if (r.output)
+            console.log(`output: ${JSON.stringify(r.output)}`);
+    }
+    // Exit codes: success → 0, failed/cancelled → 1, still-running-at-timeout → 2
+    // (distinct from a real failure so agents can tell "not yet" from "broke").
+    if (!done)
+        process.exit(2);
+    if (r.status !== 'success')
+        process.exit(1);
+}));
 jobCommand
     .command('runs <name>')
     .description('List recent runs for a job')
@@ -87,6 +163,7 @@ jobCommand
     .description('Stream live logs for a job run (--no-follow for a one-shot snapshot)')
     .option('--follow', 'Stream via SSE (default)', true)
     .option('--no-follow', 'One-shot snapshot of run state instead of streaming')
+    .option('--timeout <seconds>', 'Stop streaming after N seconds and exit cleanly, so a bounded peek at the live log never hangs the shell (no shell `timeout` wrapper needed). Bare number = seconds; unit (20s) also accepted.')
     .option('--json', 'Output as JSON')
     .action((runGuid, opts) => run('Logs', async () => {
     const config = requireConfig();
@@ -95,6 +172,16 @@ jobCommand
         console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
         return;
     }
+    // Optional bounded peek: close the stream after --timeout seconds instead of
+    // holding open until the run finishes. Lets an agent glance at early stdout
+    // (e.g. catch an import error during cold start) without wrapping the command
+    // in a shell `timeout`, then poll again to keep watching.
+    let peekSeconds = 0;
+    if (opts.timeout != null) {
+        const dur = parseDuration(String(opts.timeout), 's');
+        const secs = dur ? dur.value : parseFloat(String(opts.timeout));
+        peekSeconds = Number.isFinite(secs) && secs > 0 ? secs : 0;
+    }
     // SSE stream. Manual fetch + line buffering - Node's EventSource isn't built-in,
     // and the SSE format is simple enough to parse inline (event: <name>\ndata: <json>\n\n).
     const url = `${getBaseUrl()}/projects/${config.projectGuid}/jobs/runs/${encodeURIComponent(runGuid)}/logs/stream`;
@@ -102,8 +189,28 @@ jobCommand
     const headers = { 'Accept': 'text/event-stream' };
     if (authHeader)
         headers.Authorization = authHeader;
-    const res = await fetch(url, { headers });
+    // Abort the underlying request when the peek window elapses so the socket is
+    // torn down cleanly rather than left dangling.
+    const controller = new AbortController();
+    let peekTimer;
+    let peekedOut = false;
+    if (peekSeconds > 0) {
+        peekTimer = setTimeout(() => { peekedOut = true; controller.abort(); }, peekSeconds * 1000);
+    }
+    let res;
+    try {
+        res = await fetch(url, { headers, signal: controller.signal });
+    }
+    catch (e) {
+        if (peekedOut) {
+            console.error(muted(`... still streaming after ${peekSeconds}s. Run \`gipity job logs ${runGuid} --timeout ${Math.round(peekSeconds)}\` again to keep watching, or \`gipity job wait ${runGuid}\` to block until it finishes.`));
+            return;
+        }
+        throw e;
+    }
     if (!res.ok || !res.body) {
+        if (peekTimer)
+            clearTimeout(peekTimer);
         console.error(clrError(`Failed to open stream: HTTP ${res.status}`));
         process.exit(1);
     }
@@ -112,9 +219,24 @@ jobCommand
     let buffer = '';
     let currentEvent = '';
     while (true) {
-        const { done, value } = await reader.read();
-        if (done)
+        let chunk;
+        try {
+            chunk = await reader.read();
+        }
+        catch (e) {
+            // Peek window elapsed mid-stream: report cleanly and exit 0 (not an error).
+            if (peekedOut) {
+                console.error(muted(`... still streaming after ${peekSeconds}s. Run \`gipity job logs ${runGuid} --timeout ${Math.round(peekSeconds)}\` again to keep watching, or \`gipity job wait ${runGuid}\` to block until it finishes.`));
+                return;
+            }
+            throw e;
+        }
+        const { done, value } = chunk;
+        if (done) {
+            if (peekTimer)
+                clearTimeout(peekTimer);
             break;
+        }
         buffer += decoder.decode(value, { stream: true });
         let nl;
         while ((nl = buffer.indexOf('\n')) >= 0) {

package/dist/commands/load.js

@@ -152,7 +152,7 @@ export const loadCommand = new Command('load')
     if (opts.inspect) {
         const res = opts.json
             ? await doInspect()
-            : await withSpinner('Inspecting…', doInspect, { done: null });
+            : await withSpinner('Inspecting...', doInspect, { done: null });
         if (opts.json) {
             console.log(JSON.stringify(res.data));
             return;
@@ -162,7 +162,7 @@ export const loadCommand = new Command('load')
     }
     const { data, partial } = opts.json
         ? await doImport()
-        : await withSpinner('Importing…', doImport, { done: null });
+        : await withSpinner('Importing...', doImport, { done: null });
     const project = data.project;
     // Materialize a local dir and link it, exactly like `gipity project create`:
     // `.gipity.json` is written directly inside the new dir, then a soft sync

package/dist/commands/login.js

@@ -4,6 +4,7 @@ import { publicPost } from '../api.js';
 import { prompt, decodeJwtExp } from '../utils.js';
 import { success, error as clrError, muted } from '../colors.js';
 import { flushBugQueue } from '../bug-queue.js';
+import { warnBeforeCodeIfUnexpectedNewAccount, warnIfUnexpectedNewAccount } from '../login-flow.js';
 export const loginCommand = new Command('login')
     .description('Log in or sign up')
     .option('--email <email>', 'Email address')
@@ -19,9 +20,10 @@ export const loginCommand = new Command('login')
         }
         // Email only → send code and exit (non-interactive step 1)
         if (email && !code) {
-            await publicPost('/auth/login', { email });
+            const sendRes = await publicPost('/auth/login', { email });
             console.log('Check your email for a 6-digit code.');
             console.log(muted(`Then run: gipity login --email ${email} --code <code>`));
+            warnBeforeCodeIfUnexpectedNewAccount(sendRes.isNewUser, email);
             return;
         }
         // Fully interactive flow
@@ -34,9 +36,10 @@ export const loginCommand = new Command('login')
             console.error(clrError('Email required.'));
             process.exit(1);
         }
-        await publicPost('/auth/login', { email });
+        const sendRes = await publicPost('/auth/login', { email });
         console.log('');
         console.log('Check your email for a 6-digit code.');
+        warnBeforeCodeIfUnexpectedNewAccount(sendRes.isNewUser, email);
         code = await prompt('Code: ');
         await verify(email, code);
     }
@@ -46,6 +49,7 @@ export const loginCommand = new Command('login')
     }
 });
 async function verify(email, code) {
+    const priorAuth = getAuth();
     const res = await publicPost('/auth/verify', { email, code });
     const exp = decodeJwtExp(res.accessToken);
     if (!exp) {
@@ -60,6 +64,7 @@ async function verify(email, code) {
         expiresAt,
     });
     console.log(success(`Logged in (${email}).`));
+    warnIfUnexpectedNewAccount(res.isNewUser, email, priorAuth);
     // A fresh session is the clearest "we're reconnected" signal - clear any bug
     // reports that got stranded while this account's session was expired/offline.
     const delivered = await flushBugQueue().catch(() => 0);

package/dist/commands/page-eval.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { Command, Option } from 'commander';
 import { post, get, ApiError } from '../api.js';
 import { brand, bold, muted, warning, success } from '../colors.js';
-import { run } from '../helpers/index.js';
+import { run, parseDuration } from '../helpers/index.js';
 import { getAuth } from '../auth.js';
 import { resolveProjectContext } from '../config.js';
 import { uploadPublicFixture, uploadCameraFeed, assertCameraFile, deleteFixture } from '../page-fixtures.js';
@@ -106,7 +106,7 @@ export function summarizeExpr(expr) {
     if (oneLine && expr.trim().length <= EXPR_ECHO_MAX_CHARS)
         return expr.trim();
     const first = (meaningful[0] ?? '').trim();
-    const head = first.length > EXPR_ECHO_MAX_CHARS ? `${first.slice(0, EXPR_ECHO_MAX_CHARS - 1)}…` : first;
+    const head = first.length > EXPR_ECHO_MAX_CHARS ? `${first.slice(0, EXPR_ECHO_MAX_CHARS - 3)}...` : first;
     const shape = oneLine
         ? `(${expr.trim().length} chars)`
         : `(+${meaningful.length - 1} more ${meaningful.length - 1 === 1 ? 'line' : 'lines'}, ${expr.trim().length} chars)`;
@@ -148,6 +148,13 @@ export function capWaitForTimeoutMs(raw) {
         `or watch for it INSIDE the script (--timeout ${EVAL_SCRIPT_BUDGET_MAX_MS}).`));
     return WAIT_FOR_MAX_MS;
 }
+/** Read a --file/--reload-file script. `-` means stdin, so an agent can pipe a
+ *  heredoc straight in — `gipity page eval <url> --file - <<'EOF' … EOF` — with
+ *  no throwaway tmp file to write and then clean up. readFileSync(0) drains fd 0
+ *  (stdin) to EOF. Any other value is a path on disk. */
+export function readScriptFile(pathArg) {
+    return readFileSync(pathArg === '-' ? 0 : pathArg, 'utf8');
+}
 /** True when `s` is an expression (`document.title`, an IIFE) rather than a
  *  statement body (`const x = …; return x`). Mirrors the server's own parse
  *  choice: only an expression may be spliced into `return (…)`. Nothing is
@@ -192,6 +199,12 @@ const CAMERA_SETUP_BUDGET_MS = 30_000;
 export const EVAL_SCRIPT_BUDGET_MS = 30_000;
 export const EVAL_SCRIPT_BUDGET_CAMERA_MS = 45_000;
 export const EVAL_SCRIPT_BUDGET_MAX_MS = 90_000;
+// The smallest in-page budget the server will honour. A --timeout below this is
+// floored to it, so any sub-floor value is useless as a real ms budget AND is
+// almost always seconds typed as ms (--timeout 120 meaning 120s) — the guard in
+// the action rejects it up front with the unit named, rather than letting it
+// silently floor and then stall with an opaque "1s budget" error.
+export const EVAL_SCRIPT_BUDGET_MIN_MS = 1_000;
 /** The in-page budget this call gets: the caller's --timeout when given, else the
  *  default for the kind of run (roomier under --camera/--fake-media). Clamped to
  *  the server's accepted range — a value over the max is clamped and explained on
@@ -209,7 +222,7 @@ export function capScriptBudgetMs(rawTimeout, hasMedia) {
             `absorb it in the pre-eval window (--wait-for '<ready-selector>'), keeping the body to a quick read.`));
         return EVAL_SCRIPT_BUDGET_MAX_MS;
     }
-    return Math.max(1_000, parsed);
+    return Math.max(EVAL_SCRIPT_BUDGET_MIN_MS, parsed);
 }
 /** Upper bound on the server-side work this eval asked for. EVERY leg the caller
  *  can lengthen has to be in here, or the client gives up on a job that is still
@@ -366,9 +379,9 @@ export const pageEvalCommand = new Command('eval')
     .description('Evaluate JS in a real browser on a page (DOM, computed styles, element rects; inline expr or --file script). ONE client per call - to verify realtime/presence across concurrent clients use `page test --observe` instead')
     .argument('<url>', 'URL to load')
     .argument('[expr]', `JavaScript to evaluate in page context (inline expression or statement body; await works, and the trailing expression is returned automatically — REPL-style — so no explicit return is needed; result is JSON-serialized). Omit when using --file. Time budget: the body has ${EVAL_SCRIPT_BUDGET_MS / 1000}s to finish after page load (${EVAL_SCRIPT_BUDGET_CAMERA_MS / 1000}s with --camera) - raise it with --timeout, max ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s.`)
-    .option('--file <path>', `Read the script body from a file instead of the inline <expr> arg (mutually exclusive). Runs as an async function body, so top-level return/await work. Same post-load budget as <expr> (--timeout).`)
+    .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. Repeat for several files (single-value so it never swallows the inline <expr>).', (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-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".`)
@@ -376,7 +389,7 @@ export const pageEvalCommand = new Command('eval')
     .option('--wait <ms>', 'Sleep this many ms after DOMContentLoaded before evaluating (lets late async work settle; max 30000). With --wait-for, it elapses AFTER the selector appears - gate, then settle.', '500')
     .option('--wait-for <selector>', `Wait until this CSS selector appears before evaluating, then evaluate (deterministic - beats guessing a --wait). Gate on the state you are ASSERTING, not just a ready flag: '#verdict:not(:empty)' returns the instant the round lands, where a fixed wait snapshots mid-sequence. Same flag on page inspect/screenshot. Max ${WAIT_FOR_MAX_MS}ms (--wait-timeout).`)
     .option('--wait-timeout <ms>', `Max ms to wait for --wait-for before giving up (max ${WAIT_FOR_MAX_MS})`, '5000')
-    .option('--timeout <ms>', `How long the script itself may run IN the page - its own await/setTimeout pauses count (default ${EVAL_SCRIPT_BUDGET_MS}, ${EVAL_SCRIPT_BUDGET_CAMERA_MS} with --camera/--fake-media; max ${EVAL_SCRIPT_BUDGET_MAX_MS}). Raise it to trace a sequence that unfolds over time (a game round, an animation). Distinct from --wait, which only sleeps BEFORE the script.`)
+    .option('--timeout <ms>', `How long the script itself may run IN the page. Bare number = MILLISECONDS (so 90s = 90000, NOT 90); or pass an explicit unit that means the same on both this and \`sandbox run --timeout\` — --timeout 90s. Its own await/setTimeout pauses count (default ${EVAL_SCRIPT_BUDGET_MS}, ${EVAL_SCRIPT_BUDGET_CAMERA_MS} with --camera/--fake-media; floor 1000, max ${EVAL_SCRIPT_BUDGET_MAX_MS}). Raise it to trace a sequence that unfolds over time (a game round, an animation). Distinct from --wait, which only sleeps BEFORE the script.`)
     .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor — nothing carries over from earlier --auth runs.')
     .option('--json', 'Output as JSON')
     .action((url, exprArg, opts) => run('Page eval', async () => {
@@ -409,10 +422,12 @@ export const pageEvalCommand = new Command('eval')
     let expr = exprArg;
     if (opts.file) {
         try {
-            expr = readFileSync(opts.file, 'utf8');
+            expr = readScriptFile(opts.file);
         }
         catch {
-            pageEvalCommand.error(`error: Cannot read file: ${opts.file}`);
+            pageEvalCommand.error(opts.file === '-'
+                ? 'error: --file - reads the script from stdin, but stdin was empty/unreadable - pipe it in, e.g. gipity page eval "<url>" --file - <<\'EOF\' ... EOF'
+                : `error: Cannot read file: ${opts.file}`);
         }
     }
     // Post-reload expression: inline --reload or --reload-file, same shape
@@ -423,7 +438,7 @@ export const pageEvalCommand = new Command('eval')
     let reloadExpr = opts.reload;
     if (opts.reloadFile) {
         try {
-            reloadExpr = readFileSync(opts.reloadFile, 'utf8');
+            reloadExpr = readScriptFile(opts.reloadFile);
         }
         catch {
             pageEvalCommand.error(`error: Cannot read file: ${opts.reloadFile}`);
@@ -434,6 +449,41 @@ export const pageEvalCommand = new Command('eval')
         pageEvalCommand.error(`error: at most ${MAX_EVAL_STEPS} --step expressions ride on one page load (got ${steps.length}) — ` +
             `do more per step, or split this into two evals`);
     }
+    // --timeout is native MILLISECONDS here but native SECONDS on the sibling
+    // `sandbox run --timeout`. An explicit unit suffix reconciles them: `--timeout
+    // 90s` means 90 seconds on BOTH commands. A suffixed value is normalized to ms
+    // up front, so the rest of this action (and the bare-number guard below) sees a
+    // plain ms number and the portable form just works.
+    if (opts.timeout !== undefined) {
+        const dur = parseDuration(opts.timeout, 'ms');
+        if (dur?.hadSuffix)
+            opts.timeout = String(Math.round(dur.value));
+    }
+    // A BARE number below the in-page floor is the unit-mixup tell: a real ms
+    // budget that small is useless (it just floors to the minimum), so a sub-floor
+    // bare number is almost always seconds typed as ms (--timeout 90 meaning 90s).
+    // Left alone it clamps SILENTLY to a ~1s budget and the script then stalls with
+    // an opaque "1s budget" error that never reveals the unit mix-up. Reject it up
+    // front, naming the unit AND the portable suffix form, so the fix is one obvious
+    // edit instead of a doomed run.
+    if (opts.timeout !== undefined) {
+        const t = parseInt(opts.timeout, 10);
+        if (Number.isFinite(t) && t > 0 && t < EVAL_SCRIPT_BUDGET_MIN_MS) {
+            const overMax = t * 1000 > EVAL_SCRIPT_BUDGET_MAX_MS;
+            const asMs = Math.min(t * 1000, EVAL_SCRIPT_BUDGET_MAX_MS);
+            // A value-mixup, not an arg-SHAPE error: the message below already carries
+            // the complete fix (pass `--timeout ${t}s`), so this does NOT go through
+            // pageEvalCommand.error() — that dumps the whole options list bracketing
+            // the message, and an agent piping the output through `| tail` reads the
+            // option list as "it rejected me with help" and misses the one-line fix.
+            // Throw instead: `run()` prints just the targeted message, nothing else.
+            throw new Error(`--timeout is in MILLISECONDS (got ${t}, under the ${EVAL_SCRIPT_BUDGET_MIN_MS}ms in-page floor). ` +
+                `Unlike \`sandbox run --timeout\` (seconds), page eval's is ms — or pass an explicit unit that means the ` +
+                `same on both: --timeout ${t}s. ${t} looks like seconds, so for ${t} second${t === 1 ? '' : 's'} pass ` +
+                `--timeout ${t}s (= ${asMs}ms)` +
+                `${overMax ? ` (${t}s is over the ${EVAL_SCRIPT_BUDGET_MAX_MS / 1000}s max, so this is the ceiling)` : ''}.`);
+        }
+    }
     let waitMs = capWaitMs(opts.wait, url);
     const waitForTimeoutMs = capWaitForTimeoutMs(opts.waitTimeout);
     // The in-page budget for the script itself. Always sent, so the caller (and
@@ -490,12 +540,12 @@ export const pageEvalCommand = new Command('eval')
             projectGuid = config.projectGuid;
         }
         if (opts.camera) {
-            console.log(muted(`Hosting camera feed ${opts.camera}…`));
+            console.log(muted(`Hosting camera feed ${opts.camera}...`));
             camera = await uploadCameraFeed(projectGuid, opts.camera);
         }
         if (fixturePaths.length) {
             for (const p of fixturePaths) {
-                console.log(muted(`Hosting fixture ${p}…`));
+                console.log(muted(`Hosting fixture ${p}...`));
                 hosted.push(await uploadPublicFixture(projectGuid, p));
             }
             const map = {};
@@ -601,7 +651,7 @@ export const pageEvalCommand = new Command('eval')
             console.log(`${muted('Camera:')} ${camera.name} ${muted('(played as the webcam feed; getUserMedia resolves)')}`);
         if (hosted.length)
             console.log(`${muted('Fixtures:')} ${hosted.map((h) => h.name).join(', ')}`);
-        console.error(opts.file ? `${muted('Script:')} ${opts.file}` : `${muted('Expression:')} ${summarizeExpr(expr)}`);
+        console.error(opts.file ? `${muted('Script:')} ${opts.file === '-' ? '(stdin)' : opts.file}` : `${muted('Expression:')} ${summarizeExpr(expr)}`);
         console.log(`\n${result.trim() ? result : muted('(empty result)')}`);
         if (noValue)
             console.log(muted(`\n${EVAL_NO_VALUE_HINT}`));
@@ -646,7 +696,16 @@ for (const f of JS_DECOY_FLAGS)
 // clients see each other (presence, shared state). For that, use the genuinely-
 // concurrent `page test --observe` instead, which overlaps N clients and reports
 // whether they actually ran together.
-pageEvalCommand.addHelpText('after', `
+//
+// This whole narrative renders ONLY on an explicit `--help`, never on an
+// arg-shape error. An error dumps the command via outputHelp too, but appending
+// ~70 lines of examples/time-budget/realtime guidance on top of a one-line "URL
+// must be absolute" buries the actual error — and its trailing realtime block,
+// off-topic for a plain probe, has misled agents into "fixing the eval syntax".
+// The one realtime pointer worth keeping on error already lives in the command
+// DESCRIPTION ("ONE client per call - use `page test --observe`"), which renders
+// on error anyway, so nothing is lost by withholding the manual here.
+pageEvalCommand.addHelpText('after', (context) => context.error ? '' : `
 Examples:
   gipity page eval "https://dev.gipity.ai/me/app/" "document.title"
   # Functionally test a page's own code paths: save a script that drives the UI
@@ -682,6 +741,16 @@ Examples:
     "window.__vision.gesture()" \\
     --step "document.getElementById('see').textContent" \\
     --step "({ score: score.textContent, verdict: verdict.textContent })"
+  # File-UPLOAD vision app (web-vision-detect, no camera)? --fixture is the analog of
+  # --camera: it hosts your test photo at a CORS-permissive URL, so you feed the kit's
+  # detector a known image and read back the labels - no deploying a throwaway asset into
+  # the app tree (and no cleanup redeploy). crossOrigin='anonymous' keeps the canvas clean.
+  gipity generate image "street scene: three people, two cars, one dog" -o street.jpg
+  gipity page eval "https://dev.gipity.ai/me/app/" --fixture street.jpg \\
+    "const { createDetector } = await import('./packages/web-vision-detect/index.js'); \\
+     const det = await createDetector({ model: 'nano' }); \\
+     const img = new Image(); img.crossOrigin = 'anonymous'; img.src = fixtureUrl; await img.decode(); \\
+     const { detections } = await det.detect(img); return detections.map(d => d.label);"
 
 Module resolution: dynamic import() specifiers starting with ./ or ../ resolve
 against the PAGE URL, so import('./packages/i18n/index.js') loads the app's own

package/dist/commands/page-fetch.js

@@ -30,9 +30,6 @@ function looksLikeHtml(body) {
     const head = body.slice(0, 300).toLowerCase();
     return /<!doctype html|<html[\s>]/.test(head);
 }
-function sha256(s) {
-    return createHash('sha256').update(s).digest('hex');
-}
 function baseWithSlash(url) {
     return url.endsWith('/') ? url : url + '/';
 }
@@ -43,8 +40,16 @@ function resolveUrl(base, path) {
 async function fetchRaw(url) {
     try {
         const res = await fetch(url, { redirect: 'follow' });
-        const body = await res.text();
-        return { status: res.status, contentType: res.headers.get('content-type'), body };
+        // Read raw bytes, not text(): decoding binary as UTF-8 turns every invalid
+        // byte into a 3-byte replacement char, inflating the measured size ~1.7x.
+        const buf = Buffer.from(await res.arrayBuffer());
+        return {
+            status: res.status,
+            contentType: res.headers.get('content-type'),
+            body: buf.toString('utf-8'),
+            bytes: buf.length,
+            sha256: createHash('sha256').update(buf).digest('hex'),
+        };
     }
     catch {
         return null; // DNS failure, connection refused, etc.
@@ -59,21 +64,20 @@ async function probeShell(base) {
     return {
         served: r.status >= 200 && r.status < 300,
         status: r.status,
-        sha256: sha256(r.body),
+        sha256: r.sha256,
         isHtml: looksLikeHtml(r.body),
     };
 }
 function classify(path, r, shell) {
     if (!r)
         return { status: null, contentType: null, bytes: 0, verdict: 'MISSING', detail: 'fetch failed (host unreachable)' };
-    const bytes = Buffer.byteLength(r.body);
-    const base = { status: r.status, contentType: r.contentType, bytes };
+    const base = { status: r.status, contentType: r.contentType, bytes: r.bytes };
     // Honest 404/5xx - the file simply isn't there.
     if (r.status >= 400)
         return { ...base, verdict: 'MISSING', detail: `HTTP ${r.status}` };
     const expect = expectedType(path);
     // 1) Served the catch-all shell verbatim → 200, but the file isn't deployed.
-    if (shell.served && shell.sha256 && sha256(r.body) === shell.sha256) {
+    if (shell.served && shell.sha256 && r.sha256 === shell.sha256) {
         return { ...base, verdict: 'MISSING', detail: `HTTP ${r.status} but served the SPA shell (file not deployed)` };
     }
     // 2) Asked for a non-HTML asset but got an HTML body → a per-path shell variant.
@@ -92,7 +96,7 @@ const TAG = {
     'WRONG-TYPE': warning('WRONG-TYPE'),
 };
 export const pageFetchCommand = new Command('fetch')
-    .description('Verify deployed non-rendered files (llms.txt, AGENTS.md, robots.txt, served JSON…) really exist - catches the static-host trap where a missing file returns 200 with the SPA shell instead of a 404')
+    .description('Verify deployed non-rendered files (llms.txt, AGENTS.md, robots.txt, served JSON...) really exist - catches the static-host trap where a missing file returns 200 with the SPA shell instead of a 404')
     .argument('<url>', 'Deployed app base URL; file paths resolve relative to it')
     .argument('<paths...>', 'One or more file paths to verify, e.g. llms.txt AGENTS.md robots.txt')
     .option('--json', 'Output as JSON')

package/dist/commands/page-inspect.js

@@ -26,10 +26,10 @@ function shortUrl(url, truncate = true, maxLen = 100) {
     }
     if (!truncate || result.length <= maxLen)
         return result;
-    const keep = maxLen - 1;
+    const keep = maxLen - 3;
     const headLen = Math.ceil(keep / 2);
     const tailLen = Math.floor(keep / 2);
-    return result.slice(0, headLen) + '…' + result.slice(-tailLen);
+    return result.slice(0, headLen) + '...' + result.slice(-tailLen);
 }
 export const pageInspectCommand = new Command('inspect')
     .description('Inspect a web page (console, failed resources, timing, layout overflow). ONE passive load - to verify realtime/presence across concurrent clients use `page test --observe`')
@@ -80,7 +80,24 @@ export async function inspectPage(url, opts = {}) {
         auth: opts.auth || undefined,
     };
     const res = await post(`/tools/browser/inspect`, inspectBody);
-    const b = res.data;
+    const b = res?.data;
+    // The inspector can hand back nothing to report — an auth-gated or
+    // JS-rendered SPA whose client render hadn't run, a navigation that
+    // redirected away, or a server-side hiccup that returned an empty bundle.
+    // Left unguarded the report below either crashes on `b.failedResources` or
+    // prints a bare header that reads as blank output — no signal at the exact
+    // moment the agent reached for verification. Say plainly that nothing was
+    // captured and point at the levers that fix it.
+    if (!b || typeof b !== 'object') {
+        if (opts.json) {
+            console.log(JSON.stringify({ url, captured: false, note: 'inspector returned no page data' }));
+            return;
+        }
+        console.log(`${brand('Inspecting')} ${bold(url)}`);
+        console.log(warning('Captured no page data — the page returned an empty response.'));
+        console.log(muted('The page may have failed to load, redirected away, or rendered nothing server-side. Retry once; if it persists pass --wait-for <selector> to wait for a specific element to appear, or --auth if it is behind Sign in with Gipity.'));
+        return;
+    }
     // ── Move resource-load failures out of the console, where they're noise ──
     // A sub-resource that returns an HTTP 4xx/5xx is reported twice: once in
     // `failedResources` (CDP network layer — carries the full URL, method, and
@@ -179,6 +196,14 @@ export async function inspectPage(url, opts = {}) {
     console.log(`${muted('Title:')} ${b.title || '(none)'}`);
     console.log(`${muted('Elements:')} ${b.elementCount || 0}`);
     console.log(`${muted('Page weight:')} ${info(formatSize(b.totalBytes || 0))}`);
+    // A page that came back with no DOM and no title rendered essentially
+    // nothing the inspector could see. That's the auth-gated / JS-rendered SPA
+    // trap: the header above alone reads as "loaded fine, just empty" when the
+    // real story is "client render or auth gate produced nothing yet." Flag it
+    // so the agent knows to wait for the render or sign in, not to trust silence.
+    if ((b.elementCount || 0) === 0 && !b.title) {
+        console.log(`${warning('⚠ Rendered no DOM (0 elements, no title)')} ${muted('— the client-side render likely had not run yet (try --wait-for <selector>), the page failed to load, or it is behind a sign-in gate (try --auth).')}`);
+    }
     // ── Timing ──
     console.log(`\n${bold('Timing:')}`);
     console.log(`${muted('TTFB:')} ${timing.ttfb}ms`);