gipity 1.1.6 → 1.1.7

package/dist/catalog.js

@@ -19,9 +19,9 @@ export const STARTERS = [
 /** Visible blank-wiring templates. */
 export const BLANK = [
     { key: 'web-simple', hint: 'static frontend-only site - pages, dashboards, simple games' },
-    { key: 'web-fullstack', hint: 'backend API + database wiring - frontend, functions, migrations; deploys green' },
+    { key: 'web-fullstack', hint: 'backend API + database wiring - frontend, functions, migrations; deploys green empty' },
     { key: '3d-engine', hint: '3D multiplayer wiring - Three.js + Rapier + Gipity Realtime' },
-    { key: 'api', hint: 'pure API backend, no frontend - one example function + test' },
+    { key: 'api', hint: 'pure API backend, no frontend - functions + tests, deploys green' },
 ];
 /** Hidden templates - installable by exact key, omitted from listings. */
 export const HIDDEN = [

package/dist/commands/db.js

@@ -4,6 +4,7 @@ import { requireConfig } from '../config.js';
 import { error as clrError, success } from '../colors.js';
 import { run, printList, emitField } from '../helpers/index.js';
 import { confirm } from '../utils.js';
+import { createCheckpoint, restoreCheckpoint, dropCheckpoint, resolveDatabase } from '../db-checkpoint.js';
 export const dbCommand = new Command('db')
     .description('Manage databases');
 dbCommand
@@ -171,4 +172,64 @@ dbCommand
         console.log(success(`Dropped database '${name}'.`));
     }
 }));
+dbCommand
+    .command('checkpoint')
+    .description('Snapshot every table so a write test can be undone. Take one before exercising a real write path (page eval on the deployed app, fn call, workflow run), then `gipity db restore` to put the data back exactly as it was - no hand-written SQL to scrub test strings out of real content.')
+    .option('--database <name>', 'Database name')
+    .option('--drop', 'Discard the existing checkpoint without restoring (keep whatever the run wrote)')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Checkpoint', async () => {
+    const config = requireConfig();
+    const dbName = await resolveDatabase(config.projectGuid, opts.database);
+    if (!dbName) {
+        console.error(clrError('No databases in this project - nothing to checkpoint.'));
+        process.exit(1);
+    }
+    if (opts.drop) {
+        const dropped = await dropCheckpoint(config.projectGuid, dbName);
+        if (opts.json) {
+            console.log(JSON.stringify(dropped));
+        }
+        else {
+            console.log(dropped.tables.length === 0
+                ? `No checkpoint in '${dbName}'.`
+                : success(`Discarded the checkpoint of ${dropped.tables.length} table(s) in '${dbName}'. Current data kept.`));
+        }
+        return;
+    }
+    const res = await createCheckpoint(config.projectGuid, dbName);
+    if (opts.json) {
+        console.log(JSON.stringify(res));
+    }
+    else if (res.tables.length === 0) {
+        console.log(`Database '${dbName}' has no tables - nothing to checkpoint.`);
+    }
+    else {
+        console.log(success(`Checkpointed ${res.tables.length} table(s), ${res.rows} row(s) in '${dbName}'.`));
+        console.log('Undo everything written since: gipity db restore');
+    }
+}));
+dbCommand
+    .command('restore')
+    .description('Roll every table back to the last `gipity db checkpoint` and drop the checkpoint. The undo for a live write test.')
+    .option('--database <name>', 'Database name')
+    .option('--keep', 'Keep the checkpoint after restoring, so you can run the same write test again')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Restore', async () => {
+    const config = requireConfig();
+    const dbName = await resolveDatabase(config.projectGuid, opts.database);
+    if (!dbName) {
+        console.error(clrError('No databases in this project - nothing to restore.'));
+        process.exit(1);
+    }
+    const res = await restoreCheckpoint(config.projectGuid, dbName, { keep: opts.keep });
+    if (opts.json) {
+        console.log(JSON.stringify(res));
+    }
+    else {
+        console.log(success(`Restored ${res.tables.length} table(s) to the checkpoint (${res.rows} row(s)) in '${dbName}'.`));
+        if (opts.keep)
+            console.log('Checkpoint kept - restore again any time.');
+    }
+}));
 //# sourceMappingURL=db.js.map

package/dist/commands/page-eval.js

@@ -5,6 +5,7 @@ import { brand, bold, muted, warning, success } from '../colors.js';
 import { run, parseDuration } from '../helpers/index.js';
 import { getAuth } from '../auth.js';
 import { resolveProjectContext } from '../config.js';
+import { createCheckpoint, restoreCheckpoint, resolveDatabase } from '../db-checkpoint.js';
 import { uploadPublicFixture, uploadCameraFeed, assertCameraFile, deleteFixture } from '../page-fixtures.js';
 // Shown when an eval runs cleanly but returns nothing serializable. Turns a
 // bare/opaque `null` into a deterministic, actionable nudge so the agent shapes
