gipity 1.0.391 → 1.0.394

package/dist/api.js

@@ -16,13 +16,23 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
-async function getHeaders() {
+/** Resolve the Bearer token value. A GIPITY_TOKEN env var (a long-lived agent
+ *  API token) takes precedence over the saved session — the persistent,
+ *  login-free path for headless agents and CI. Falls back to the refreshed
+ *  session access token. */
+async function bearerToken() {
+    const envToken = process.env.GIPITY_TOKEN?.trim();
+    if (envToken)
+        return envToken;
     await refreshTokenIfNeeded();
     const auth = getAuth();
     if (!auth)
         throw new Error('Not authenticated. Run: gipity login');
+    return auth.accessToken;
+}
+async function getHeaders() {
     return {
-        'Authorization': `Bearer ${auth.accessToken}`,
+        'Authorization': `Bearer ${await bearerToken()}`,
         'Content-Type': 'application/json',
     };
 }
@@ -125,13 +135,9 @@ export async function sendMessage(message) {
 }
 /** Download a file as raw bytes (no JSON parsing) */
 export async function download(path) {
-    await refreshTokenIfNeeded();
-    const auth = getAuth();
-    if (!auth)
-        throw new Error('Not authenticated. Run: gipity login');
     const url = `${baseUrl()}${path}`;
     const res = await fetch(url, {
-        headers: { 'Authorization': `Bearer ${auth.accessToken}` },
+        headers: { 'Authorization': `Bearer ${await bearerToken()}` },
     });
     if (!res.ok) {
         throw new ApiError(res.status, 'DOWNLOAD_ERROR', `Download failed: ${res.statusText}`);
@@ -141,13 +147,9 @@ export async function download(path) {
 /** Download a response as a Node.js Readable stream */
 export async function downloadStream(path) {
     const { Readable } = await import('stream');
-    await refreshTokenIfNeeded();
-    const auth = getAuth();
-    if (!auth)
-        throw new Error('Not authenticated. Run: gipity login');
     const url = `${baseUrl()}${path}`;
     const res = await fetch(url, {
-        headers: { 'Authorization': `Bearer ${auth.accessToken}` },
+        headers: { 'Authorization': `Bearer ${await bearerToken()}` },
     });
     if (!res.ok) {
         throw new ApiError(res.status, 'DOWNLOAD_ERROR', `Download failed: ${res.statusText}`);

package/dist/auth.js

@@ -2,7 +2,11 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, chmodSy
 import { join } from 'path';
 import { homedir } from 'os';
 import { decodeJwtExp } from './utils.js';
-const AUTH_DIR = join(homedir(), '.gipity');
+// GIPITY_DIR lets a caller keep a SEPARATE auth context (its own auth.json) from
+// the default ~/.gipity — e.g. GipRunner logging into a local dev server without
+// clobbering your real (prod) login. Only the auth dir moves; HOME is untouched,
+// so the `claude` subprocess and git/npm still use the real home.
+const AUTH_DIR = process.env.GIPITY_DIR || join(homedir(), '.gipity');
 const AUTH_FILE = join(AUTH_DIR, 'auth.json');
 let cached = null;
 export function getAuth() {
@@ -52,18 +56,10 @@ export function clearAuth() {
     catch { /* already gone */ }
     cached = null;
 }
-export function isExpired() {
-    const auth = getAuth();
-    if (!auth)
-        return true;
-    const expiresAt = new Date(auth.expiresAt).getTime();
-    const buffer = 5 * 60 * 1000; // 5 minute buffer
-    return Date.now() > expiresAt - buffer;
-}
 /** True only when re-login is genuinely required: the refresh token itself
- *  has expired. Access-token expiry (`expiresAt` / isExpired) is invisible
- *  to users — every API call renews it via refreshTokenIfNeeded() — so it
- *  must never be surfaced as a session warning. */
+ *  has expired. Access-token expiry (`expiresAt`) is invisible to users —
+ *  every API call renews it via refreshTokenIfNeeded() — so it must never be
+ *  surfaced as a session warning. */
 export function sessionExpired() {
     const auth = getAuth();
     if (!auth)
@@ -73,40 +69,78 @@ export function sessionExpired() {
         return false; // undecodable - let the refresh path decide
     return Date.now() > exp * 1000;
 }
+const delay = (ms) => new Promise(r => setTimeout(r, ms));
+/** Renew the access token (5-min buffer) before an authenticated call, surviving
+ *  the case that broke overnight fix-mode runs: MANY concurrent `gipity` processes
+ *  (relay daemon, file-sync hook, parallel commands) sharing one ~/.gipity/auth.json.
+ *  Refresh tokens are SINGLE-USE — the server rotates them, so when several siblings
+ *  race to refresh the same token, the first wins and the rest get a 401. The old
+ *  code trusted a stale in-process cache and, on that race, let the 401 reach the
+ *  caller, whose handler called clearAuth() and DELETED the shared file — locking
+ *  every sibling out mid-run ("Not logged in"). Fix: always read the file fresh, and
+ *  retry the race/transient failures, re-reading each attempt so we ADOPT whatever
+ *  token a sibling just rotated in rather than resubmitting the rotated-away one.
+ *  Stays void / never throws / never clears auth: a genuine dead token still flows to
+ *  the caller's existing 401 path (which messages "run: gipity login"). */
 export async function refreshTokenIfNeeded() {
-    if (!isExpired())
-        return;
-    const auth = getAuth();
+    const auth = readAuthFresh(); // never the cache — a sibling may have rotated
     if (!auth)
-        return; // not logged in, caller will handle
-    try {
-        const config = await import('./config.js');
-        const apiBase = config.resolveApiBase();
-        const res = await fetch(`${apiBase}/auth/refresh`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ refreshToken: auth.refreshToken }),
-        });
-        if (!res.ok) {
-            cached = null; // force re-login
+        return; // not logged in - caller throws the clean error
+    cached = auth;
+    const buffer = 5 * 60 * 1000; // refresh 5 min before the access token lapses
+    const fresh = (a) => Date.now() <= new Date(a.expiresAt).getTime() - buffer;
+    if (fresh(auth))
+        return;
+    // If the refresh token itself has expired, re-login is genuinely required; leave the
+    // expired auth in place so the caller's existing 401 path prompts `gipity login`.
+    const refreshExp = decodeJwtExp(auth.refreshToken);
+    if (refreshExp && Date.now() > refreshExp * 1000)
+        return;
+    const { resolveApiBase } = await import('./config.js');
+    const apiBase = resolveApiBase();
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        const cur = readAuthFresh(); // a sibling may have just refreshed for us
+        if (cur && fresh(cur)) {
+            cached = cur;
             return;
         }
-        const json = await res.json();
-        const exp = decodeJwtExp(json.accessToken);
-        if (!exp) {
-            cached = null;
+        const refreshToken = cur?.refreshToken ?? auth.refreshToken;
+        let res;
+        try {
+            res = await fetch(`${apiBase}/auth/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refreshToken }),
+            });
+        }
+        catch {
+            await delay(attempt * 300);
+            continue; // network blip - retry
+        }
+        if (res.ok) {
+            const json = await res.json().catch(() => null);
+            const exp = json && decodeJwtExp(json.accessToken);
+            if (!json || !exp) {
+                await delay(attempt * 300);
+                continue;
+            }
+            saveAuth({ accessToken: json.accessToken, refreshToken: json.refreshToken, email: auth.email, expiresAt: new Date(exp * 1000).toISOString() });
             return;
         }
-        const expiresAt = new Date(exp * 1000).toISOString();
-        saveAuth({
-            accessToken: json.accessToken,
-            refreshToken: json.refreshToken,
-            email: auth.email,
-            expiresAt,
-        });
-    }
-    catch {
-        // Refresh failed - caller will see expired auth
+        // 401/403 → the refresh token was rejected outright (it was rotated away by a
+        // sibling, or genuinely expired). Re-read once more in case a sibling's fresh
+        // token just landed; otherwise stop and let the caller's 401 path re-login.
+        if (res.status === 401 || res.status === 403) {
+            const after = readAuthFresh();
+            if (after && fresh(after)) {
+                cached = after;
+                return;
+            }
+            return;
+        }
+        await delay(attempt * 300); // 5xx / unexpected → transient, retry
     }
+    // Retries exhausted: leave the existing token. The caller's request will 401 and the
+    // existing handler messages the user — we never delete the shared auth.json here.
 }
 //# sourceMappingURL=auth.js.map

package/dist/commands/agent.js

@@ -68,12 +68,103 @@ agentCommand
     else if (field === 'temp' || field === 'temperature')
         body.temperature = parseFloat(value);
     else {
-        console.error(clrError(`Unknown field: ${field}. Use: model, temp`));
+        console.error(clrError(`Unknown field: ${field}. Use: model, temp (for soul/goal use \`gipity agent soul|goal\`)`));
         process.exit(1);
     }
     await put(`/agents/${config.agentGuid}`, body);
     printResult(`Set ${field} = ${value}`, opts, { success: true, field, value });
 }));
+/** The active agent's guid, or a clear error - the brain commands all need one. */
+function requireAgentGuid() {
+    const config = requireConfig();
+    if (!config.agentGuid) {
+        console.error(clrError('No active agent. Switch to one with: gipity agent <name>'));
+        process.exit(1);
+    }
+    return config.agentGuid;
+}
+// --- Brain: soul / goal / rules / learn ---
+// These hit the account-scoped /account/agents surface (the same dual-auth,
+// app-callable routes a deployed app uses), so the CLI, the web terminal, and an
+// app all drive the agent's brain through one set of endpoints. No more
+// hand-rolled `curl -X PUT a.gipity.ai/agents/:guid/soul` with a scraped token.
+agentCommand
+    .command('soul [text...]')
+    .description("Show the current agent's soul, or set it (its voice/personality)")
+    .option('--json', 'Output as JSON')
+    .action((text, opts) => run('Soul', async () => {
+    const guid = requireAgentGuid();
+    if (text && text.length) {
+        const content = text.join(' ');
+        const res = await put(`/account/agents/${guid}/soul`, { content });
+        printResult('Soul updated.', opts, res.data);
+    }
+    else {
+        const res = await get(`/account/agents/${guid}/soul`);
+        printResult(res.data.content || '(no soul set)', opts, res.data);
+    }
+}));
+agentCommand
+    .command('goal [text...]')
+    .description("Show the current agent's goal, or set it")
+    .option('--clear', 'Clear the goal (back to a plain assistant)')
+    .option('--json', 'Output as JSON')
+    .action((text, opts) => run('Goal', async () => {
+    const guid = requireAgentGuid();
+    if (opts.clear) {
+        const res = await put(`/account/agents/${guid}/goal`, { goal: null });
+        printResult('Goal cleared.', opts, res.data);
+    }
+    else if (text && text.length) {
+        const goal = text.join(' ');
+        const res = await put(`/account/agents/${guid}/goal`, { goal });
+        printResult('Goal updated.', opts, res.data);
+    }
+    else {
+        const res = await get(`/account/agents/${guid}/goal`);
+        printResult(res.data.goal || '(no goal set)', opts, res.data);
+    }
+}));
+const rulesCommand = agentCommand
+    .command('rules')
+    .description("Show the agent's rules playbook (manual + learned)")
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Rules', async () => {
+    const guid = requireAgentGuid();
+    const res = await get(`/account/agents/${guid}/rules`);
+    printList(res.data, opts, 'No rules yet.', r => `[${r.source}]  ${r.short_guid}  ${r.text}`);
+}));
+rulesCommand
+    .command('add <text...>')
+    .description('Add a manual rule')
+    .option('--json', 'Output as JSON')
+    .action((text, opts) => run('Add', async () => {
+    const guid = requireAgentGuid();
+    const res = await post(`/account/agents/${guid}/rules`, { text: text.join(' ') });
+    printResult(`Added rule ${res.data[0].short_guid}.`, opts, res.data[0]);
+}));
+rulesCommand
+    .command('rm <rule-guid>')
+    .alias('delete')
+    .description('Deactivate a rule by its guid')
+    .option('--json', 'Output as JSON')
+    .action((ruleGuid, opts) => run('Remove', async () => {
+    const guid = requireAgentGuid();
+    await del(`/account/agents/${guid}/rules/${ruleGuid}`);
+    printResult(`Removed rule ${ruleGuid}.`, opts, { removed: ruleGuid });
+}));
+agentCommand
+    .command('learn')
+    .description("Teach the agent from one correction (distills a durable learned rule)")
+    .requiredOption('--original <text>', 'What the agent originally produced')
+    .requiredOption('--comment <text>', "Your correction / why it was wrong")
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Learn', async () => {
+    const guid = requireAgentGuid();
+    const res = await post(`/account/agents/${guid}/learn`, { original: opts.original, comment: opts.comment });
+    const d = res.data;
+    printResult(d.saved ? `Learned: ${d.rule.text}` : `No rule saved (${d.reason || 'too idiosyncratic to generalize'}).`, opts, d);
+}));
 agentCommand
     .command('rename <new-name>')
     .description('Rename the current agent')

