gipity 1.1.3 → 1.1.4

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';
@@ -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
@@ -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-inspect.js

@@ -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`);

package/dist/commands/page-screenshot.js

@@ -8,6 +8,7 @@ import { brand, bold, muted, success, warning } from '../colors.js';
 import { formatSize } from '../utils.js';
 import { run } from '../helpers/index.js';
 import { withSpinner } from '../progress.js';
+import { readScriptFile } from './page-eval.js';
 import { uploadCameraFeed, assertCameraFile, deleteFixture } from '../page-fixtures.js';
 /** `mobile` and `tablet` name a real handset/tablet rather than just a window size.
  *  The server emulates it end to end - mobile user-agent, DPR, and crucially TOUCH,
@@ -235,6 +236,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     .option('--wait-for <selector>', `Wait until this CSS selector appears before capturing, then capture (deterministic - beats guessing a --wait). Same flag as page eval/inspect. Gate on what you are photographing ('[data-vision="ready"]', '#verdict:not(:empty)'). Max ${WAIT_FOR_MAX_MS}ms (--wait-timeout).`)
     .option('--wait-timeout <ms>', `Max ms to wait for --wait-for before giving up (default ${WAIT_FOR_DEFAULT_MS}, max ${WAIT_FOR_MAX_MS}). Timing out is reported - the capture still happens, so you see the state it got stuck in.`)
     .option('--action <js>', 'Run JS in the page before capturing — e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs as an async function body, so const/await and app-relative import(\'./…\') work. Runs after the post-load delay, then settles again before the shot. If it throws, the capture still happens and the failure is reported.')
+    .option('--file <path>', 'Read the pre-capture script from a file instead of inline --action (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<\'EOF\' … EOF) with no tmp file. For a multi-step driver — click through a flow, wait for it to render — then capture. Same async-function-body semantics as --action; same --file flag as page eval.')
     .option('--full', 'Capture the full scrollable page (default: viewport only). Scrolls the page through first so scroll-reveal/fade-in-on-scroll (IntersectionObserver) sections render into the shot instead of capturing blank.')
     .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
     .option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
@@ -264,8 +266,27 @@ export const pageScreenshotCommand = new Command('screenshot')
     if (aliasFlag) {
         console.error(muted(`Note: treating ${aliasFlag} as --action — it runs your JS in the page before the capture. --action is the canonical flag.`));
     }
-    const actionScript = [opts.action, ...ACTION_ALIAS_FLAGS.map((f) => opts[f.slice(2)])]
+    // The pre-capture script can come inline (--action / its JS-intent aliases) or
+    // from a file/stdin (--file, the same script-passing ergonomics as page eval).
+    // They are mutually exclusive: one page load runs one pre-capture body, so a
+    // caller that passed both meant one of them — say so rather than silently
+    // concatenating a driver script onto a stray click.
+    const inlineAction = [opts.action, ...ACTION_ALIAS_FLAGS.map((f) => opts[f.slice(2)])]
         .filter(Boolean).join('\n');
+    if (opts.file && inlineAction) {
+        throw new Error('Pass either --file <path> or an inline --action script, not both');
+    }
+    let actionScript = inlineAction;
+    if (opts.file) {
+        try {
+            actionScript = readScriptFile(opts.file);
+        }
+        catch {
+            throw new Error(opts.file === '-'
+                ? "--file - reads the pre-capture script from stdin, but stdin was empty/unreadable — pipe it in, e.g. gipity page screenshot \"<url>\" --file - <<'EOF' … EOF"
+                : `Cannot read file: ${opts.file}`);
+        }
+    }
     // --wait is the canonical name (it is what `page inspect`/`page eval` call it);
     // --post-load-delay stays as a hidden alias. Whether the caller named EITHER is
     // what decides the defaults below, so keep the raw "was it set" signal.
@@ -546,9 +567,17 @@ Waiting for the page to reach a state before the shot?
 
 Capturing a state that needs an interaction (start a game, open a menu, dismiss a modal)?
   Use --action to run JS in the page before the shot — it fires after the wait
-  (and after any --wait-for gate), then settles again so the result has painted. Do
-  NOT hand-roll a 'page eval' that returns a base64 image: the eval result is capped
-  (~16KB) and truncates the PNG.
+  (and after any --wait-for gate), then settles again so the result has painted. For
+  a multi-step driver (click, wait, click) pipe it as a heredoc with --file - (same
+  as 'page eval') instead of cramming it into one inline string:
+    gipity page screenshot "https://dev.gipity.ai/me/app/" --file - <<'EOF'
+    document.getElementById('load-sample').click();
+    await new Promise(r => setTimeout(r, 500));
+    document.getElementById('run').click();
+    await new Promise(r => setTimeout(r, 2000));
+    EOF
+  Do NOT hand-roll a 'page eval' that returns a base64 image: the eval result is
+  capped (~16KB) and truncates the PNG.
 
 Capturing an off-screen region or reading element data?
     • --full captures the ENTIRE scrollable page (then crop to the region).

package/dist/commands/records.js

@@ -9,7 +9,7 @@ import { confirm } from '../utils.js';
 // Records API is the only records surface that exists server-side; there is no
 // /projects/<guid>/records mirror.)
 export const recordsCommand = new Command('records')
-    .description('Manage records-kit data (registry-driven CRUD)');
+    .description('Manage app records (Gipity Records - validated CRUD with audit history)');
 recordsCommand
     .command('list')
     .description('List record tables')
@@ -91,6 +91,19 @@ recordsCommand
     const res = await get(`/api/${config.projectGuid}/records/${table}/${id}`);
     console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
 }));
+recordsCommand
+    .command('history <table> <id>')
+    .description('Audit history for a record (who/what changed it, with English summaries)')
+    .option('--limit <n>', 'Max events', '20')
+    .option('--json', 'Output as JSON')
+    .action((table, id, opts) => run('History', async () => {
+    const config = requireConfig();
+    const res = await get(`/api/${config.projectGuid}/records/${table}/${id}/history?limit=${encodeURIComponent(opts.limit)}`);
+    printList(res.data, opts, 'No history for this record.', e => {
+        const summary = e.detail?.summary || `${e.action} ${e.entity_type} ${e.entity_id}`;
+        return `${muted(e.created_at)}  ${bold(e.source || '-')}  ${summary}`;
+    });
+}));
 recordsCommand
     .command('create <table>')
     .description('Create a record')

package/dist/commands/sandbox.js

@@ -6,7 +6,7 @@ import { resolveProjectContext, getConfigPath, getProjectRoot, shouldIgnore } fr
 import { SCRATCH_IGNORE } from '../setup.js';
 import { sync } from '../sync.js';
 import { error as clrError, dim } from '../colors.js';
-import { run } from '../helpers/index.js';
+import { run, parseDuration } from '../helpers/index.js';
 import { createProgressReporter, withSpinner } from '../progress.js';
 const LANG_MAP = {
     js: 'javascript',
@@ -144,6 +144,77 @@ function explainSplitArgs(args) {
     lines.push('', 'Fix, in order of preference:', dim('  1. Put the code in a file (best for anything with quotes, $(...), or newlines):'), '       gipity sandbox run --file script.sh', dim('  2. Use the interpreter shorthand on a file:'), '       gipity sandbox run bash script.sh', dim('  3. Keep it inline, but as ONE argument your shell will not split:'), "       gipity sandbox run --language bash 'echo hi'");
     return lines.join('\n');
 }
+// Regex fragments for the scratch directory names, derived from SCRATCH_IGNORE
+// so this can never drift from what sync actually ignores. Each pattern's
+// trailing '/' is dropped, dots are escaped, and a leading-`*` glob (`*_tmp/`)
+// becomes a filename-char run so `frames_tmp/` is matched too. `shouldIgnore`
+// is the authoritative filter downstream, so a slightly broad candidate here is
+// harmless — it just gets dropped if sync wouldn't actually ignore it.
+const SCRATCH_DIR_PATTERNS = SCRATCH_IGNORE
+    .map((p) => p.replace(/\/$/, ''))
+    .filter(Boolean)
+    .map((p) => p.replace(/[.]/g, '\\.').replace(/\*/g, '[A-Za-z0-9._-]*'));
+/**
+ * References to a scratch directory inside a code body — the files the sandbox's
+ * auto-mirror will NOT carry, because sync ignores the scratch namespaces. Two
+ * shapes of the same trap are matched:
+ *   - project-relative `tmp/nimbus.pdf` (how you name a root file locally), and
+ *   - mirror-absolute `/work/tmp/nimbus.pdf` (how you name that same file inside
+ *     the container, where the auto-mirror lands the project under /work/).
+ * Both are returned project-relative (the `/work/` prefix stripped) so the caller
+ * can resolve them on local disk and print a clean path. Deliberately NOT matched:
+ * `/tmp/out` (the container's own writable /tmp is fine) nor `mytmp/x` (word
+ * boundary). Covers every SCRATCH_IGNORE namespace, including the `*_tmp/` glob.
+ * Returns the distinct referenced paths. Exported for tests.
+ */
+export function scratchRefsInCode(code) {
+    const dirs = SCRATCH_DIR_PATTERNS.join('|');
+    if (!dirs)
+        return [];
+    // Match either a `/work/`-prefixed reference or a bare one that is not preceded
+    // by a slash (absolute/nested path) or a word/dot char (mytmp/, a.tmp/).
+    const re = new RegExp(`(?:\\/work\\/|(?<![\\w/.]))(?:${dirs})\\/[A-Za-z0-9._\\-\\/]+`, 'g');
+    return [...new Set((code.match(re) ?? []).map((m) => m.replace(/^\/work\//, '')))];
+}
+/**
+ * True when the code WRITES `p` at its FIRST use, so the file is produced inside
+ * the sandbox and any later reference (an `ls`/`cat` to inspect it, a second
+ * pass over it) reads that in-sandbox copy rather than an unmirrored input. Two
+ * output shapes are recognized, judged at the path's first occurrence:
+ *   - a flagged/redirected output: `-o p`, `-of p`, `--output p`, `> p`, `>> p`, `tee p`;
+ *   - an ffmpeg trailing-positional output: ffmpeg names its output as the last
+ *     positional (NO `-o` flag), so a path in an ffmpeg segment that is not the
+ *     `-i`/`--input` argument is an output.
+ * This keeps the write-then-inspect pattern in one script working (ffmpeg writes
+ * tmp/clip.mp4, then `ls tmp/clip.mp4`), while still catching a genuine staged
+ * INPUT read whose first use is not a write (`cat tmp/x`, `pandoc tmp/x.md ...`,
+ * `open('tmp/x')`, `ffmpeg -i tmp/x ...`). It also lets the normal iterate loop
+ * through: a scratch OUTPUT lands locally after the first run, so on a re-run it
+ * exists, but its first reference is still the write.
+ */
+export function isWriteTarget(code, p) {
+    const path = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const m = new RegExp(`(?:\\/work\\/)?${path}(?![\\w./-])`).exec(code);
+    if (!m)
+        return false;
+    const idx = m.index;
+    const before = code.slice(Math.max(0, idx - 40), idx);
+    // Flagged / redirected output position immediately before the path.
+    if (/(?:^|[\s'"`;(])(?:-o|-of|--out(?:put)?[= ]|>>?|tee(?:\s+-a)?)\s*['"`]?(?:\/work\/)?$/.test(before))
+        return true;
+    // ffmpeg's output is a trailing positional (no `-o`): a path in an ffmpeg
+    // segment that isn't the `-i`/`--input` argument is an output.
+    const segStart = Math.max(code.lastIndexOf('&&', idx), code.lastIndexOf('||', idx), code.lastIndexOf(';', idx), code.lastIndexOf('|', idx), code.lastIndexOf('\n', idx));
+    // segStart points at the FIRST char of the separator; a two-char operator
+    // (`&&`/`||`) leaves its second char in the slice, so strip any leading
+    // operator/space chars before reading the command word. Without this, the
+    // canonical `mkdir -p tmp && ffmpeg -i a.png tmp/out.mp4` idiom left a stray
+    // `&` that defeated the command extractor and false-blocked the re-run.
+    const seg = code.slice(segStart + 1, idx).replace(/^[\s&|;]+/, '');
+    const cmd = /^\s*([A-Za-z0-9_./-]+)/.exec(seg)?.[1]?.split('/').pop()?.toLowerCase();
+    const afterInputFlag = /(?:^|[\s'"`])(?:-i|--input)[= ]\s*['"`]?$/.test(before);
+    return cmd === 'ffmpeg' && !afterInputFlag;
+}
 /** Project-relative path from the process cwd, or undefined when there's
  *  no local config (one-off mode) or the cwd is at/above the project root. */
 function resolveRelativeCwd() {
@@ -171,7 +242,16 @@ sandboxCommand
     // positional arg is the canonical spelling). Accept it as a working alias
     // rather than bouncing the guess into an unknown-option --help detour.
     .addOption(new Option('--code <code>', 'Alias for the positional inline <code> arg').hideHelp())
-    .option('--timeout <seconds>', 'Execution timeout in seconds', '30')
+    // `bash -c '<code>'` and `node -e '<code>'` are the universal ways to run an
+    // inline command, and an agent reaches for them by reflex - but the bare
+    // `-c` / `-e` used to hit commander's OWN parser first ("unknown option
+    // '-c'"), before the interpreter-token logic below ever ran. Declaring them
+    // as hidden inline-code aliases makes the idiom just work: `-c`/`--cmd`
+    // implies bash, `-e`/`--eval` implies node, and a leading `bash`/`python`/
+    // `node` token still pins the language (so `python -c '...'` runs as python).
+    .addOption(new Option('-c, --cmd <code>', 'Inline code (bash idiom: `sandbox run bash -c "<code>"`)').hideHelp())
+    .addOption(new Option('-e, --eval <code>', 'Inline code (node idiom: `sandbox run node -e "<code>"`)').hideHelp())
+    .option('--timeout <seconds>', 'Execution timeout. Bare number = seconds; or pass an explicit unit that means the same on both this and `page eval --timeout`, e.g. --timeout 90s.', '30')
     .option('--input <path>', 'Narrow to specific project files instead of auto-mirroring the whole tree (repeatable). Use this only for >1 GB projects or when you want surgical control.', (v, prev) => [...(prev ?? []), v])
     // Named "discard", not "no-sync": in Gipity vocabulary "sync" means the
     // local<->cloud file sync, so a no-sync spelling reads as "give me the file
@@ -214,6 +294,8 @@ Examples:
   $ gipity sandbox run --file build_report.py
   $ gipity sandbox run python build_report.py   # same thing, interpreter shorthand
   $ gipity sandbox run bash "echo hi; ffmpeg -version"   # inline, language pinned
+  $ gipity sandbox run bash -c "ffmpeg -version"         # the bash -c idiom also works
+  $ gipity sandbox run node -e "console.log(process.version)"  # and node -e
 
   # Surgical: only these files are mirrored in
   $ gipity sandbox run --language bash \\
@@ -242,13 +324,26 @@ GCC/Rust).
     let inlineCode;
     let filePath = opts.file;
     let langFromInterp;
-    // --code alias: fold it into the positional slot before the shape checks.
-    if (opts.code !== undefined) {
-        if (args.length) {
-            console.error(clrError('Pass the code once: either positionally or via --code, not both'));
+    // Inline code may arrive via a flag alias instead of the positional slot:
+    //   --code            language-agnostic (needs --language or an interpreter token)
+    //   --cmd / -c        the `bash -c '<code>'` idiom → implies bash
+    //   --eval / -e       the `node -e '<code>'` idiom → implies node
+    // Fold whichever was given into the positional slot before the shape checks,
+    // preserving a leading interpreter token (`python -c '...'` stays python).
+    const flagCode = opts.code ?? opts.cmd ?? opts.eval;
+    if (flagCode !== undefined) {
+        // The positional slot may legitimately hold ONLY a leading interpreter
+        // token that pins the language; anything more is a duplicate copy of the code.
+        const leadIsInterp = args.length === 1 && INTERPRETERS[args[0].toLowerCase()] !== undefined;
+        if (args.length > (leadIsInterp ? 1 : 0)) {
+            console.error(clrError('Pass the code once: either positionally or via --code/--cmd/-c/--eval/-e, not both'));
             process.exit(1);
         }
-        args = [opts.code];
+        const interp = leadIsInterp ? args[0]
+            : opts.cmd !== undefined ? 'bash'
+                : opts.eval !== undefined ? 'node'
+                    : undefined;
+        args = interp ? [interp, flagCode] : [flagCode];
     }
     if (args.length >= 2 && INTERPRETERS[args[0].toLowerCase()] !== undefined) {
         langFromInterp = INTERPRETERS[args[0].toLowerCase()];
@@ -267,7 +362,9 @@ GCC/Rust).
         process.exit(1);
     }
     if (inlineCode !== undefined && filePath) {
-        console.error(clrError('Pass either an inline <code> arg or --file <path>, not both'));
+        console.error(clrError('Pass the code ONE way, not both: an inline <code> arg OR --file <path>.'));
+        console.error(dim("  inline:  gipity sandbox run bash 'echo hi'"));
+        console.error(dim('  file:    gipity sandbox run --file script.sh'));
         process.exit(1);
     }
     if (inlineCode === undefined && !filePath) {
@@ -299,7 +396,10 @@ GCC/Rust).
     }
     // Args are good - now it's worth resolving (and announcing) the project.
     const { config } = await resolveProjectContext();
-    const timeout = parseInt(opts.timeout, 10);
+    // A bare number is native SECONDS; an explicit suffix (90s / 1500ms / 2m) is
+    // portable with `page eval --timeout` and converted to seconds here.
+    const durOpt = parseDuration(opts.timeout, 's');
+    const timeout = durOpt ? Math.max(1, Math.round(durOpt.value)) : parseInt(opts.timeout, 10);
     const cwd = resolveRelativeCwd();
     // A scratch path is never synced, so it can never reach the VFS the sandbox
     // mirrors from - `--input tmp/frame.png` would fail inside the container with
@@ -311,6 +411,31 @@ GCC/Rust).
         console.error(dim('  Stage inputs at a real project path (src/, docs/, assets/) and delete them afterward.'));
         process.exit(1);
     }