@@ -418,6 +419,7 @@ export const pageEvalCommand = new Command('eval')
     .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. 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('--restore-db', "Snapshot the app database before the script runs and roll it back after, so a write-path check (click Approve, submit the form, edit a row) leaves the real data untouched. Use this whenever the eval WRITES - it is the undo for driving the deployed app against real project data. Same snapshot/undo standalone: gipity db checkpoint / gipity db restore.")
     .option('--json', 'Output as JSON')
     .action((url, exprArg, opts) => run('Page eval', async () => {
     // A JS-intent flag guess (captured as a hidden decoy below): redirect to the
@@ -561,7 +563,24 @@ export const pageEvalCommand = new Command('eval')
     // instant error, not an upload plus an opaque browser-side failure.
     if (opts.camera)
         assertCameraFile(opts.camera);
+    // Set when --restore-db took a checkpoint; the finally below rolls the app
+    // database back to it, so a write-path smoke test leaves no residue in the
+    // real data the user is about to look at.
+    let restoreDb;
     try {
+        if (opts.restoreDb) {
+            const { config } = await resolveProjectContext({});
+            projectGuid = config.projectGuid;
+            const database = await resolveDatabase(config.projectGuid);
+            if (!database) {
+                console.error(muted('--restore-db: this project has no database - nothing to roll back.'));
+            }
+            else {
+                const cp = await createCheckpoint(config.projectGuid, database);
+                console.error(muted(`Checkpointed ${cp.tables.length} table(s), ${cp.rows} row(s) in '${database}' - rolled back when this eval finishes.`));
+                restoreDb = { projectGuid: config.projectGuid, database };
+            }
+        }
         if (fixturePaths.length || opts.camera) {
             const { config } = await resolveProjectContext({});
             projectGuid = config.projectGuid;
@@ -715,6 +734,15 @@ export const pageEvalCommand = new Command('eval')
         }
     }
     finally {
+        if (restoreDb) {
+            try {
+                const r = await restoreCheckpoint(restoreDb.projectGuid, restoreDb.database);
+                console.error(muted(`Rolled ${r.tables.length} table(s) back to the checkpoint (${r.rows} row(s)) - nothing this eval wrote survives.`));
+            }
+            catch (err) {
+                console.error(warning(`⚠ Could not roll back the database - the checkpoint is still there, retry with: gipity db restore (${err.message})`));
+            }
+        }
         for (const h of [...hosted, ...(camera ? [camera] : [])]) {
             try {
                 await deleteFixture(projectGuid, h.guid);

package/dist/commands/page-screenshot.js

@@ -1,6 +1,6 @@
 import { Command, Option } from 'commander';
 import { mkdirSync, writeFileSync } from 'fs';
-import { dirname, join, resolve as resolvePath } from 'path';
+import { dirname, extname, join, resolve as resolvePath } from 'path';
 import { postForTarEntries } from '../api.js';
 import { getConfig, getProjectRoot } from '../config.js';
 import { getAuth } from '../auth.js';
@@ -171,6 +171,19 @@ function resolveDevice(name) {
     const available = [...Object.keys(DEVICE_PRESETS), ...TOUCH_DEVICES].join(', ');
     throw new Error(`Unknown --device preset: "${name}" (known: ${available})`);
 }
+/** Slug used to tell one viewport's `-o` file from another's: the device name the
+ *  caller typed (`desktop`, `Pixel 9` → `pixel-9`) or the raw dimensions. */
+function viewportSlug(name) {
+    return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'shot';
+}
+/** Expand an `--output` path into one path per viewport by treating it as a stem:
+ *  `tmp/shot.png` + `mobile` → `tmp/shot-mobile.png`. Keeps the caller's extension
+ *  (defaulting to .png) so a multi-device capture writes every file it took. */
+function stemPath(output, suffix) {
+    const ext = extname(output) || '.png';
+    const base = ext && output.endsWith(ext) ? output.slice(0, -ext.length) : output;
+    return `${base}-${suffix}${ext}`;
+}
 function splitCsv(values) {
     if (!values || values.length === 0)
         return [];
@@ -238,7 +251,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     .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('-o, --output <file>', 'Output path (default .gipity/screenshots/ss-<host>-<timestamp>.png). With several viewports it is a stem: -o tmp/shot.png --device desktop,mobile writes tmp/shot-desktop.png and tmp/shot-mobile.png.')
     .option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
     .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern — to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
     .option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture — so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
@@ -347,9 +360,12 @@ export const pageScreenshotCommand = new Command('screenshot')
         ...deviceNames.map(resolveDevice),
         ...viewportStrs.map(parseViewportString),
     ];
-    if (opts.output && customViewports.length > 1) {
-        throw new Error('--output can only be used with a single viewport');
-    }
+    // Parallel to customViewports: what each capture is called when `--output` has
+    // to name more than one file.
+    const viewportLabels = [
+        ...deviceNames.map(viewportSlug),
+        ...viewportStrs.map(viewportSlug),
+    ];
     // Server defaults to 1280×720 when viewports is omitted - don't send it in
     // the no-flag case so the filename stays unsuffixed (no viewport segment).
     const userSpecifiedViewports = customViewports.length > 0;
@@ -437,9 +453,21 @@ export const pageScreenshotCommand = new Command('screenshot')
     }
     const dir = defaultScreenshotDir();
     const savedFiles = [];
+    // With more than one viewport, `--output` is a stem: every capture gets its own
+    // file (shot.png → shot-desktop.png, shot-mobile.png) instead of overwriting.
+    const usedStems = new Set();
+    const outputPath = (i) => {
+        if (pngs.length === 1)
+            return opts.output;
+        let suffix = viewportLabels[i] ?? dimSuffix(meta.screenshots[i].viewport);
+        while (usedStems.has(suffix))
+            suffix += `-${i + 1}`;
+        usedStems.add(suffix);
+        return stemPath(opts.output, suffix);
+    };
     for (let i = 0; i < pngs.length; i++) {
         const target = opts.output
-            ? opts.output
+            ? outputPath(i)
             : join(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
         // Create the target's parent dir so a `-o` path under a not-yet-existing
         // directory (e.g. .gipity/screenshots/home.png) writes cleanly instead of

package/dist/commands/records.js

@@ -79,25 +79,37 @@ recordsCommand
 }));
 recordsCommand
     .command('query <table>')
-    .description('List records')
-    .option('--filter <filter>', 'Filter string (e.g., "status:eq:active")')
+    .description('List records (full-text search, filter, sort, recycle bin)')
+    .option('-q, --q <text>', 'Full-text search across the table\'s text columns (needs `--searchable true` on the table)')
+    .option('--filter <filter>', 'AND filter string (e.g., "status:eq:active")')
+    .option('--any <filter>', 'OR filter group, same grammar as --filter (e.g., "owner:eq:me,shared:eq:true")')
     .option('--sort <sort>', 'Sort string (e.g., "created_at:desc")')
     .option('--limit <n>', 'Max rows', '20')
     .option('--offset <n>', 'Offset', '0')
     .option('--fields <fields>', 'Comma-separated column names')
+    .option('--include-deleted', 'Include soft-deleted rows (owner/editor)')
+    .option('--only-deleted', 'Only soft-deleted rows - the recycle bin (owner/editor)')
     .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, opts) => run('Query', async () => {
     const api = await recordsHttp(opts);
     const params = new URLSearchParams();
+    if (opts.q)
+        params.set('q', opts.q);
     if (opts.filter)
         params.set('filter', opts.filter);
+    if (opts.any)
+        params.set('any', opts.any);
     if (opts.sort)
         params.set('sort', opts.sort);
     params.set('limit', opts.limit);
     params.set('offset', opts.offset);
     if (opts.fields)
         params.set('fields', opts.fields);
+    if (opts.includeDeleted)
+        params.set('include_deleted', '1');
+    if (opts.onlyDeleted)
+        params.set('only_deleted', '1');
     const res = await api.get(`/api/${api.guid}/records/${table}?${params}`);
     if (opts.json) {
         console.log(JSON.stringify(res));
@@ -162,18 +174,38 @@ recordsCommand
     const res = await api.put(`/api/${api.guid}/records/${table}/${id}`, data);
     printResult(`Updated: ${JSON.stringify(res.data)}`, opts, res.data);
 }));
+// A table that declares `soft_delete_column` only STAMPS the row on delete - it
+// stays queryable via `query --only-deleted` and keeps its audit history. That's
+// right for user data and wrong for a probe row you just minted to test the
+// wiring, so `--purge` (the server's ?purge=1) is the one call that really
+// removes it. The plain success line says which of the two happened and names
+// the escape hatch, so nobody has to go spelunking through gipity.js to find it.
 recordsCommand
     .command('delete <table> <id>')
-    .description('Delete a record')
+    .description('Delete a record (soft-delete when the table declares one; --purge removes it for good)')
+    .option('--purge', 'Hard-delete: remove the row AND erase its audit history (owner/editor). Use it to scrub probe rows.')
     .option(ANON_FLAG, ANON_HELP)
     .option('--json', 'Output as JSON')
     .action((table, id, opts) => run('Delete', async () => {
-    if (!await confirm(`Delete record ${id} from "${table}"?`)) {
+    const what = opts.purge ? `Purge record ${id} from "${table}" (also erases its history)?` : `Delete record ${id} from "${table}"?`;
+    if (!await confirm(what)) {
         printResult('Cancelled.', opts, { table, id, deleted: false, cancelled: true });
         return;
     }
     const api = await recordsHttp(opts);
-    const res = await api.del(`/api/${api.guid}/records/${table}/${id}`);
-    printResult('Deleted.', opts, res?.data ?? { table, id, deleted: true });
+    const res = await api.del(`/api/${api.guid}/records/${table}/${id}${opts.purge ? '?purge=1' : ''}`);
+    const data = res?.data ?? { table, id, deleted: true, purged: !!opts.purge };
+    printResult(data.purged
+        ? 'Purged - the row and its audit history are gone.'
+        : `Deleted. If "${table}" declares a soft-delete column the row is only stamped deleted (see it with \`gipity records query ${table} --only-deleted\`, bring it back with \`gipity records restore ${table} ${id}\`, remove it for good with \`--purge\`).`, opts, data);
+}));
+recordsCommand
+    .command('restore <table> <id>')
+    .description('Un-delete a soft-deleted record (owner/editor)')
+    .option('--json', 'Output as JSON')
+    .action((table, id, opts) => run('Restore', async () => {
+    const api = await recordsHttp(opts);
+    const res = await api.post(`/api/${api.guid}/records/${table}/${id}/restore`);
+    printResult('Restored.', opts, res?.data ?? { table, id, restored: true });
 }));
 //# sourceMappingURL=records.js.map

package/dist/commands/service.js

@@ -1,8 +1,9 @@
 import { Command } from 'commander';
-import { get, post } from '../api.js';
+import { get, post, publicRequest, mintAppToken, ApiError } from '../api.js';
+import { getAuth } from '../auth.js';
 import { requireConfig } from '../config.js';
 import { bold, muted } from '../colors.js';
-import { run } from '../helpers/index.js';
+import { run, emitField, resolveBody } from '../helpers/index.js';
 /** Known app-service endpoints, shown by `gipity service list` and used to
  *  give a helpful hint on typos. POST endpoints take a JSON body; GET
  *  endpoints (model/voice listings) are reached with `--get`. */
@@ -35,16 +36,41 @@ serviceCommand
     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)'));
+    console.log(muted('Verifying what a signed-out visitor of your deployed app gets? Add --anon.'));
     console.log('');
     for (const s of SERVICES) {
         console.log(`${bold(s.name.padEnd(width))}  ${muted(`[${s.method}] ${s.desc}`)}`);
     }
 }));
+/** A signed-out visitor's 401 on a service is almost never "the caller needs to
+ *  log in" — it is the app's service `billing_mode` still on the `user_pays`
+ *  default, which asks every anonymous visitor of a PUBLIC page to sign in and
+ *  pay from their own credits. The server's raw body says LOGIN_REQUIRED and
+ *  nothing about the manifest, so the fix costs a doc hunt across skills. Name
+ *  the cause and the exact edit here, at the moment it happens. */
+export function anonBillingHint(name, err) {
+    if (!(err instanceof ApiError) || err.statusCode !== 401)
+        return null;
+    // Only the "sign in to use this" refusal is a billing-mode symptom. A missing
+    // credential (the visitor token never minted) is a different failure with a
+    // different fix, and must not be dressed up as one.
+    if (err.code !== 'LOGIN_REQUIRED')
+        return null;
+    const service = name.split('/')[0];
+    return (`An anonymous visitor cannot call '${service}': it is on the user_pays default, so every signed-out ` +
+        `visitor to a public page is asked to sign in and pay from their own credits. If this app serves the ` +
+        `public (a help bubble, a landing page), switch it to owner-pays in gipity.yaml and redeploy:\n` +
+        `  deploy:\n    phases:\n      - services\n  service_definitions:\n    - service: ${service}\n      billing_mode: owner_pays\n` +
+        `  gipity deploy dev --only services`);
+}
 serviceCommand
     .command('call <name> [body]')