package/dist/commands/db.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { get, post, sendMessage } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, success } from '../colors.js';
-import { run, printList } from '../helpers/index.js';
+import { run, printList, emitField } from '../helpers/index.js';
 import { confirm } from '../utils.js';
 export const dbCommand = new Command('db')
     .description('Manage databases');
@@ -10,6 +10,7 @@ dbCommand
     .command('query <sql>')
     .description('Run SQL')
     .option('--database <name>', 'Database name')
+    .option('--field <path>', 'Print only this field of the result (dot path, e.g. rows.0.status)')
     .option('--json', 'Output as JSON')
     .action((sql, opts) => run('Query', async () => {
     const config = requireConfig();
@@ -24,7 +25,10 @@ dbCommand
         dbName = listRes.data[0].friendlyName;
     }
     const res = await post(`/projects/${config.projectGuid}/db/query`, { sql, database: dbName });
-    if (opts.json) {
+    if (opts.field) {
+        emitField(res.data, opts.field);
+    }
+    else if (opts.json) {
         console.log(JSON.stringify(res.data));
     }
     else {

package/dist/commands/fn.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { get, post, del } from '../api.js';
 import { requireConfig } from '../config.js';
 import { error as clrError, bold, muted, success } from '../colors.js';
-import { run, printList } from '../helpers/index.js';
+import { run, printList, emitField } from '../helpers/index.js';
 import { confirm } from '../utils.js';
 export const fnCommand = new Command('fn')
     .description('Manage functions');
@@ -38,12 +38,17 @@ fnCommand
     .command('call <name> [body]')
     .description('Call a function')
     .option('--data <json>', 'JSON request body')
+    .option('--field <path>', 'Print only this field of the result (dot path, e.g. items.0.short_guid)')
     .option('--json', 'Output as JSON')
     .action((name, bodyArg, opts) => run('Call', async () => {
     const config = requireConfig();
     const raw = bodyArg || opts.data || '{}';
     const body = JSON.parse(raw);
     const res = await post(`/api/${config.projectGuid}/fn/${encodeURIComponent(name)}`, body);
+    if (opts.field) {
+        emitField(res.data, opts.field);
+        return;
+    }
     console.log(opts.json ? JSON.stringify(res.data) : JSON.stringify(res.data, null, 2));
 }));
 fnCommand

package/dist/commands/generate.js

@@ -1,19 +1,48 @@
 import { Command } from 'commander';
 import { post } from '../api.js';
-import { resolveProjectContext } from '../config.js';
+import { resolveProjectContext, getConfigPath } from '../config.js';
+import { pushFile } from '../sync.js';
 import { writeFileSync } from 'fs';
-import { resolve as resolvePath } from 'path';
+import { resolve as resolvePath, dirname, relative, isAbsolute } from 'path';
 import { error as clrError, success, muted, info } from '../colors.js';
 import { IMAGE_MODELS_DOC, IMAGE_GEMINI_ASPECT_RATIOS, IMAGE_GEMINI_SIZES, VIDEO_MODELS_DOC, TTS_PROVIDER_DESCRIPTIONS } from '../provider-docs.js';
-/** Download a URL and save to a local file. Returns the absolute path written,
- *  so callers can report exactly where the file landed. */
+/** Download a URL and save to a local file, then push it up to the project so
+ *  the cloud (and anything that mirrors it) immediately matches local disk.
+ *  Returns the absolute path written, so callers can report where it landed.
+ *
+ *  The push matters because generated media is written straight to disk with
+ *  writeFileSync, which does NOT trip the editor's file-sync hook the way an
+ *  agent's own file write does. Without it the file is local-only until the
+ *  next `gipity sync`, so `gipity sandbox run` - which mirrors the *server* -
+ *  can't see a just-generated image to convert/optimize it. Pushing here closes
+ *  that gap so the "sandbox auto-mirrors the project" contract holds right after
+ *  generation. Best-effort: the local save already succeeded, so a push failure
+ *  only warns and points at `gipity sync`. */
 async function downloadFile(url, filename) {
     const res = await fetch(url);
     if (!res.ok)
         throw new Error(`Download failed: ${res.status}`);
     const buffer = Buffer.from(await res.arrayBuffer());
     writeFileSync(filename, buffer);
-    return resolvePath(filename);
+    const savedPath = resolvePath(filename);
+    await pushGenerated(savedPath);
+    return savedPath;
+}
+/** Sync a freshly generated file up to the linked project (no-op when there's
+ *  no local project, or the file was written outside the project tree). */
+async function pushGenerated(savedPath) {
+    const configPath = getConfigPath();
+    if (!configPath)
+        return; // not linked to a project - nothing to sync into
+    const rel = relative(dirname(configPath), savedPath);
+    if (rel.startsWith('..') || isAbsolute(rel))
+        return; // outside the project tree
+    try {
+        await pushFile(savedPath);
+    }
+    catch (err) {
+        console.error(muted(`Note: couldn't sync to the cloud automatically (${err.message}). Run \`gipity sync\` before referencing this file in \`gipity sandbox run\`.`));
+    }
 }
 // ── IMAGE ──────────────────────────────────────────────────────────────
 const imageCommand = new Command('image')

package/dist/commands/page-eval.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { post, get, ApiError } from '../api.js';
 import { brand, bold, muted, warning } from '../colors.js';
 import { run } from '../helpers/index.js';
@@ -122,6 +122,13 @@ export function evalExecTimeoutMessage(result) {
         `and cannot extend it. Split a long interactive check into several shorter 'page eval' calls (e.g. ` +
         `one per state to verify), keeping each body's in-page waits well under ${EVAL_EXEC_BUDGET_MS / 1000}s.`);
 }
+// Agents instinctively reach for a flag to pass the script (`--js`, `--script`,
+// `--code`, …); the JS is actually the positional <expr> (or --file for a saved
+// script). Without these, commander answers `--js` with "did you mean --json?" —
+// a trap, since --json is a real flag that changes output but still leaves the
+// script unset, sending the agent in a loop. Capture the common guesses as
+// hidden decoy options so the action can redirect to the positional arg exactly.
+const JS_DECOY_FLAGS = ['--js', '--javascript', '--script', '--code', '--expr', '--eval', '--exec'];
 // The long-tail escape hatch alongside `page inspect`'s fixed bundle: when the
 // curated metrics don't cover what you need (computed styles, element rects,
 // visibility, z-index stacks), eval an expression in page context and get the
@@ -143,6 +150,13 @@ export const pageEvalCommand = new Command('eval')
     .option('--wait-timeout <ms>', 'Max ms to wait for --wait-for before giving up', '5000')
     .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
+    // positional <expr> precisely, before the inline/--file shape checks fire.
+    const decoy = JS_DECOY_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
+    if (decoy) {
+        pageEvalCommand.error(`error: ${decoy} is not a flag — pass the JavaScript as the positional <expr> argument ` +
+            `(or --file <path> for a saved script), e.g. gipity page eval "<url>" 'document.title'`);
+    }
     // Arg-shape errors go through commander's error() so the enableHelpAfterError
     // hook renders this command's help inline with the one-line error LAST
     // (survives `| tail`), same as commander-detected errors like a missing url.
@@ -225,6 +239,11 @@ export const pageEvalCommand = new Command('eval')
         }
     }
 }));