+    // Same trap, one step less obvious: a scratch file referenced as an INPUT
+    // from inside the code body (not via --input). The auto-mirror skips the
+    // scratch namespaces, so the container hits a bare "No such file" for a path
+    // the caller can plainly see on local disk. Catch it here, pre-sync, with the
+    // reason. We flag a reference only when that scratch file ACTUALLY EXISTS
+    // locally — which cleanly separates a staged input (must exist to be read)
+    // from a scratch OUTPUT target like `tmp/preview.png` (valid; doesn't exist
+    // yet, and outputs written under tmp/ come back on their own).
+    if (source) {
+        const scratchReads = scratchRefsInCode(source).filter((p) => shouldIgnore(p, SCRATCH_IGNORE)
+            && existsSync(resolve(process.cwd(), p))
+            // A previous run's OUTPUT lands locally, so on a re-run it exists -
+            // but a path written at its FIRST use (ffmpeg output, -o, >) is
+            // produced in the sandbox, so a later inspect (`ls`/`cat`) in the same
+            // script reads that copy, not the mirror. Only a genuine staged input
+            // read (first use isn't a write) is blocked.
+            && !isWriteTarget(source, p));
+        if (scratchReads.length) {
+            console.error(clrError(`Scratch files are never mirrored into the sandbox, so it can't read: ${scratchReads.join(', ')}`));
+            console.error(dim(`  ${SCRATCH_IGNORE.join(', ')} are ignored by sync, so the sandbox never sees them.`));
+            console.error(dim('  Stage the input at a real project path (src/, docs/, assets/) and delete it afterward.'));
+            console.error(dim('  (Writing OUTPUT under tmp/ is fine — scratch outputs come back to your local tmp/.)'));
+            process.exit(1);
+        }
+    }
     // Push local working-tree changes up before executing. The sandbox mirrors
     // the *server* (VFS), not the local cwd, so any input staged outside Claude's
     // Write/Edit auto-push hook - a Bash `cp`/`ffmpeg`/redirect, or any external