-    .description('Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling.')
-    .option('--data <json>', 'JSON request body (alternative to the positional [body])')
+    .description('Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling; --anon calls it as a signed-out visitor instead.')
+    .option('-d, --data <json>', 'JSON request body: inline JSON, @file to read a file, or @- / - for stdin (alternative to the positional [body])')
+    .option('--file <field=@path>', 'Attach a file as { data, media_type } under <field> (the vision/media shape these services expect), repeatable, e.g. --file image=@receipt.png', (v, acc) => (acc || []).concat(v))
+    .option('--anon', 'Call as an anonymous visitor (the public path a signed-out user of your deployed app hits) instead of as your signed-in account')
     .option('--get', 'Issue a GET (for listing endpoints like llm/models, tts/voices)')
+    .option('--field <path>', 'Print only this field of the result (dot path, e.g. choices.0.message.content)')
     .option('--json', 'Output compact JSON')
     .action((name, bodyArg, opts) => run('Call', async () => {
     const config = requireConfig();
@@ -52,9 +78,47 @@ serviceCommand
     // like `location/geocode` and `llm/models` resolve correctly.
     const path = name.split('/').map(encodeURIComponent).join('/');
     const url = `/api/${config.projectGuid}/services/${path}`;
-    const res = opts.get
-        ? await get(url)
-        : await post(url, JSON.parse(bodyArg || opts.data || '{}'));
+    const body = resolveBody(bodyArg || opts.data, opts.file);
+    // Name the calling identity (stderr, so stdout stays parseable). An owner
+    // call always succeeds regardless of billing mode, so without this line a
+    // "the service works" verification silently proves nothing about the
+    // visitors the deployed app actually serves.
+    if (opts.anon) {
+        console.error(muted('Auth: anonymous visitor (the public path a signed-out user of your deployed app hits)'));
+    }
+    else {
+        const who = getAuth()?.email;
+        console.error(muted(`Auth: calling as ${who ?? 'your signed-in account'} (the owner persona - always billed to you and never blocked by billing_mode; use --anon for the public visitor path)`));
+    }
+    let res;
+    try {
+        if (opts.anon) {
+            // The short-lived app token IS the visitor's credential here (unlike a
+            // public function, a service is never callable with no token at all).
+            // If it can't be minted, say so — otherwise the request comes back as a
+            // bare 401 that reads like an app-permissions problem.
+            const headers = await mintAppToken(config.projectGuid);
+            if (!headers) {
+                throw new Error(`Could not mint a visitor token for this project, so there is no anonymous path to call. ` +
+                    `That means the app is not deployed on this API base yet: run \`gipity deploy dev\` first, ` +
+                    `then re-run this command.`);
+            }
+            res = await publicRequest(opts.get ? 'GET' : 'POST', url, opts.get ? undefined : body, headers);
+        }
+        else {
+            res = opts.get ? await get(url) : await post(url, body);
+        }
+    }
+    catch (err) {
+        const hint = opts.anon ? anonBillingHint(name, err) : null;
+        if (!hint)
+            throw err;
+        throw new Error(`${err.message}\n${hint}`);
+    }
+    if (opts.field) {
+        emitField(res, opts.field);
+        return;
+    }
     console.log(opts.json ? JSON.stringify(res) : JSON.stringify(res, null, 2));
 }));
 //# sourceMappingURL=service.js.map

package/dist/commands/workflow.js

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { get, post, put, del } from '../api.js';
 import { getConfig, requireConfig } from '../config.js';
 import { success, error as clrError, muted, bold } from '../colors.js';
@@ -29,6 +29,51 @@ function formatRunLine(r) {
     const statusColor = r.status === 'completed' ? success : r.status === 'failed' ? clrError : muted;
     return `${muted(r.short_guid)}  ${statusColor(r.status)}  ${dur}  ${runTokens(r)} tokens  ${muted(fmtTime(r.started_at))}`;
 }
+/** Classify a step-output value that is a *string* holding JSON: parsed, or
+ *  looks-like-JSON-but-doesn't-parse (a truncated / cut-off llm response — the
+ *  step reports `completed` and the next step then can't read a field out of
+ *  it). `null` means "not a JSON string at all". */
+function jsonStringInfo(v) {
+    if (typeof v !== 'string')
+        return null;
+    const t = v.trim();
+    if (!t.startsWith('{') && !t.startsWith('['))
+        return null;
+    try {
+        const parsed = JSON.parse(t);
+        return typeof parsed === 'object' && parsed !== null ? { ok: true, value: parsed } : null;
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function labelFor(info) {
+    return info.ok ? '(JSON string)' : clrError('(truncated/invalid JSON string)');
+}
+/** Render one step's output for humans.
+ *
+ *  Step outputs routinely carry a JSON *string* under a key — an `llm` step's
+ *  `result` is the common case. Dumped through a plain JSON.stringify that
+ *  arrives as one enormous backslash-escaped line: unreadable, and it hides the
+ *  single fact you need most, that the NEXT step sees a string, not an object
+ *  (so `{{step.summary}}` resolves to nothing). Label such keys
+ *  `"key" (JSON string)` and print the decoded value indented under it, so both
+ *  the content and the string-vs-object handoff are obvious at a glance. */
+function renderStepOutput(output) {
+    if (output && typeof output === 'object' && !Array.isArray(output)) {
+        return Object.entries(output).map(([k, v]) => {
+            const info = jsonStringInfo(v);
+            if (!info)
+                return `${JSON.stringify(k)}: ${JSON.stringify(v, null, 2)}`;
+            const body = info.ok ? JSON.stringify(info.value, null, 2) : JSON.stringify(v);
+            return `${JSON.stringify(k)} ${labelFor(info)}: ${body}`;
+        }).join('\n');
+    }
+    const info = jsonStringInfo(output);
+    if (info?.ok)
+        return JSON.stringify(info.value, null, 2);
+    return JSON.stringify(output, null, 2);
+}
 /** Print each step's status, tokens, model, error and output. A run line alone
  *  says a run finished, not what it did — without the steps you can't tell a
  *  workflow that wrote a row from one that silently skipped every step. */
@@ -46,7 +91,7 @@ function printStepRuns(steps, emptyNote) {
         if (s.error_message)
             console.log(`     ${clrError(s.error_message)}`);
         if (s.output_json !== null && s.output_json !== undefined) {
-            console.log(JSON.stringify(s.output_json, null, 2).split('\n').map(l => `     ${l}`).join('\n'));
+            console.log(renderStepOutput(s.output_json).split('\n').map(l => `     ${l}`).join('\n'));
         }
     }
 }
@@ -149,10 +194,18 @@ workflowCommand
 }));
 workflowCommand
     .command('run <name>')
-    .description('Trigger a workflow (add --wait to block until it finishes)')
+    .description("Run a workflow: waits for it to finish and prints each step's status and output (--no-wait to fire and forget)")
     .option('--json', 'Output as JSON')