+// Register the JS-intent flag guesses as hidden decoys (take a value so they
+// swallow the script the agent passed) — the action turns any of them into the
+// precise "JS is the positional arg" redirect above.
+for (const f of JS_DECOY_FLAGS)
+    pageEvalCommand.addOption(new Option(`${f} <value>`).hideHelp());
 // Each `page eval` call runs to completion before the next starts, so two evals
 // fired back-to-back never coexist in time - they CANNOT test whether two live
 // clients see each other (presence, shared state). For that, use the genuinely-

package/dist/commands/page-inspect.js

@@ -6,6 +6,13 @@ import { run } from '../helpers/index.js';
 import { capWaitMs } from './page-eval.js';
 /** A console line is an error-level entry (page error or console.error). */
 const isErrorLine = (line) => /^error:/i.test(line);
+/** A message-less, cross-origin "Script error." The throwing <script> lacks
+ *  CORS, so the browser strips its message/stack and the source is unknowable
+ *  from the console alone — there is no own-code stack to chase. These can't be
+ *  attributed to app code, so we surface them apart from real console errors
+ *  rather than letting an unactionable (and sometimes growing) count read as a
+ *  regression in the app the agent just wrote. */
+const isMessagelessCrossOrigin = (line) => isErrorLine(line) && /message-less|cross-origin|Script error\.?/i.test(line);
 function shortUrl(url, truncate = true, maxLen = 100) {
     let result;
     try {
@@ -55,13 +62,55 @@ export const pageInspectCommand = new Command('inspect')
         };
         const res = await post(`/tools/browser/inspect`, inspectBody);
         const b = res.data;
-        // Self-verify console errors before flagging them. A freshly-deployed page's
-        // first hit can throw a one-time, non-reproducible error — typically a
-        // cross-origin "Script error." with no message/stack from a CDN asset still
-        // propagating — and reporting it as a real defect sends agents chasing a
-        // phantom. So when the first probe reports error-level console lines, re-probe
-        // once (the sticky session is now warm) and keep only the errors that recur;
-        // errors seen on a single probe are surfaced separately as transient noise.
+        // ── Strip the platform's own instrumentation noise first ──
+        // Every deployed page loads Gipity's injected analytics SDK, which POSTs to
+        // Gipity's traffic/error log endpoints (`/api/<guid>/log/traffic|error`).
+        // Those are platform infrastructure, not the app's resources, so when one
+        // fails it surfaces as a failed resource on the Gipity host PLUS a generic,
+        // URL-less "Failed to load resource" console error — identical noise on
+        // essentially every deployed app. Drop both so an agent inspecting the app
+        // it just built sees only its own code's resources, not the platform's.
+        const isPlatformLog = (entry) => {
+            const urlPart = entry.replace(/\s*\([^)]*\)\s*$/, '');
+            try {
+                const u = new URL(urlPart);
+                return /(^|\.)gipity\.ai$/.test(u.hostname) && /\/log\/(traffic|error)$/.test(u.pathname);
+            }
+            catch {
+                return false;
+            }
+        };
+        const platformFailures = (b.failedResources || []).filter(isPlatformLog);
+        b.failedResources = (b.failedResources || []).filter((r) => !isPlatformLog(r));
+        // Each failed platform POST also emits exactly one generic, URL-less
+        // "Failed to load resource" console error. Drop one per platform failure —
+        // the text is identical, so removing by count is exact and any genuine app
+        // 404 keeps its own (indistinguishable) line.
+        let platformConsoleToDrop = platformFailures.length;
+        if (platformConsoleToDrop > 0) {
+            b.console = (b.console || []).filter((l) => {
+                if (platformConsoleToDrop > 0 && /^error:\s*Failed to load resource:/i.test(l)) {
+                    platformConsoleToDrop--;
+                    return false;
+                }
+                return true;
+            });
+        }
+        // Pull message-less cross-origin "Script error." lines out first. They carry
+        // no source/stack, so they're never actionable as app-code defects, and on a
+        // Gipity-deployed page the platform's own injected SDK is itself a
+        // cross-origin script — so these are reported separately (not as app console
+        // errors, and not folded into the re-probe count) instead of misleading the
+        // agent into chasing its own code.
+        const crossOriginErrors = (b.console || []).filter(isMessagelessCrossOrigin);
+        b.console = (b.console || []).filter((l) => !isMessagelessCrossOrigin(l));
+        // Self-verify the remaining console errors before flagging them. A
+        // freshly-deployed page's first hit can throw a one-time, non-reproducible
+        // error from an asset still propagating — and reporting it as a real defect
+        // sends agents chasing a phantom. So when the first probe reports error-level
+        // console lines, re-probe once (the sticky session is now warm) and keep only
+        // the errors that recur; errors seen on a single probe are surfaced
+        // separately as transient noise.
         let transientErrors = [];
         if ((b.console || []).some(isErrorLine)) {
             try {
@@ -76,7 +125,11 @@ export const pageInspectCommand = new Command('inspect')
             }
         }
         if (opts.json) {
-            console.log(JSON.stringify(transientErrors.length ? { ...b, transientConsole: transientErrors } : b));
+            console.log(JSON.stringify({
+                ...b,
+                ...(transientErrors.length ? { transientConsole: transientErrors } : {}),
+                ...(crossOriginErrors.length ? { crossOriginConsole: crossOriginErrors } : {}),
+            }));
             return;
         }
         const timing = b.timing || { ttfb: 0, domReady: 0, load: 0 };