@@ -407,6 +532,18 @@ GCC/Rust).
                 if (pulledLocal)
                     console.log(dim("Not pulled locally - run 'gipity sync' to fetch them."));
             }
+            // A sandbox output that lands directly at the project ROOT (a bare
+            // filename, no directory) is almost always a throwaway probe, not a
+            // real asset - real assets live under src/, functions/, assets/, etc.
+            // Root files sync and are picked up by the deploy `files` phase, so a
+            // stray one ships unless the caller remembers to delete it. Point at
+            // tmp/ (local-only, never synced or deployed) at the moment of use so
+            // the next probe never has to be hand-cleaned off a deployable path.
+            const rootStrays = [...onDisk, ...notOnDisk].filter((f) => !f.includes('/'));
+            if (rootStrays.length > 0) {
+                console.log(dim(`\nNote: ${rootStrays.join(', ')} landed at the project root and will deploy with the files phase.`));
+                console.log(dim('For a throwaway probe or fixture, write it under tmp/ instead - scratch outputs stay on local disk and never sync or deploy.'));
+            }
         }
         if (scratchWritten.length > 0) {
             console.log('\nScratch outputs (local only - never synced or deployed):');
@@ -418,7 +555,42 @@ GCC/Rust).
             for (const f of res.data.skippedOutputFiles)
                 console.log(dim(`${f}`));
         }