-    .option('--wait', 'Block until the triggered run reaches a terminal state, then print it')
-    .option('--timeout <s>', 'Max seconds to wait with --wait', '120')
+    // Waiting is the default: a bare trigger tells you nothing about what the
+    // workflow did, so every caller followed it with a poll-and-drill-in loop.
+    // `--no-wait` is the escape hatch for fire-and-forget.
+    .option('--no-wait', 'Trigger and return immediately instead of waiting for the run')
+    // Waiting is already the default, but `--wait` reads naturally and older
+    // docs/muscle memory reach for it — accept it silently rather than erroring.
+    .addOption(new Option('--wait', 'Wait for the run (already the default)').hideHelp())
+    // LLM steps routinely take a couple of minutes; a 120s default timed out on
+    // healthy runs and taught callers to always pass --timeout.
+    .option('--timeout <s>', 'Max seconds to wait for the run to finish', '300')
     .action((name, _opts, cmd) => run('Run', async () => {
     const opts = mergedOpts(cmd);
     const wf = await resolveWorkflow(name);
@@ -168,7 +221,7 @@ workflowCommand
     const before = await get(`/workflows/${wf.short_guid}/runs?limit=1`);
     const prevGuid = before.data[0]?.short_guid;
     await post(`/workflows/${wf.short_guid}/run`, {});
-    const r = await waitForRun(wf.short_guid, prevGuid, Number(opts.timeout) || 120);
+    const r = await waitForRun(wf.short_guid, prevGuid, Number(opts.timeout) || 300);
     if (opts.json) {
         console.log(JSON.stringify(r));
     }

package/dist/db-checkpoint.js

@@ -0,0 +1,42 @@
+/**
+ * Database checkpoint / restore — the undo for a LIVE write test.
+ *
+ * Verifying a write path for real (clicking Approve in the deployed UI, calling
+ * a function that inserts, letting a scheduled workflow run) mutates the
+ * project's real data, and there was no way to put it back - agents ended up
+ * hand-writing SQL to scrub their own test strings out.
+ *
+ * The snapshot itself is the SERVER's job: it lives in a sibling schema the app
+ * can't see, and restore runs in one transaction. This module is just the
+ * client - the CLI never composes checkpoint DDL, so a snapshot can never show
+ * up in `db query`, in a migration diff, or in app code that enumerates tables.
+ */
+import { get, post } from './api.js';
+/** First database in the project, or null when the project has none. */
+export async function resolveDatabase(projectGuid, explicit) {
+    if (explicit)
+        return explicit;
+    const res = await get(`/projects/${projectGuid}/databases`);
+    return res.data.length > 0 ? res.data[0].friendlyName : null;
+}
+async function checkpoint(projectGuid, database, action, keep) {
+    const res = await post(`/projects/${projectGuid}/db/checkpoint`, { database, action, ...(keep ? { keep } : {}) });
+    return res.data;
+}
+/** Snapshot every app table. Replaces any previous checkpoint. */
+export function createCheckpoint(projectGuid, database) {
+    return checkpoint(projectGuid, database, 'create');
+}
+/**
+ * Put every checkpointed table back to its snapshot contents and drop the
+ * snapshot (unless `keep`). Sequences are deliberately NOT rewound - leaving
+ * them ahead keeps ids unique against anything the test run handed out.
+ */
+export function restoreCheckpoint(projectGuid, database, opts = {}) {
+    return checkpoint(projectGuid, database, 'restore', opts.keep);
+}
+/** Drop the checkpoint without restoring (keep whatever the run wrote). */
+export function dropCheckpoint(projectGuid, database) {
+    return checkpoint(projectGuid, database, 'drop');
+}
+//# sourceMappingURL=db-checkpoint.js.map

package/dist/index.js

@@ -4002,9 +4002,10 @@ async function confirm(question, opts = {}) {
   const defaultYes = opts.default === "yes";
   if (opts.skip ?? _autoConfirm) return true;
   if (!process.stdin.isTTY) {
+    if (opts.headless === "no") return false;
     console.error(`Confirmation required (non-interactive). Re-run with --yes:
   ${rerunWithYes()}`);
-    return false;
+    process.exit(1);
   }
   const hint = defaultYes ? dim("[Y/n]") : dim("[y/N]");
   process.stdout.write(`${question} ${hint}: `);
@@ -32101,7 +32102,7 @@ Run \`gipity --help\` for the full list. Use \`--help\` on any command for detai
 
 Function return shape: \`gipity fn call\`, the in-test \`ctx.fn.call\`/\`callAs\`, and the client \`Gipity.fn\` all return your function's value **unwrapped** - read/assert \`result.field\`. Only raw HTTP/\`curl\` wraps it as \`{ data: ... }\`; never write \`result.data.field\` in a test.
 
-Tests are isolated, not run against your live DB: \`gipity test\` points \`ctx.fn.call\`/\`callAs\` at a throwaway copy of your database (your \`migrations/\` + \`seeds/\`), reset (truncate + reseed) before every run - so test rows never reach the deployed app and you don't write teardown. Functions see \`ctx.isTest === true\` during a run (use it to skip your own rate limiting); the platform also suppresses \`notify()\` push so a suite can't spam subscribers. Reference data tests need goes in seed files; a runtime-written settings table that isn't seeded goes under \`test.preserve\` in \`gipity.yaml\`. Build per-file fixtures in \`setup(fn)\` \u2192 \`ctx.fixtures\`, and namespace unique values with \`ctx.testId\`.
+Tests are isolated, not run against your live DB: \`gipity test\` points \`ctx.fn.call\`/\`callAs\` at a throwaway copy of your database (your \`migrations/\` + \`seeds/\`), one per test FILE, reset (truncate + reseed) before the file runs - so files can't interfere, test rows never reach the deployed app, and you don't write teardown. Functions see \`ctx.isTest === true\` during a run (use it to skip your own rate limiting); the platform also suppresses \`notify()\` push so a suite can't spam subscribers. Reference data tests need goes in seed files; a runtime-written settings table that isn't seeded goes under \`test.preserve\` in \`gipity.yaml\`. Build per-file fixtures in \`setup(fn)\` \u2192 \`ctx.fixtures\`.
 
 ## Hit friction on the platform? Report it in real time
 
@@ -32172,7 +32173,7 @@ App development skills:
 - \`app-development\` - functions, database, and API
 - \`app-import\` - import apps from GitHub/.gip bundles (incl. Vercel/Replit/Lovable porting) and export any project as a portable .gip - app_import tool, gipity save/load
 - \`app-records\` - Gipity Records: declared tables \u2192 validated CRUD, provenance, workflows, auto UI
-- \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the isolated test DB)
+- \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the per-file test DB)
 - \`deploy\` - the deploy pipeline & gipity.yaml manifest
 - \`jobs\` - long-running CPU + GPU compute jobs (Python / Node / bash)
 - \`realtime-scheduled-app\` - recipe: realtime presence/messages + DB function + scheduled poster, end-to-end
@@ -35730,6 +35731,30 @@ init_colors();
 init_auth();
 init_config();
 
+// src/db-checkpoint.ts
+init_api();
+async function resolveDatabase(projectGuid2, explicit) {
+  if (explicit) return explicit;
+  const res = await get(`/projects/${projectGuid2}/databases`);
+  return res.data.length > 0 ? res.data[0].friendlyName : null;
+}
+async function checkpoint(projectGuid2, database, action, keep) {
+  const res = await post(
+    `/projects/${projectGuid2}/db/checkpoint`,
+    { database, action, ...keep ? { keep } : {} }
+  );
+  return res.data;
+}
+function createCheckpoint(projectGuid2, database) {
+  return checkpoint(projectGuid2, database, "create");
+}
+function restoreCheckpoint(projectGuid2, database, opts = {}) {
+  return checkpoint(projectGuid2, database, "restore", opts.keep);
+}
+function dropCheckpoint(projectGuid2, database) {
+  return checkpoint(projectGuid2, database, "drop");
+}
+
 // src/page-fixtures.ts
 init_api();
 init_config();
@@ -36010,7 +36035,7 @@ var pageEvalCommand = new Command("eval").description("Evaluate JS in a real bro
 ).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) \u2014 nothing a vision model can recognize; to drive a vision app use --camera <path> instead.").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. Bare number = MILLISECONDS (so 90s = 90000, NOT 90); or pass an explicit unit that means the same on both this and \`sandbox run --timeout\` \u2014 --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 \u2014 nothing carries over from earlier --auth runs.").option("--json", "Output as JSON").action((url, exprArg, opts) => run("Page eval", async () => {
+).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 \u2014 nothing carries over from earlier --auth runs.").option("--restore-db", "Snapshot the app database before the script runs and roll it back after, so a write-path check (click Approve, submit the form, edit a row) leaves the real data untouched. Use this whenever the eval WRITES - it is the undo for driving the deployed app against real project data. Same snapshot/undo standalone: gipity db checkpoint / gipity db restore.").option("--json", "Output as JSON").action((url, exprArg, opts) => run("Page eval", async () => {
   const decoy = JS_DECOY_FLAGS.find((f) => opts[f.slice(2)] !== void 0);
   if (decoy) {
     pageEvalCommand.error(
@@ -36091,7 +36116,20 @@ var pageEvalCommand = new Command("eval").description("Evaluate JS in a real bro
   let sentExpr = expr;
   let sentSteps = steps;
   if (opts.camera) assertCameraFile(opts.camera);
+  let restoreDb;
   try {
+    if (opts.restoreDb) {
+      const { config } = await resolveProjectContext({});
+      projectGuid2 = config.projectGuid;
+      const database = await resolveDatabase(config.projectGuid);
+      if (!database) {
+        console.error(muted("--restore-db: this project has no database - nothing to roll back."));
+      } else {
+        const cp2 = await createCheckpoint(config.projectGuid, database);
+        console.error(muted(`Checkpointed ${cp2.tables.length} table(s), ${cp2.rows} row(s) in '${database}' - rolled back when this eval finishes.`));
+        restoreDb = { projectGuid: config.projectGuid, database };
+      }
+    }
     if (fixturePaths.length || opts.camera) {
       const { config } = await resolveProjectContext({});
       projectGuid2 = config.projectGuid;
@@ -36211,6 +36249,14 @@ ${bold("After reload")} ${muted("(page reloaded in place \u2014 storage preserve
       if (d.reloadTruncated) console.log(muted("(reload result truncated to fit context - narrow the expression for the full value)"));
     }
   } finally {
+    if (restoreDb) {
+      try {
+        const r = await restoreCheckpoint(restoreDb.projectGuid, restoreDb.database);
+        console.error(muted(`Rolled ${r.tables.length} table(s) back to the checkpoint (${r.rows} row(s)) - nothing this eval wrote survives.`));
+      } catch (err) {
+        console.error(warning(`\u26A0 Could not roll back the database - the checkpoint is still there, retry with: gipity db restore (${err.message})`));
+      }
+    }
     for (const h of [...hosted, ...camera ? [camera] : []]) {
       try {
         await deleteFixture(projectGuid2, h.guid);
@@ -36307,7 +36353,7 @@ init_auth();
 init_colors();
 init_utils();
 import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
-import { dirname as dirname7, join as join12, resolve as resolvePath } from "path";
+import { dirname as dirname7, extname as extname4, join as join12, resolve as resolvePath } from "path";
 var DEVICE_PRESETS = {
   default: { width: 1280, height: 720 },
   desktop: { width: 1920, height: 1080 },
@@ -36418,6 +36464,14 @@ function resolveDevice(name) {
   const available = [...Object.keys(DEVICE_PRESETS), ...TOUCH_DEVICES].join(", ");
   throw new Error(`Unknown --device preset: "${name}" (known: ${available})`);
 }
+function viewportSlug(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "shot";
+}
+function stemPath(output, suffix) {
+  const ext = extname4(output) || ".png";
+  const base = ext && output.endsWith(ext) ? output.slice(0, -ext.length) : output;
+  return `${base}-${suffix}${ext}`;
+}
 function splitCsv(values) {
   if (!values || values.length === 0) return [];
   return values.flatMap((v7) => v7.split(",").map((s) => s.trim()).filter(Boolean));
@@ -36434,7 +36488,7 @@ var WAIT_FOR_MAX_MS2 = 15e3;
 var WAIT_FOR_DEFAULT_MS = 15e3;
 var MAX_POST_LOAD_DELAY_MS = 3e4;
 var CAMERA_DEFAULT_DELAY_MS = 15e3;
-var pageScreenshotCommand = new Command("screenshot").description("Screenshot a web page").argument("<url>", "URL to screenshot").option("--device <names>", `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(", ")} (comma-separated or repeat flag). mobile/tablet emulate a real touch device \u2014 touch events, mobile user-agent, DPR \u2014 so touch-gated mobile UI actually renders.`, appendOption, []).option("--viewport <dims>", "Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag), e.g. --viewport 390x844 for a phone-sized window", appendOption, []).option("--wait <ms>", `Sleep this many ms after DOMContentLoaded before capturing (default 1000, max ${MAX_POST_LOAD_DELAY_MS}). With --camera it defaults to ${CAMERA_DEFAULT_DELAY_MS} so the vision model is up. Same flag as page eval/inspect.`).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_MS2}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_MS2}). 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)").option("--fake-media", "Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern \u2014 to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.").option("--camera <path>", "Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser's WEBCAM feed, then capture \u2014 so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.").option("--auth", "Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. 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 \u2014 nothing carries over from earlier --auth runs.").option("--ephemeral", "Skip the project screenshot history: do not persist this capture to Gipity (screenshots/ in the project). Local file is still written.").option("--json", "Output JSON metadata instead of a friendly summary").addOption(new Option("--post-load-delay <ms>", "Alias for --wait").hideHelp()).addOption(new Option("--full-page", "Alias for --full").hideHelp()).addOption(new Option("--width <px>", "Alias: --viewport WxH").hideHelp()).addOption(new Option("--height <px>", "Alias: --viewport WxH").hideHelp()).action((url, opts) => run("Page screenshot", async () => {
+var pageScreenshotCommand = new Command("screenshot").description("Screenshot a web page").argument("<url>", "URL to screenshot").option("--device <names>", `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(", ")} (comma-separated or repeat flag). mobile/tablet emulate a real touch device \u2014 touch events, mobile user-agent, DPR \u2014 so touch-gated mobile UI actually renders.`, appendOption, []).option("--viewport <dims>", "Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag), e.g. --viewport 390x844 for a phone-sized window", appendOption, []).option("--wait <ms>", `Sleep this many ms after DOMContentLoaded before capturing (default 1000, max ${MAX_POST_LOAD_DELAY_MS}). With --camera it defaults to ${CAMERA_DEFAULT_DELAY_MS} so the vision model is up. Same flag as page eval/inspect.`).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_MS2}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_MS2}). 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 (default .gipity/screenshots/ss-<host>-<timestamp>.png). With several viewports it is a stem: -o tmp/shot.png --device desktop,mobile writes tmp/shot-desktop.png and tmp/shot-mobile.png.").option("--no-reload-between", "Skip reload between viewports (faster, lower fidelity - only safe for static pages)").option("--fake-media", "Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern \u2014 to capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.").option("--camera <path>", "Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser's WEBCAM feed, then capture \u2014 so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.").option("--auth", "Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. 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 \u2014 nothing carries over from earlier --auth runs.").option("--ephemeral", "Skip the project screenshot history: do not persist this capture to Gipity (screenshots/ in the project). Local file is still written.").option("--json", "Output JSON metadata instead of a friendly summary").addOption(new Option("--post-load-delay <ms>", "Alias for --wait").hideHelp()).addOption(new Option("--full-page", "Alias for --full").hideHelp()).addOption(new Option("--width <px>", "Alias: --viewport WxH").hideHelp()).addOption(new Option("--height <px>", "Alias: --viewport WxH").hideHelp()).action((url, opts) => run("Page screenshot", async () => {
   const aliasFlag = ACTION_ALIAS_FLAGS.find((f) => opts[f.slice(2)] !== void 0);
   if (aliasFlag) {
     console.error(muted(
@@ -36504,9 +36558,10 @@ var pageScreenshotCommand = new Command("screenshot").description("Screenshot a
     ...deviceNames.map(resolveDevice),
     ...viewportStrs.map(parseViewportString)
   ];
-  if (opts.output && customViewports.length > 1) {
-    throw new Error("--output can only be used with a single viewport");
-  }
+  const viewportLabels = [
+    ...deviceNames.map(viewportSlug),
+    ...viewportStrs.map(viewportSlug)
+  ];
   const userSpecifiedViewports = customViewports.length > 0;
   const slug = slugFromUrl(url);
   const ts2 = timestampSlug();
@@ -36565,8 +36620,16 @@ var pageScreenshotCommand = new Command("screenshot").description("Screenshot a
   }
   const dir = defaultScreenshotDir();
   const savedFiles = [];
+  const usedStems = /* @__PURE__ */ new Set();
+  const outputPath = (i) => {
+    if (pngs.length === 1) return opts.output;
+    let suffix = viewportLabels[i] ?? dimSuffix(meta.screenshots[i].viewport);
+    while (usedStems.has(suffix)) suffix += `-${i + 1}`;
+    usedStems.add(suffix);
+    return stemPath(opts.output, suffix);
+  };
   for (let i = 0; i < pngs.length; i++) {
-    const target = opts.output ? opts.output : join12(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
+    const target = opts.output ? outputPath(i) : join12(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
     mkdirSync7(dirname7(target), { recursive: true });
     writeFileSync8(target, pngs[i].buffer);
     savedFiles.push(resolvePath(target));
@@ -37111,6 +37174,47 @@ dbCommand.command("drop <name>").description("Drop a database").option("--projec
     console.log(success(`Dropped database '${name}'.`));
   }
 }));
+dbCommand.command("checkpoint").description("Snapshot every table so a write test can be undone. Take one before exercising a real write path (page eval on the deployed app, fn call, workflow run), then `gipity db restore` to put the data back exactly as it was - no hand-written SQL to scrub test strings out of real content.").option("--database <name>", "Database name").option("--drop", "Discard the existing checkpoint without restoring (keep whatever the run wrote)").option("--json", "Output as JSON").action((opts) => run("Checkpoint", async () => {
+  const config = requireConfig();
+  const dbName = await resolveDatabase(config.projectGuid, opts.database);
+  if (!dbName) {
+    console.error(error("No databases in this project - nothing to checkpoint."));
+    process.exit(1);
+  }
+  if (opts.drop) {
+    const dropped = await dropCheckpoint(config.projectGuid, dbName);
+    if (opts.json) {
+      console.log(JSON.stringify(dropped));
+    } else {
+      console.log(dropped.tables.length === 0 ? `No checkpoint in '${dbName}'.` : success(`Discarded the checkpoint of ${dropped.tables.length} table(s) in '${dbName}'. Current data kept.`));
+    }
+    return;
+  }
+  const res = await createCheckpoint(config.projectGuid, dbName);
+  if (opts.json) {
+    console.log(JSON.stringify(res));
+  } else if (res.tables.length === 0) {
+    console.log(`Database '${dbName}' has no tables - nothing to checkpoint.`);
+  } else {
+    console.log(success(`Checkpointed ${res.tables.length} table(s), ${res.rows} row(s) in '${dbName}'.`));
+    console.log("Undo everything written since: gipity db restore");
+  }
+}));
+dbCommand.command("restore").description("Roll every table back to the last `gipity db checkpoint` and drop the checkpoint. The undo for a live write test.").option("--database <name>", "Database name").option("--keep", "Keep the checkpoint after restoring, so you can run the same write test again").option("--json", "Output as JSON").action((opts) => run("Restore", async () => {
+  const config = requireConfig();
+  const dbName = await resolveDatabase(config.projectGuid, opts.database);
+  if (!dbName) {
+    console.error(error("No databases in this project - nothing to restore."));
+    process.exit(1);
+  }
+  const res = await restoreCheckpoint(config.projectGuid, dbName, { keep: opts.keep });
+  if (opts.json) {
+    console.log(JSON.stringify(res));
+  } else {
+    console.log(success(`Restored ${res.tables.length} table(s) to the checkpoint (${res.rows} row(s)) in '${dbName}'.`));
+    if (opts.keep) console.log("Checkpoint kept - restore again any time.");
+  }
+}));
 
 // src/commands/memory.ts
 init_api();
@@ -37165,7 +37269,7 @@ memoryCommand.command("delete <topic>").description("Delete a topic").option("--
 init_api();
 init_config();
 import { readFileSync as readFileSync15, existsSync as existsSync11, statSync as statSync7, mkdirSync as mkdirSync8, writeFileSync as writeFileSync9 } from "fs";
-import { dirname as dirname8, extname as extname4, relative as relative4, resolve as resolve11, sep as sep3 } from "path";
+import { dirname as dirname8, extname as extname5, relative as relative4, resolve as resolve11, sep as sep3 } from "path";
 init_colors();
 var LANG_MAP = {
   js: "javascript",
@@ -37229,7 +37333,7 @@ function resolveLanguage(opts) {
     process.exit(1);
   }
   if (explicit) return explicit;
-  const fromExt = opts.filePath ? LANG_MAP[extname4(opts.filePath).slice(1).toLowerCase()] : void 0;
+  const fromExt = opts.filePath ? LANG_MAP[extname5(opts.filePath).slice(1).toLowerCase()] : void 0;
   if (fromExt) return fromExt;
   if (opts.filePath) {
     console.error(error(`Cannot infer the language of ${opts.filePath} from its extension (expected .js, .py, or .sh).`));
@@ -37940,6 +38044,33 @@ function formatRunLine(r) {
   const statusColor = r.status === "completed" ? success : r.status === "failed" ? error : muted;
   return `${muted(r.short_guid)}  ${statusColor(r.status)}  ${dur}  ${runTokens(r)} tokens  ${muted(fmtTime(r.started_at))}`;
 }
+function jsonStringInfo(v7) {
+  if (typeof v7 !== "string") return null;
+  const t = v7.trim();
+  if (!t.startsWith("{") && !t.startsWith("[")) return null;
+  try {
+    const parsed = JSON.parse(t);
+    return typeof parsed === "object" && parsed !== null ? { ok: true, value: parsed } : null;
+  } catch {
+    return { ok: false };
+  }
+}
+function labelFor(info2) {
+  return info2.ok ? "(JSON string)" : error("(truncated/invalid JSON string)");
+}
+function renderStepOutput(output) {
+  if (output && typeof output === "object" && !Array.isArray(output)) {
+    return Object.entries(output).map(([k7, v7]) => {
+      const info3 = jsonStringInfo(v7);
+      if (!info3) return `${JSON.stringify(k7)}: ${JSON.stringify(v7, null, 2)}`;
+      const body = info3.ok ? JSON.stringify(info3.value, null, 2) : JSON.stringify(v7);
+      return `${JSON.stringify(k7)} ${labelFor(info3)}: ${body}`;
+    }).join("\n");
+  }
+  const info2 = jsonStringInfo(output);
+  if (info2?.ok) return JSON.stringify(info2.value, null, 2);
+  return JSON.stringify(output, null, 2);
+}
 function printStepRuns(steps, emptyNote) {
   if (steps.length === 0) {
     console.log(`  ${muted(emptyNote)}`);
@@ -37952,7 +38083,7 @@ function printStepRuns(steps, emptyNote) {
     console.log(`  ${s.step_order}. ${name}${statusColor(s.status)}  ${s.tokens_used ?? 0} tokens${model}`);
     if (s.error_message) console.log(`     ${error(s.error_message)}`);
     if (s.output_json !== null && s.output_json !== void 0) {
-      console.log(JSON.stringify(s.output_json, null, 2).split("\n").map((l7) => `     ${l7}`).join("\n"));
+      console.log(renderStepOutput(s.output_json).split("\n").map((l7) => `     ${l7}`).join("\n"));
     }
   }
 }
@@ -38023,7 +38154,7 @@ workflowCommand.command("info <name>").description("Show workflow details").opti
     }
   }
 }));
-workflowCommand.command("run <name>").description("Trigger a workflow (add --wait to block until it finishes)").option("--json", "Output as JSON").option("--wait", "Block until the triggered run reaches a terminal state, then print it").option("--timeout <s>", "Max seconds to wait with --wait", "120").action((name, _opts, cmd) => run("Run", async () => {
+workflowCommand.command("run <name>").description("Run a workflow: waits for it to finish and prints each step's status and output (--no-wait to fire and forget)").option("--json", "Output as JSON").option("--no-wait", "Trigger and return immediately instead of waiting for the run").addOption(new Option("--wait", "Wait for the run (already the default)").hideHelp()).option("--timeout <s>", "Max seconds to wait for the run to finish", "300").action((name, _opts, cmd) => run("Run", async () => {
   const opts = mergedOpts(cmd);
   const wf2 = await resolveWorkflow(name);
   if (!opts.wait) {
@@ -38034,7 +38165,7 @@ workflowCommand.command("run <name>").description("Trigger a workflow (add --wai
   const before = await get(`/workflows/${wf2.short_guid}/runs?limit=1`);
   const prevGuid = before.data[0]?.short_guid;
   await post(`/workflows/${wf2.short_guid}/run`, {});
-  const r = await waitForRun(wf2.short_guid, prevGuid, Number(opts.timeout) || 120);
+  const r = await waitForRun(wf2.short_guid, prevGuid, Number(opts.timeout) || 300);
   if (opts.json) {
     console.log(JSON.stringify(r));
   } else {
@@ -39046,7 +39177,7 @@ async function runRelaySetup(opts) {
   }
   console.log("");
   const promptText = opts.mode === "run-now" ? "  Set up remote control on this computer" : "  Enable remote control";
-  const enable = await confirm(promptText, { default: "yes" });
+  const enable = await confirm(promptText, { default: "yes", headless: "no" });
   if (!enable) {
     setRelayEnabled(false);
     console.log(`  ${muted("Skipped. Turn on later with")} ${brand("gipity connect")}${muted(".")}`);
@@ -39073,7 +39204,7 @@ async function runRelaySetup(opts) {
   }
   startDaemon();
   console.log("");
-  const autostartOs = await confirm("  Also start at OS login", { default: "yes" });
+  const autostartOs = await confirm("  Also start at OS login", { default: "yes", headless: "no" });
   if (autostartOs) {
     try {
       const res = installAutostart();
@@ -39096,7 +39227,7 @@ async function runRelaySetup(opts) {
   }
   if (getDiagnosticsConsent() === void 0) {
     console.log("");
-    const diag = await confirm("  Share anonymous diagnostics info", { default: "yes" });
+    const diag = await confirm("  Share anonymous diagnostics info", { default: "yes", headless: "no" });
     setDiagnosticsConsent(diag);
   }
   console.log("");
@@ -40623,9 +40754,9 @@ var STARTERS = [
 ];
 var BLANK = [
   { key: "web-simple", hint: "static frontend-only site - pages, dashboards, simple games" },
-  { key: "web-fullstack", hint: "backend API + database wiring - frontend, functions, migrations; deploys green" },
+  { key: "web-fullstack", hint: "backend API + database wiring - frontend, functions, migrations; deploys green empty" },
   { key: "3d-engine", hint: "3D multiplayer wiring - Three.js + Rapier + Gipity Realtime" },
-  { key: "api", hint: "pure API backend, no frontend - one example function + test" }
+  { key: "api", hint: "pure API backend, no frontend - functions + tests, deploys green" }
 ];
 var KITS = [
   { key: "realtime", hint: "multiplayer / presence / shared state" },
@@ -41402,7 +41533,7 @@ async function runInteractive(url, observe, opts) {
   const samples = Math.min(30, Math.max(2, parseInt(opts.samples, 10) || 6));
   const settle = opts.waitFor ? 200 : 1e3;
   const labels = (opts.labels ? String(opts.labels).split(",").map((s) => s.trim()) : []).filter(Boolean);
-  const labelFor = (i) => labels[i] ?? `client-${i}`;
+  const labelFor2 = (i) => labels[i] ?? `client-${i}`;
   warnUnknownTokens(unknownTokens(url, opts.action, observe));
   if (!opts.json) {
     console.log(`${brand("Page test")} ${muted("(interactive)")} ${bold(url)}`);
@@ -41412,16 +41543,16 @@ async function runInteractive(url, observe, opts) {
   for (let i = 0; i < clients; i++) {
     runs.push((async () => {
       await sleep3(i * stagger * 1e3);
-      if (!opts.json) console.log(muted(`client ${i} (${labelFor(i)}) joining`));
-      const clientUrl = subst(url, labelFor(i), i);
+      if (!opts.json) console.log(muted(`client ${i} (${labelFor2(i)}) joining`));
+      const clientUrl = subst(url, labelFor2(i), i);
       const expr = buildHarness(
-        opts.action ? subst(opts.action, labelFor(i), i) : void 0,
-        subst(observe, labelFor(i), i),
-        labelFor(i),
+        opts.action ? subst(opts.action, labelFor2(i), i) : void 0,
+        subst(observe, labelFor2(i), i),
+        labelFor2(i),
         hold,
         samples
       );
-      return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor);
+      return observeClient(clientUrl, expr, i, labelFor2(i), settle, hold, opts.waitFor);
     })());
   }
   const results = (await Promise.all(runs)).sort((a, b7) => a.i - b7.i);
@@ -41475,7 +41606,7 @@ async function runPassive(url, opts) {
   const stagger = opts.stagger != null ? Math.max(0, parseInt(opts.stagger, 10) || 0) : 12;
   const wait = Math.min(3e4, Math.max(2e3, parseInt(opts.wait, 10) || 24e3));
   const labels = (opts.labels ? String(opts.labels).split(",").map((s) => s.trim()) : []).filter(Boolean);
-  const labelFor = (i) => labels[i] ?? `client-${i}`;
+  const labelFor2 = (i) => labels[i] ?? `client-${i}`;
   warnUnknownTokens(unknownTokens(url));
   if (!opts.json) {
     console.log(`${brand("Page test")} ${bold(url)}`);
@@ -41486,7 +41617,7 @@ async function runPassive(url, opts) {
     runs.push((async () => {
       await sleep3(i * stagger * 1e3);
       if (!opts.json) console.log(`${muted(`client ${i}${i === 0 ? " (first)" : ""} starting`)}`);
-      return inspectClient(subst(url, labelFor(i), i), wait, i);
+      return inspectClient(subst(url, labelFor2(i), i), wait, i);
     })());
   }
   const results = (await Promise.all(runs)).sort((a, b7) => a.i - b7.i);
@@ -41736,14 +41867,18 @@ recordsCommand.command("config <table>").description("Show or set a table's Reco
     res.data
   );
 }));
-recordsCommand.command("query <table>").description("List records").option("--filter <filter>", 'Filter string (e.g., "status:eq:active")').option("--sort <sort>", 'Sort string (e.g., "created_at:desc")').option("--limit <n>", "Max rows", "20").option("--offset <n>", "Offset", "0").option("--fields <fields>", "Comma-separated column names").option(ANON_FLAG, ANON_HELP).option("--json", "Output as JSON").action((table, opts) => run("Query", async () => {
+recordsCommand.command("query <table>").description("List records (full-text search, filter, sort, recycle bin)").option("-q, --q <text>", "Full-text search across the table's text columns (needs `--searchable true` on the table)").option("--filter <filter>", 'AND filter string (e.g., "status:eq:active")').option("--any <filter>", 'OR filter group, same grammar as --filter (e.g., "owner:eq:me,shared:eq:true")').option("--sort <sort>", 'Sort string (e.g., "created_at:desc")').option("--limit <n>", "Max rows", "20").option("--offset <n>", "Offset", "0").option("--fields <fields>", "Comma-separated column names").option("--include-deleted", "Include soft-deleted rows (owner/editor)").option("--only-deleted", "Only soft-deleted rows - the recycle bin (owner/editor)").option(ANON_FLAG, ANON_HELP).option("--json", "Output as JSON").action((table, opts) => run("Query", async () => {
   const api = await recordsHttp(opts);
   const params = new URLSearchParams();
+  if (opts.q) params.set("q", opts.q);
   if (opts.filter) params.set("filter", opts.filter);
+  if (opts.any) params.set("any", opts.any);
   if (opts.sort) params.set("sort", opts.sort);
   params.set("limit", opts.limit);
   params.set("offset", opts.offset);
   if (opts.fields) params.set("fields", opts.fields);
+  if (opts.includeDeleted) params.set("include_deleted", "1");
+  if (opts.onlyDeleted) params.set("only_deleted", "1");
   const res = await api.get(
     `/api/${api.guid}/records/${table}?${params}`
   );
@@ -41786,14 +41921,27 @@ recordsCommand.command("update <table> <id>").description("Update a record").req
   const res = await api.put(`/api/${api.guid}/records/${table}/${id2}`, data);
   printResult(`Updated: ${JSON.stringify(res.data)}`, opts, res.data);
 }));
-recordsCommand.command("delete <table> <id>").description("Delete a record").option(ANON_FLAG, ANON_HELP).option("--json", "Output as JSON").action((table, id2, opts) => run("Delete", async () => {
-  if (!await confirm(`Delete record ${id2} from "${table}"?`)) {
+recordsCommand.command("delete <table> <id>").description("Delete a record (soft-delete when the table declares one; --purge removes it for good)").option("--purge", "Hard-delete: remove the row AND erase its audit history (owner/editor). Use it to scrub probe rows.").option(ANON_FLAG, ANON_HELP).option("--json", "Output as JSON").action((table, id2, opts) => run("Delete", async () => {
+  const what = opts.purge ? `Purge record ${id2} from "${table}" (also erases its history)?` : `Delete record ${id2} from "${table}"?`;
+  if (!await confirm(what)) {
     printResult("Cancelled.", opts, { table, id: id2, deleted: false, cancelled: true });
     return;
   }
   const api = await recordsHttp(opts);
-  const res = await api.del(`/api/${api.guid}/records/${table}/${id2}`);
-  printResult("Deleted.", opts, res?.data ?? { table, id: id2, deleted: true });
+  const res = await api.del(
+    `/api/${api.guid}/records/${table}/${id2}${opts.purge ? "?purge=1" : ""}`
+  );
+  const data = res?.data ?? { table, id: id2, deleted: true, purged: !!opts.purge };
+  printResult(
+    data.purged ? "Purged - the row and its audit history are gone." : `Deleted. If "${table}" declares a soft-delete column the row is only stamped deleted (see it with \`gipity records query ${table} --only-deleted\`, bring it back with \`gipity records restore ${table} ${id2}\`, remove it for good with \`--purge\`).`,
+    opts,
+    data
+  );
+}));
+recordsCommand.command("restore <table> <id>").description("Un-delete a soft-deleted record (owner/editor)").option("--json", "Output as JSON").action((table, id2, opts) => run("Restore", async () => {
+  const api = await recordsHttp(opts);
+  const res = await api.post(`/api/${api.guid}/records/${table}/${id2}/restore`);
+  printResult("Restored.", opts, res?.data ?? { table, id: id2, restored: true });
 }));
 
 // src/commands/fn.ts