@@ -112,7 +165,12 @@ export const pageInspectCommand = new Command('inspect')
             for (const line of transientErrors) {
                 console.log(muted(line));
             }
-            console.log(muted('One-time cold-load artifact (first hit of freshly-deployed assets, or a cross-origin script) — not reproducible, not in your app code. Ignore unless it recurs.'));
+            console.log(muted('One-time cold-load artifact (first hit of freshly-deployed assets) — not reproducible, not in your app code. Ignore unless it recurs.'));
+        }
+        // ── Cross-origin console errors (message-less; source hidden by the browser) ──
+        if (crossOriginErrors.length > 0) {
+            console.log(`\n${bold('Cross-origin console errors')} ${muted(`(${crossOriginErrors.length}, source hidden by the browser)`)}:`);
+            console.log(muted("Message-less — the throwing <script> lacks CORS, so the browser hides its source and there's no own-code stack to chase. Gipity's injected SDK is itself cross-origin, so if your app loads no third-party CDN scripts these are platform noise — ignore them. If your app DOES load a third-party <script>, add crossorigin=\"anonymous\" to that tag to surface the real error."));
         }
         // ── Failed Resources ──
         // Browsers auto-request /favicon.ico at the site root for every page, so a

package/dist/commands/page-screenshot.js

@@ -100,6 +100,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     // so the `?? opts.wait` merge below would never see the --wait alias. Default
     // is applied in the merge instead.
     .option('--post-load-delay <ms>', 'Delay after DOMContentLoaded before capture, in ms (default: 1000)')