+        // Silent-failure guard: a command that exits 0 yet leaves a 0-byte output
+        // almost always failed silently - a broken ffmpeg filter, or an OOM the
+        // shell swallowed. Without this the only signal is an `ls -la` afterward,
+        // and the agent burns a turn inferring "the encode failed" from a file
+        // size. Name it at the moment it happens, for scratch (bytes returned
+        // inline) and synced outputs (stat on local disk) alike.
+        if (res.data.exitCode === 0) {
+            const emptyScratch = (res.data.scratchFiles ?? [])
+                .filter((f) => f.contentBase64.length === 0)
+                .map((f) => f.path.replace(/\\/g, '/'));
+            const root = getProjectRoot();
+            const emptyOutputs = pulledLocal && root
+                ? (res.data.outputFiles ?? []).filter((f) => {
+                    try {
+                        return statSync(resolve(root, f)).size === 0;
+                    }
+                    catch {
+                        return false;
+                    }
+                })
+                : [];
+            const empties = [...new Set([...emptyScratch, ...emptyOutputs])];
+            if (empties.length > 0) {
+                console.error(dim(`Note: ${empties.join(', ')} was written but is empty (0 bytes) - the command exited 0 but likely failed silently (a broken filter, or an out-of-memory kill the shell swallowed). Re-check the command, or shrink the job if it may have run out of memory.`));
+            }
+        }
         if (res.data.exitCode !== 0) {
+            // A process killed by a signal exits 128+signal. 137 (SIGKILL) on the
+            // sandbox is almost always the OS OOM-killer - the raw `/work/_run.sh:
+            // Killed` line the shell prints never says so, so a bare retry at the
+            // same size just OOMs again. Name it and point at the usual fix.
+            if (res.data.exitCode === 137) {
+                console.error(clrError('The sandbox process was killed (exit 137) - it ran out of memory.'));
+                console.error(dim('  Shrink the job: for ffmpeg, downscale (-vf scale=640:-2) and add -preset ultrafast;'));
+                console.error(dim('  for ImageMagick, lower -density/-resize. Process in smaller chunks if it still OOMs.'));
+            }
             // No "did you mean another language?" hint is needed: the language is now
             // always something the caller pinned, never a silent default we chose.
             process.exit(res.data.exitCode);

package/dist/commands/service.js

@@ -25,8 +25,13 @@ export const serviceCommand = new Command('service')
 serviceCommand
     .command('list')
     .description('List callable app services')
-    .action(() => run('Services', async () => {
+    .option('--json', 'Output the service list as JSON')
+    .action((opts) => run('Services', async () => {
     requireConfig();
+    if (opts.json) {
+        console.log(JSON.stringify(SERVICES));
+        return;
+    }
     const width = SERVICES.reduce((m, s) => Math.max(m, s.name.length), 0);
     console.log('Call one with `gipity service call <name> \'{"json":"body"}\'`');
     console.log(muted('(GET endpoints like llm/models, tts/voices take --get and no body)'));