@@ -41880,6 +42028,7 @@ fnCommand.command("delete <name>").alias("rm").description("Delete a function").
 
 // src/commands/service.ts
 init_api();
+init_auth();
 init_config();
 init_colors();
 var SERVICES = [
@@ -41905,16 +42054,59 @@ serviceCommand.command("list").description("List callable app services").option(
   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)"));
+  console.log(muted("Verifying what a signed-out visitor of your deployed app gets? Add --anon."));
   console.log("");
   for (const s of SERVICES) {
     console.log(`${bold(s.name.padEnd(width))}  ${muted(`[${s.method}] ${s.desc}`)}`);
   }
 }));
-serviceCommand.command("call <name> [body]").description("Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling.").option("--data <json>", "JSON request body (alternative to the positional [body])").option("--get", "Issue a GET (for listing endpoints like llm/models, tts/voices)").option("--json", "Output compact JSON").action((name, bodyArg, opts) => run("Call", async () => {
+function anonBillingHint(name, err) {
+  if (!(err instanceof ApiError) || err.statusCode !== 401) return null;
+  if (err.code !== "LOGIN_REQUIRED") return null;
+  const service = name.split("/")[0];
+  return `An anonymous visitor cannot call '${service}': it is on the user_pays default, so every signed-out visitor to a public page is asked to sign in and pay from their own credits. If this app serves the public (a help bubble, a landing page), switch it to owner-pays in gipity.yaml and redeploy:
+  deploy:
+    phases:
+      - services
+  service_definitions:
+    - service: ${service}
+      billing_mode: owner_pays
+  gipity deploy dev --only services`;
+}
+serviceCommand.command("call <name> [body]").description("Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling; --anon calls it as a signed-out visitor instead.").option("-d, --data <json>", "JSON request body: inline JSON, @file to read a file, or @- / - for stdin (alternative to the positional [body])").option("--file <field=@path>", "Attach a file as { data, media_type } under <field> (the vision/media shape these services expect), repeatable, e.g. --file image=@receipt.png", (v7, acc) => (acc || []).concat(v7)).option("--anon", "Call as an anonymous visitor (the public path a signed-out user of your deployed app hits) instead of as your signed-in account").option("--get", "Issue a GET (for listing endpoints like llm/models, tts/voices)").option("--field <path>", "Print only this field of the result (dot path, e.g. choices.0.message.content)").option("--json", "Output compact JSON").action((name, bodyArg, opts) => run("Call", async () => {
   const config = requireConfig();
   const path5 = name.split("/").map(encodeURIComponent).join("/");
   const url = `/api/${config.projectGuid}/services/${path5}`;
-  const res = opts.get ? await get(url) : await post(url, JSON.parse(bodyArg || opts.data || "{}"));
+  const body = resolveBody(bodyArg || opts.data, opts.file);
+  if (opts.anon) {
+    console.error(muted("Auth: anonymous visitor (the public path a signed-out user of your deployed app hits)"));
+  } else {
+    const who = getAuth()?.email;
+    console.error(muted(`Auth: calling as ${who ?? "your signed-in account"} (the owner persona - always billed to you and never blocked by billing_mode; use --anon for the public visitor path)`));
+  }
+  let res;
+  try {
+    if (opts.anon) {
+      const headers = await mintAppToken(config.projectGuid);
+      if (!headers) {
+        throw new Error(
+          `Could not mint a visitor token for this project, so there is no anonymous path to call. That means the app is not deployed on this API base yet: run \`gipity deploy dev\` first, then re-run this command.`
+        );
+      }
+      res = await publicRequest(opts.get ? "GET" : "POST", url, opts.get ? void 0 : body, headers);
+    } else {
+      res = opts.get ? await get(url) : await post(url, body);
+    }
+  } catch (err) {
+    const hint = opts.anon ? anonBillingHint(name, err) : null;
+    if (!hint) throw err;
+    throw new Error(`${err.message}
+${hint}`);
+  }
+  if (opts.field) {
+    emitField(res, opts.field);
+    return;
+  }
   console.log(opts.json ? JSON.stringify(res) : JSON.stringify(res, null, 2));
 }));
 

package/dist/knowledge.js

@@ -116,7 +116,7 @@ Run \`gipity --help\` for the full list. Use \`--help\` on any command for detai
 
 Function return shape: \`gipity fn call\`, the in-test \`ctx.fn.call\`/\`callAs\`, and the client \`Gipity.fn\` all return your function's value **unwrapped** - read/assert \`result.field\`. Only raw HTTP/\`curl\` wraps it as \`{ data: ... }\`; never write \`result.data.field\` in a test.
 
-Tests are isolated, not run against your live DB: \`gipity test\` points \`ctx.fn.call\`/\`callAs\` at a throwaway copy of your database (your \`migrations/\` + \`seeds/\`), reset (truncate + reseed) before every run - so test rows never reach the deployed app and you don't write teardown. Functions see \`ctx.isTest === true\` during a run (use it to skip your own rate limiting); the platform also suppresses \`notify()\` push so a suite can't spam subscribers. Reference data tests need goes in seed files; a runtime-written settings table that isn't seeded goes under \`test.preserve\` in \`gipity.yaml\`. Build per-file fixtures in \`setup(fn)\` → \`ctx.fixtures\`, and namespace unique values with \`ctx.testId\`.
+Tests are isolated, not run against your live DB: \`gipity test\` points \`ctx.fn.call\`/\`callAs\` at a throwaway copy of your database (your \`migrations/\` + \`seeds/\`), one per test FILE, reset (truncate + reseed) before the file runs - so files can't interfere, test rows never reach the deployed app, and you don't write teardown. Functions see \`ctx.isTest === true\` during a run (use it to skip your own rate limiting); the platform also suppresses \`notify()\` push so a suite can't spam subscribers. Reference data tests need goes in seed files; a runtime-written settings table that isn't seeded goes under \`test.preserve\` in \`gipity.yaml\`. Build per-file fixtures in \`setup(fn)\` → \`ctx.fixtures\`.
 
 ## Hit friction on the platform? Report it in real time
 
@@ -187,7 +187,7 @@ App development skills:
 - \`app-development\` - functions, database, and API
 - \`app-import\` - import apps from GitHub/.gip bundles (incl. Vercel/Replit/Lovable porting) and export any project as a portable .gip - app_import tool, gipity save/load
 - \`app-records\` - Gipity Records: declared tables → validated CRUD, provenance, workflows, auto UI
-- \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the isolated test DB)
+- \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the per-file test DB)
 - \`deploy\` - the deploy pipeline & gipity.yaml manifest
 - \`jobs\` - long-running CPU + GPU compute jobs (Python / Node / bash)
 - \`realtime-scheduled-app\` - recipe: realtime presence/messages + DB function + scheduled poster, end-to-end

package/dist/relay/onboarding.js

@@ -82,7 +82,7 @@ export async function runRelaySetup(opts) {
     const promptText = opts.mode === 'run-now'
         ? '  Set up remote control on this computer'
         : '  Enable remote control';
-    const enable = await confirm(promptText, { default: 'yes' });
+    const enable = await confirm(promptText, { default: 'yes', headless: 'no' });
     if (!enable) {
         state.setRelayEnabled(false);
         console.log(`  ${muted('Skipped. Turn on later with')} ${brand('gipity connect')}${muted('.')}`);
@@ -119,7 +119,7 @@ export async function runRelaySetup(opts) {
     startDaemon();
     console.log('');
     // Offer OS-level autostart (launchd / systemd --user / Task Scheduler).
-    const autostartOs = await confirm('  Also start at OS login', { default: 'yes' });
+    const autostartOs = await confirm('  Also start at OS login', { default: 'yes', headless: 'no' });
     if (autostartOs) {
         try {
             const res = installAutostart();
@@ -153,7 +153,7 @@ export async function runRelaySetup(opts) {
     // on|off` flips it later.)
     if (state.getDiagnosticsConsent() === undefined) {
         console.log('');
-        const diag = await confirm('  Share anonymous diagnostics info', { default: 'yes' });
+        const diag = await confirm('  Share anonymous diagnostics info', { default: 'yes', headless: 'no' });
         state.setDiagnosticsConsent(diag);
     }
     console.log('');

package/dist/utils.js

@@ -119,17 +119,28 @@ function rerunWithYes() {
  *  - `opts.skip` (or the global `--yes` flag) auto-returns `true`.
  *  - Renders a `[Y/n]:` or `[y/N]:` hint automatically - callers should NOT
  *    append their own y/N suffix (or a trailing `?`/`:`) to `question`.
- *  - In non-TTY environments without `--yes`, returns `false` and prints a hint. */
+ *  - In non-TTY environments without `--yes`, this EXITS the process with code 1
+ *    (it never returns) - see the comment in the body for why. Pass
+ *    `{ headless: 'no' }` for prompts that merely OFFER something optional,
+ *    where declining is a normal successful outcome. */
 export async function confirm(question, opts = {}) {
     const defaultYes = opts.default === 'yes';
     if (opts.skip ?? _autoConfirm)
         return true;
     if (!process.stdin.isTTY) {
-        // Headless/agent context: no one can answer the prompt. Don't just say
-        // "use --yes" - echo the exact command to re-run so the fix is copy-paste,
-        // not a second guessing trip.
+        // Headless/agent context: no one can answer the prompt. For an optional
+        // offer, declining and carrying on is the right answer (`headless: 'no'`).
+        // For everything else the command did NOT do what it was asked to do, so
+        // exit non-zero: an agent that pipes or suppresses output
+        // (`gipity records delete games 1 --purge >/dev/null 2>&1`) otherwise sees
+        // a clean exit 0 and believes the delete happened, then burns turns
+        // discovering it silently cancelled. The exit status is the only signal
+        // that survives redirection. The message echoes the exact command to
+        // re-run so the fix is copy-paste, not a second guessing trip.
+        if (opts.headless === 'no')
+            return false;
         console.error(`Confirmation required (non-interactive). Re-run with --yes:\n  ${rerunWithYes()}`);
-        return false;
+        process.exit(1);
     }
     const hint = defaultYes ? dim('[Y/n]') : dim('[y/N]');
     process.stdout.write(`${question} ${hint}: `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "The full-stack platform tuned for AI agents. Database, storage, auth, functions, deploy, and drop-in kits - all agent-tuned. Pair with Claude Code or use standalone.",
   "bin": {
     "gipity": "dist/updater/shim.js",
@@ -14,7 +14,7 @@
     "prepack": "npm run build",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "npm run build && node --test dist/__tests__/utils.test.js dist/__tests__/template-vars.test.js dist/__tests__/platform.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-unretrievable.test.js dist/__tests__/sync-clean-check.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/api-401-retry.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/build-picker.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/session-pool.test.js dist/__tests__/relay-diagnostics.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/ingest-queue.test.js dist/__tests__/media-upload.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/capture-parsers.test.js dist/__tests__/agents.test.js dist/__tests__/capture-lock.test.js dist/__tests__/capture-resolve.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-brand.test.js dist/__tests__/cli-cmd-bug.test.js dist/__tests__/cli-cmd-bug-queue.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-storage.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-status.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-key.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js dist/__tests__/setup-codex-hooks.test.js dist/__tests__/trace.test.js",
+    "test:smoke": "npm run build && node --test dist/__tests__/utils.test.js dist/__tests__/template-vars.test.js dist/__tests__/platform.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-unretrievable.test.js dist/__tests__/sync-clean-check.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/api-401-retry.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/build-picker.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/session-pool.test.js dist/__tests__/relay-diagnostics.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/ingest-queue.test.js dist/__tests__/media-upload.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/capture-parsers.test.js dist/__tests__/agents.test.js dist/__tests__/capture-lock.test.js dist/__tests__/capture-resolve.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-brand.test.js dist/__tests__/cli-cmd-bug.test.js dist/__tests__/cli-cmd-bug-queue.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-db-checkpoint.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-storage.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-status.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-key.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js dist/__tests__/setup-codex-hooks.test.js dist/__tests__/trace.test.js",
     "test:smoke:quick": "node scripts/smoke-quick.mjs",
     "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-live.test.js dist/__tests__/cli-e2e-sync-live.test.js dist/__tests__/cli-e2e-sync-stress-live.test.js dist/__tests__/cli-e2e-rollback-live.test.js dist/__tests__/cli-e2e-services-media-live.test.js dist/__tests__/cli-e2e-workflow-live.test.js dist/__tests__/cli-e2e-sandbox-live.test.js dist/__tests__/cli-e2e-page-fetch-live.test.js dist/__tests__/cli-e2e-page-test-live.test.js",
     "test:e2e:sync": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sync-live.test.js",