+    .option('--action <js>', 'Run JS in the page before capturing — e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs after the post-load delay, then settles again before the shot.')
     .option('--full', 'Capture the full scrollable page (default: viewport only)')
     .option('-o, --output <file>', 'Output path (single viewport only; default .gipity/screenshots/ss-<host>-<timestamp>.png)')
     .option('--device <names>', `Viewport preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag)`, appendOption, [])
@@ -140,6 +141,7 @@ export const pageScreenshotCommand = new Command('screenshot')
         reloadBetween: opts.reloadBetween !== false,
         ...(userSpecifiedViewports ? { viewports: customViewports } : {}),
         ...(opts.fakeMedia ? { fakeMedia: true } : {}),
+        ...(opts.action ? { action: opts.action } : {}),
     };
     const entries = await postForTarEntries('/tools/browser/screenshot', body);
     const metaEntry = entries.find((e) => e.name === 'meta.json');
@@ -231,4 +233,28 @@ export const pageScreenshotCommand = new Command('screenshot')
         console.log(`${label('Screenshot file')} ${success(savedFiles[i])}`);
     }
 }));
+// `screenshot` captures the page AFTER load + settle (+ optional --action). It does
+// NOT scroll or wait for a selector before capture (agents reach for --scroll/
+// --selector and get an unknown-option detour). State the supported levers right
+// here, so the help (rendered on any bad flag, and this 'after' block survives
+// `| tail`/`| grep`) ends the hunt in one shot. --action covers "click, then shoot";
+// --full + crop covers off-screen regions; `page eval` reads data without a picture.
+pageScreenshotCommand.addHelpText('after', `
+Examples:
+  gipity page screenshot "https://dev.gipity.ai/me/app/"
+  gipity page screenshot "https://dev.gipity.ai/me/app/" --full          # whole scrollable page
+  gipity page screenshot "https://dev.gipity.ai/me/app/" --device mobile,desktop
+  gipity page screenshot "https://dev.gipity.ai/me/app/" \\
+    --action "document.getElementById('play').click()"                   # capture an in-game frame
+
+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 post-load
+  delay, 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.
+
+Capturing an off-screen region or reading element data?
+    • --full captures the ENTIRE scrollable page (then crop to the region).
+    • 'gipity page eval <url> "<expr>"' reads any (even off-screen) element's
+      data/state/rect without a picture — e.g. read the chart's bar values
+      directly instead of screenshotting the slide.`);
 //# sourceMappingURL=page-screenshot.js.map

package/dist/commands/sandbox.js

@@ -150,6 +150,17 @@ GCC/Rust).
     }
     const timeout = parseInt(opts.timeout, 10);
     const cwd = resolveRelativeCwd();
+    // 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
+    // process - would otherwise be invisible to the run and the first invocation
+    // would silently miss its inputs. Syncing first makes the auto-mirror reflect
+    // local state regardless of how files got there ("no manual copy needed").
+    // Bidirectional + CAS, so it's a cheap manifest check when nothing changed.
+    // Symmetric with the post-run pull below. Skip in one-off mode (no project).
+    if (getConfigPath()) {
+        await sync({ interactive: false });
+    }
     const res = await post(`/projects/${config.projectGuid}/sandbox/execute`, {
         code: source,
         language,

package/dist/commands/token.js

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import { get, post, del } from '../api.js';
+import { bold, muted, success, warning } from '../colors.js';
+import { run, printList } from '../helpers/index.js';
+export const tokenCommand = new Command('token')
+    .description('Manage agent API tokens (gip_at_*) for headless agents and CI');
+const fmtDate = (d) => (d ? new Date(d).toLocaleDateString() : 'never');
+tokenCommand
+    .command('create')
+    .description('Mint a long-lived agent API token (shown once)')
+    .option('--name <name>', 'Label for the token, e.g. "Hermes on my VPS"')
+    .option('--expires <days>', 'Days until the token expires (default: never)')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Create', async () => {
+    const body = {};
+    if (opts.name)
+        body.name = opts.name;
+    if (opts.expires !== undefined) {
+        const days = parseInt(opts.expires, 10);
+        if (!Number.isFinite(days) || days <= 0)
+            throw new Error('--expires must be a positive number of days');
+        body.expiresInDays = days;
+    }
+    const res = await post('/auth/agent-tokens', body);
+    const { token, shortGuid, expiresAt } = res.data;
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    const expNote = expiresAt ? ` (expires ${fmtDate(expiresAt)})` : ' (never expires)';
+    console.log(success(`Created token ${bold(shortGuid)}${muted(expNote)}.`));
+    console.log('');
+    console.log(token);
+    console.log('');
+    console.log(muted('Use it from an agent, script, or CI — no login needed:'));
+    console.log(`  export GIPITY_TOKEN=${token}`);
+    console.log('');
+    console.log(warning('Copy it now — it will not be shown again.'));
+}));
+tokenCommand
+    .command('list')
+    .alias('ls')
+    .description('List your active agent API tokens')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('List', async () => {
+    const res = await get('/auth/agent-tokens');
+    printList(res.data, opts, 'No agent API tokens.', (t) => {
+        const label = t.name ? `  ${t.name}` : '';
+        return `${bold(t.short_guid)}${label}  ${muted(`created ${fmtDate(t.created_at)}`)}  ${muted(`expires ${fmtDate(t.expires_at)}`)}  ${muted(`last used ${fmtDate(t.last_used_at)}`)}`;
+    });
+}));
+tokenCommand
+    .command('revoke <short_guid>')
+    .alias('rm')
+    .description('Revoke an agent API token (instant, irreversible)')
+    .option('--json', 'Output as JSON')
+    .action((shortGuid, opts) => run('Revoke', async () => {
+    await del(`/auth/agent-tokens/${encodeURIComponent(shortGuid)}`);
+    if (opts.json) {
+        console.log(JSON.stringify({ shortGuid, revoked: true }));
+        return;
+    }
+    console.log(success(`Revoked token ${bold(shortGuid)}.`));
+}));
+//# sourceMappingURL=token.js.map

package/dist/config.js

@@ -45,6 +45,12 @@ export function resolveApiBase() {
     const override = getApiBaseOverride();
     if (override)
         return override;
+    // GIPITY_API_BASE env is a trusted override (any host, like --api-base) so a
+    // caller can point the CLI at a local dev server without passing the flag on
+    // every command — e.g. GipRunner running builds against http://localhost:7201.
+    const fromEnv = process.env.GIPITY_API_BASE;
+    if (fromEnv)
+        return fromEnv;
     const fromConfig = getConfig()?.apiBase;
     if (fromConfig) {
         if (isAllowedApiHost(fromConfig))

package/dist/helpers/index.js

@@ -2,6 +2,6 @@
  * CLI helpers - shared patterns across all commands.
  */
 export { run } from './command.js';
-export { printOutput, printList, printResult } from './output.js';
+export { printOutput, printList, printResult, pluckField, emitField } from './output.js';
 export { syncBeforeAction } from './sync.js';
 //# sourceMappingURL=index.js.map

package/dist/helpers/output.js

@@ -63,6 +63,29 @@ export function printResult(text, opts, jsonData) {
     }
     console.log(text);
 }
+/**
+ * Pluck a nested value out of a result by dot-path. Numeric segments index into
+ * arrays, so `items.0.short_guid` reaches the first item's guid. Returns
+ * `undefined` if any segment along the way is missing. This is what lets
+ * `--field` replace the `... | node -e "JSON.parse(...)"` extraction dance.
+ */
+export function pluckField(data, path) {
+    return path.split('.').reduce((acc, key) => (acc == null ? undefined : acc[key]), data);
+}
+/**
+ * Emit a single plucked field for `--field`. Scalars print raw (no quotes) so
+ * the output drops straight into `$(...)` / pipes; objects/arrays print as
+ * compact JSON. A missing path is an error (exit 1) so scripts fail loudly
+ * instead of silently consuming an empty string.
+ */
+export function emitField(data, path) {
+    const value = pluckField(data, path);
+    if (value === undefined) {
+        console.error(`Field not found: ${path}`);
+        process.exit(1);
+    }
+    console.log(typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value));
+}
 /**
  * Print a list with JSON mode, empty state, and per-item formatting.
  * Replaces the most common output pattern across all commands.

package/dist/index.js

@@ -10,6 +10,7 @@ import { GIPITY_TAGLINE } from './knowledge.js';
 import { getAuth, sessionExpired } from './auth.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
+import { tokenCommand } from './commands/token.js';
 import { initCommand } from './commands/init.js';
 import { statusCommand } from './commands/status.js';
 import { syncCommand } from './commands/sync.js';
@@ -108,7 +109,7 @@ const filesGroup = [fileCommand, syncCommand, pushCommand, uploadCommand];
 const appBuildingGroup = [testCommand, fnCommand, serviceCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
 const utilitiesGroup = [pageCommand, sandboxCommand, generateCommand, emailCommand, gmailCommand, locationCommand, textCommand];
 const agentGroup = [chatCommand, memoryCommand, agentCommand, approvalCommand];
-const setupGroup = [loginCommand, logoutCommand, creditsCommand, planCommand, doctorCommand, updateCommand, uninstallCommand];
+const setupGroup = [loginCommand, logoutCommand, tokenCommand, creditsCommand, planCommand, doctorCommand, updateCommand, uninstallCommand];
 const HELP_SECTIONS = [
     { title: 'Common', cmds: commonGroup },
     { title: 'Connect', cmds: connectGroup },
@@ -125,11 +126,15 @@ program
     .version(pkg.version, '-v, --version')
     .addOption(new Option('--api-base <url>', 'API base URL').hideHelp())
     .option('-y, --yes', 'Skip confirmation prompts');
-program.hook('preAction', () => {
+program.hook('preAction', (_thisCommand, actionCommand) => {
     const globalOpts = program.opts();
     if (globalOpts.apiBase)
         setApiBaseOverride(globalOpts.apiBase);
-    if (globalOpts.yes)
+    // Honor `-y`/`--yes` whether it came before the subcommand (the global flag)
+    // or after it (the per-command flag registered by enableYesEverywhere below),
+    // so both `gipity -y records delete ...` and `gipity records delete ... --yes`
+    // skip confirmation identically.
+    if (globalOpts.yes || actionCommand.opts().yes)
         setAutoConfirm(true);
 });
 // Bracket non-JSON command output with leading/trailing blank lines centrally,
@@ -216,6 +221,25 @@ function enableHelpAfterError(cmd) {
         enableHelpAfterError(sub);
 }
 enableHelpAfterError(program);
+// ── `-y`/`--yes` accepted AFTER any subcommand, not only before it ──────
+// The global `-y` lives on `program`, so Commander parses it only when it
+// precedes the subcommand (`gipity -y records delete ...`). Agents and humans
+// instinctively append it instead (`gipity records delete ... --yes`), which
+// Commander would reject as an unknown option and dump help for. Register the
+// flag on every leaf command so both positions work identically; the preAction
+// hook honors whichever one was set. Skip commands that already declare their
+// own `--yes` (e.g. `fn delete`, `db drop`, `remove`) to avoid a duplicate.
+function enableYesEverywhere(cmd) {
+    if (cmd.commands.length > 0) {
+        for (const sub of cmd.commands)
+            enableYesEverywhere(sub);
+        return;
+    }
+    const hasYes = cmd.options.some(o => o.long === '--yes' || o.short === '-y');
+    if (!hasYes)
+        cmd.addOption(new Option('-y, --yes', 'Skip confirmation prompts').hideHelp());
+}
+enableYesEverywhere(program);
 // Auto-fetch related skill docs when --help is run on a doc-bearing TOP-LEVEL
 // command (e.g. `gipity fn --help`, `gipity db --help`). It must NOT fire for a
 // subcommand's help: `gipity db query --help` should render commander's own

package/dist/knowledge.js

@@ -20,6 +20,7 @@ Templates:
     - \`3d-world\` - Multiplayer world, 3D sandbox, shooter, exploration, virtual showroom (Three.js + Rapier + Colyseus)
     - \`api\` - Backend service, webhook, data pipeline, chatbot, cron job - no frontend
     - \`karaoke-captions\` - Forced-alignment app - karaoke captions, subtitle timing, language learning, dubbing alignment
+    - \`outreach-agent\` - AI outreach / drip-email funnel - reach a list of people with personalized, human-approved emails that auto-send on a schedule and a self-improving agent that learns from your edits
 When unsure, default to \`web-simple\`. After adding the template, edit the generated files, then \`gipity deploy dev\`.
 Only skip this on a build request if the user explicitly says not to.
 
@@ -36,7 +37,8 @@ Kits are reusable building blocks added to an existing app, not whole templates
     - \`gipity add i18n\` - Multi-language for web apps - language picker, locale persistence, RTL, plural/translation lookup. Scaffolds src/js/strings.js and wires it up; move your copy there and read it with t('key'). Web only.
     - \`gipity add records\` - Registry-driven records: declare objects/fields as data, get generic CRUD functions with validation, full-text search, soft delete, ACTOR provenance, and an audit event spine - every write is transactional (row + event). Field types include relations ({id,label}), currency, emails/phones/links composites. Ships backend functions + migrations. Needs a database (web-fullstack/api template).
     - \`gipity add views\` - Generic UI over records-kit objects: sortable/filterable table with full-text search, create/edit/delete forms with type-appropriate widgets, kanban board with drag-to-update. Renders entirely from the field registry - zero per-object UI code. Requires the records kit.
-    - \`gipity add agent-api\` - Make your app agent-operable: named API keys (kit_api_keys) let agents and scripts write through the records kit's single write path with AGENT/API actor attribution - machine writes land on the same audit spine as human edits. Requires the records kit.`;
+    - \`gipity add agent-api\` - Make your app agent-operable: named API keys (kit_api_keys) let agents and scripts write through the records kit's single write path with AGENT/API actor attribution - machine writes land on the same audit spine as human edits. Requires the records kit.
+    - \`gipity add contacts\` - Source-agnostic contact data layer for lead-gen/CRM apps: import people from LinkedIn CSV + Gmail + pasted lists, resolve duplicates into one person while keeping EVERY value from every source with provenance (multi-valued attributes, never overwrites). Exact email/URL auto-merge; fuzzy name+company goes to a human merge-review queue (reversible). Re-imports detect job changes and emit signals. User-definable tags, full-text search, and a transactional event spine. Ships backend functions + migrations. Needs a database (web-fullstack/api template).`;
 export const SKILLS_CONTENT = `# Gipity Integration
 
 Gipity is the cloud platform your project runs on - hosting, databases, deployment, file storage, code execution, workflows, and monitoring. Gip is the cloud agent that runs on Gipity.
@@ -45,7 +47,7 @@ Prefer the cheapest option that works - CLI and sandbox are instant and free, ap
 
 1. CLI commands (fast, no agent overhead). The \`gipity\` CLI covers add, deploy, db, fn, logs, browser, sync, memory, skill, and more. All commands support \`--json\`.
 2. Cloud sandbox via \`gipity sandbox run\` - Docker container with pre-installed tools for media (ffmpeg, ImageMagick, sox), documents (pandoc, LibreOffice), and data (pandas, matplotlib, sqlite3). Run \`gipity skill read sandbox-tools\` for the full toolkit. No network from inside the sandbox - fetch what you need before sending it in.
-3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location. Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|music>\` or \`gipity chat\`. \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) — pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
+3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location. Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|music>\` or \`gipity chat\`. \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) - pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
 4. Delegate to Gip (\`gipity chat "<task>"\`) - only when the work genuinely needs agent reasoning or a tool not in the CLI, sandbox, or app services. Required for: Twitter/X search, Gmail, calendar, push notifications, video understanding, audio source isolation, cross-model second opinions, multi-step orchestration. Don't use \`gipity chat\` for anything the sandbox can do - it's slower and burns tokens.
 
 You are the developer. Write files in this directory - the Gipity Claude Code plugin's hooks auto-sync them to Gipity. Don't run \`npm install\`, \`npm start\`, \`node\`, or \`python\` locally; there is no local runtime. Code runs in the Gipity sandbox.
@@ -78,21 +80,32 @@ The full "when to add a template" rule and the definition of done are spelled ou
 
 Build loop: \`gipity add\` → edit files → \`gipity deploy dev\` → \`gipity page inspect <url>\` → fix any errors → repeat until the definition of done is met.
 
-\`add\` writes real files to disk — Read a scaffolded file before your first Write/Edit to it, or the call fails \`"File has not been read yet"\`. Don't rewrite from memory of the template.
+\`add\` writes real files to disk - Read a scaffolded file before your first Write/Edit to it, or the call fails \`"File has not been read yet"\`. Don't rewrite from memory of the template.
 
 Make your file changes and verify they landed, then run \`gipity deploy dev\` once. \`0 uploaded, N unchanged\` means nothing changed on disk - fix the files, don't re-run deploy or probe the environment.
 
 Before telling the user the app is online, verify the source tree is consistent: no files named like \`* (conflict from *)*\`, and every package directory has its expected canonical entry file. If a conflict artifact exists, resolve it (keep one copy), re-deploy, and re-inspect before reporting done.
 
+## Work on an existing project that isn't local yet
+
+If you're pointed at a project that already exists on Gipity but has no local copy - e.g. the user gives a live URL \`https://dev.gipity.ai/<account>/<slug>/\` (or \`app.gipity.ai\` for prod) and you need its files to edit them - the last path segment is the project **slug**. Pull it down by adopting it into a directory named for the slug:
+
+\`\`\`
+mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <slug>
+\`\`\`
+
+\`init\` matches the existing remote project by slug, links this directory to it, and syncs its files down (you'll see \`Found existing project ...\` and \`Synced N changes\`). There's no separate \`clone\`/\`pull\` - \`init\` against a matching slug *is* the pull. After it finishes, the files are in cwd; edit and \`gipity deploy dev\` as usual. (Already linked to a different project in this dir? Switch and pull instead: \`gipity project <slug>\` then \`gipity sync\`. List your projects with \`gipity project --json\`.)
+
 ## CLI quick reference
 
 Key commands: \`gipity add <template|kit>\`, \`gipity deploy dev\`, \`gipity sandbox run\`, \`gipity page inspect <url>\`, \`gipity page screenshot <url>\`, \`gipity db query "SQL"\`, \`gipity fn call <name>\`, \`gipity logs fn <name>\`, \`gipity skill read <name>\`.
+Pull an existing remote project local (given its URL/slug): \`mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <slug>\` (adopts the matching project and syncs files down - this is the "clone").
 For deterministic text questions (letter/word counts, substring occurrences, nth word/char, anagrams), use \`gipity text analyze "<text>"\` - local and instant, no sandbox or LLM needed.
 Run \`gipity --help\` for the full list. Use \`--help\` on any command for details.
 
-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.
+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 write to your real DB: \`gipity test\` runs the test code sandboxed, but \`ctx.fn.call\`/\`callAs\` hit your actual deployed functions, which write to the same project database the app reads from — rows a test creates persist and surface on the live page. Register \`ctx.cleanup(fn)\` in any write-test to delete what it made; the harness runs every cleanup after the suite (even on failure).
+Tests write to your real DB: \`gipity test\` runs the test code sandboxed, but \`ctx.fn.call\`/\`callAs\` hit your actual deployed functions, which write to the same project database the app reads from - rows a test creates persist and surface on the live page. Register \`ctx.cleanup(fn)\` in any write-test to delete what it made; the harness runs every cleanup after the suite (even on failure).
 
 ## Tool output is complete and synchronous
 
@@ -122,6 +135,7 @@ App services skills (load before calling \`/services/*\` endpoints):
 - \`app-video\` - Gipity Video: models, aspect, resolution
 
 App development skills:
+- \`agent-deploy\` - headless auth via agent API tokens (GIPITY_TOKEN) for unattended deploys
 - \`app-debugging\` - debug a deployed app: page inspect/eval, screenshots, function logs
 - \`app-development\` - functions, database, and API
 - \`deploy\` - the deploy pipeline & gipity.yaml manifest

package/dist/relay/daemon.js

@@ -718,7 +718,13 @@ async function handleDispatch(d) {
     // Future cleanup: see docs/feature-backlog/future-generate-to-vfs.md
     // - server-side /generate/* should write directly to VFS and make
     // this sync redundant for that case.
-    if (!spawnErr) {
+    //
+    // Skip on `killed`: a kill-on-new-message replacement is already starting for
+    // this conv, and a bidirectional reconcile over the half-finished tree of the
+    // cancelled run is exactly the WS-00172 stale-state trap - it pushes/pulls a
+    // partial state that the resuming run then fights. The replacement dispatch
+    // runs its own sync; let it own the tree.
+    if (!spawnErr && !killed) {
         try {
             await spawnSync(cwd, PROJECT_SYNC_TIMEOUT_MS);
         }

package/dist/relay/state.js

@@ -1,7 +1,7 @@
 /**
  * Local state for `gipity relay`.
  *
- * One file, `~/.gipity/relay.json`, mode 0600:
+ * One file, `$GIPITY_DIR/relay.json` (default `~/.gipity/relay.json`), mode 0600:
  *   {
  *     device: { guid, name, platform, token, paired_at },
  *     // (no allowlist - daemon materializes any of the user's projects on demand)
@@ -16,7 +16,13 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
-const RELAY_DIR = join(homedir(), '.gipity');
+// GIPITY_DIR scopes the relay/device state the same way it scopes auth.json (see
+// auth.ts). Without this, a separate auth context (e.g. GIPITY_DIR=~/.giprunner-prod
+// logged in as ec-giprunner@914-6.com) would still read the DEFAULT ~/.gipity device —
+// which is paired to a DIFFERENT account — and project/chat creation fails with
+// "deviceGuid does not match a paired device". Scoping it lets each auth context pair
+// and own its own device. Unset GIPITY_DIR → ~/.gipity, unchanged for normal users.
+const RELAY_DIR = process.env.GIPITY_DIR || join(homedir(), '.gipity');
 const RELAY_FILE = join(RELAY_DIR, 'relay.json');
 const FILE_MODE = 0o600;
 function emptyState() {

package/dist/sync.js

@@ -1030,9 +1030,18 @@ export async function pushFile(filePath) {
     const rel = relative(root, filePath).replace(/\\/g, '/');
     if (shouldIgnore(rel, effectiveIgnore(root, config.ignore)))
         return;
-    const baseline = readBaseline(config.projectGuid);
-    const baseEntry = baseline.files[rel];
+    // Serialize against `gipity sync` and other concurrent pushes by holding the
+    // same per-project lock `sync()` uses. Both paths read-modify-write the shared
+    // baseline; without a common lock, a burst of PostToolUse pushes (each a
+    // detached `gipity push`) racing the UserPromptSubmit/post-dispatch reconciles
+    // drops baseline updates, and the 3-way merge then misreads our own just-pushed
+    // edits as `modified×modified` conflicts (or pulls stale bytes over a live
+    // edit). Read the baseline AFTER acquiring the lock so earlier pushes' writes
+    // are visible. (WS-00172)
+    const releaseLock = await acquireLock();
     try {
+        const baseline = readBaseline(config.projectGuid);
+        const baseEntry = baseline.files[rel];
         const result = await uploadOneFile(config.projectGuid, filePath, rel, {
             expectedServerVersion: baseEntry ? baseEntry.serverVersion : null,
         });
@@ -1051,5 +1060,8 @@ export async function pushFile(filePath) {
         }
         throw err;
     }
+    finally {
+        releaseLock();
+    }
 }
 //# sourceMappingURL=sync.js.map

package/dist/utils.js

@@ -47,6 +47,15 @@ export async function promptBoxed() {
 let _autoConfirm = false;
 export function setAutoConfirm(val) { _autoConfirm = val; }
 export function getAutoConfirm() { return _autoConfirm; }
+/** Reconstruct the current invocation with `--yes` appended, for self-correcting
+ *  non-interactive confirmation hints. Shell-quotes args that need it. */
+function rerunWithYes() {
+    const args = process.argv.slice(2);
+    if (!args.some(a => a === '--yes' || a === '-y'))
+        args.push('--yes');
+    const quote = (a) => (/[^\w@%+=:,./-]/.test(a) ? `'${a.replace(/'/g, `'\\''`)}'` : a);
+    return `gipity ${args.map(quote).join(' ')}`;
+}
 /** Ask for Y/n confirmation. Single-keypress - no Enter required.
  *
  *  - `opts.default` controls which answer Enter / unknown-key selects. Defaults to `'no'`.
@@ -59,7 +68,10 @@ export async function confirm(question, opts = {}) {
     if (opts.skip ?? _autoConfirm)
         return true;
     if (!process.stdin.isTTY) {
-        console.error('Confirmation required. Use --yes to skip prompts.');
+        // 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.
+        console.error(`Confirmation required (non-interactive). Re-run with --yes:\n  ${rerunWithYes()}`);
         return false;
     }
     const hint = defaultYes ? dim('[Y/n]') : dim('[y/N]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.391",
+  "version": "1.0.394",
   "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",
@@ -12,7 +12,7 @@
     "build": "tsc && chmod +x dist/index.js dist/gipcc.js dist/gipccd.js dist/updater/shim.js dist/updater/check.js",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.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__/relay-state.test.js dist/__tests__/relay-daemon.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__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.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-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-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-logout.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-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",
+    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.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__/relay-state.test.js dist/__tests__/relay-daemon.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__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.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-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-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-logout.test.js dist/__tests__/cli-cmd-token.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-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",
     "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-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:sandbox": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sandbox-live.test.js"
   },