gipity 1.0.419 → 1.0.422

package/README.md

@@ -138,7 +138,7 @@ gipity sync down     # Pull remote changes
 | `gipity chat <message>` | Send a message to your Gipity agent |
 | `gipity db` | Query, list, create, or drop project databases |
 | `gipity memory` | Read/write agent and project memory |
-| `gipity sandbox run <code>` | Execute code in a sandboxed container |
+| `gipity sandbox run <code> --lang <js\|py\|bash>` | Execute code in a sandboxed container (language is required) |
 | `gipity project` | List, create, switch, or delete projects |
 | `gipity agent` | List, create, switch, or configure agents |
 | `gipity approval` | List, create, answer, or cancel pending approvals |
@@ -208,7 +208,7 @@ gipity memory write design_notes "use dark theme" --project
 Run code in a sandboxed Docker container with no network access. JavaScript, Python, and Bash.
 
 ```bash
-gipity sandbox run "console.log('Hello')"
+gipity sandbox run "console.log('Hello')" --lang js
 gipity sandbox run "import pandas; print(pandas.__version__)" --lang py
 gipity sandbox run "echo hello" --lang bash
 ```

package/dist/adopt-cwd.js

@@ -175,16 +175,19 @@ export function formatCwdLabel(cwd) {
         return norm;
     return parts.slice(-2).join('/');
 }
-/** Format byte count handling KB/MB/GB. utils.formatSize tops out at MB,
- *  which prints "1024.0 MB" for the 1 GB refuse threshold. */
+/** Format byte count handling KB/MB/GB/TB. utils.formatSize tops out at MB,
+ *  which prints "1024.0 MB" for the 1 GB refuse threshold. TB matters for
+ *  storage quotas, where the top plan is a flat 1 TB. */
 export function formatBytes(n) {
     if (n < 1024)
         return `${n} B`;
-    if (n < 1024 * 1024)
+    if (n < 1024 ** 2)
         return `${(n / 1024).toFixed(1)} KB`;
-    if (n < 1024 * 1024 * 1024)
-        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
-    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+    if (n < 1024 ** 3)
+        return `${(n / 1024 ** 2).toFixed(1)} MB`;
+    if (n < 1024 ** 4)
+        return `${(n / 1024 ** 3).toFixed(2)} GB`;
+    return `${(n / 1024 ** 4).toFixed(2)} TB`;
 }
 /** Adopt `cwd` as a Gipity project. Mirrors `gipity init`'s flow:
  *    1. Slug = slugify(basename(cwd)) - provided by caller (so caller can

package/dist/commands/deploy.js

@@ -80,11 +80,11 @@ export const deployCommand = new Command('deploy')
     const failedPhases = d.phases?.filter(p => p.status === 'failed') ?? [];
     if (failedPhases.length > 0) {
         // The database phase can fail on the account-wide database cap, whose
-        // server message ("Maximum of N databases reached. Drop one first.")
-        // names no command. The droppable databases live in OTHER projects, so
-        // the default project-scoped `gipity db list` shows nothing — point the
-        // caller straight at the account-wide list + drop path so they don't
-        // dead-end (or reach for raw DB access) to free a slot.
+        // server message ("Maximum of N databases reached (you have N). Drop one
+        // first.") names no command. The droppable databases live in OTHER
+        // projects, so the default project-scoped `gipity db list` shows nothing
+        // — point the caller straight at the account-wide list + drop path so
+        // they don't dead-end (or reach for raw DB access) to free a slot.
         if (failedPhases.some(p => /databases? reached|database (cap|limit)/i.test(p.summary))) {
             console.log('');
             console.log(muted('Free a slot under the account database cap:'));

package/dist/commands/page-inspect.js

@@ -4,6 +4,7 @@ import { formatSize } from '../utils.js';
 import { brand, bold, error as clrError, warning, muted, info } from '../colors.js';
 import { run } from '../helpers/index.js';
 import { capWaitMs } from './page-eval.js';
+import { TOUCH_DEVICES as INSPECT_DEVICES, resolveTouchDevice } from './page-screenshot.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
@@ -39,6 +40,7 @@ export const pageInspectCommand = new Command('inspect')
     .option('--no-truncate', 'Show full URLs instead of truncating long ones with middle-ellipsis')
     .option('--all', 'Include render-blocking, large resources, oversized images, overflow culprits, and LCP detail')
     .option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps run headlessly (audio is a built-in tone, not real speech)')
+    .option('--device <name>', `Inspect as a real touch device: ${INSPECT_DEVICES.join(', ')}. Emulates touch events, mobile user-agent and DPR, so a touch-gated mobile layout is what gets inspected.`)
     .option('--auth', 'Load the page signed in as you (your Gipity account), so pages behind a Sign-in-with-Gipity login are reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
     // Hidden redirect: agents reach for `page inspect --screenshot`. We don't take
     // an image here (`page screenshot` is the single path for that) — just point there.
@@ -60,6 +62,7 @@ export const pageInspectCommand = new Command('inspect')
             waitForSelector: opts.waitFor || undefined,
             waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
             fakeMedia: opts.fakeMedia || undefined,
+            device: opts.device ? resolveTouchDevice(opts.device) : undefined,
             auth: opts.auth || undefined,
         };
         const res = await post(`/tools/browser/inspect`, inspectBody);

package/dist/commands/page-screenshot.js

@@ -7,13 +7,20 @@ import { brand, bold, muted, success } from '../colors.js';
 import { formatSize } from '../utils.js';
 import { run } from '../helpers/index.js';
 import { withSpinner } from '../progress.js';
+/** `mobile` and `tablet` name a real handset/tablet rather than just a window size.
+ *  The server emulates it end to end - mobile user-agent, DPR, and crucially TOUCH,
+ *  so a page that gates its mobile UI on `'ontouchstart' in window` or
+ *  `navigator.maxTouchPoints` renders that UI instead of its desktop layout. The
+ *  dimensions here mirror the device's own metrics (reported in meta.json).
+ *  `device` values must be ones the server's BROWSER_DEVICES accepts. */
 const DEVICE_PRESETS = {
     default: { width: 1280, height: 720 },
     desktop: { width: 1920, height: 1080 },
     laptop: { width: 1366, height: 768 },
-    tablet: { width: 768, height: 1024, deviceScaleFactor: 2 },
-    mobile: { width: 390, height: 844, deviceScaleFactor: 3 },
+    tablet: { width: 820, height: 1180, deviceScaleFactor: 2, device: 'iPad' },
+    mobile: { width: 393, height: 852, deviceScaleFactor: 3, device: 'iPhone 15' },
 };
+const TOUCH_DEVICE_ALIASES = { mobile: 'iPhone 15', tablet: 'iPad' };
 const LABEL_WIDTH = 18; // "Screenshot dims:" + trailing space
 function label(text) {
     return muted((text + ':').padEnd(LABEL_WIDTH));
@@ -77,14 +84,43 @@ function parseViewportString(s) {
     }
     return dpr ? { width, height, deviceScaleFactor: dpr } : { width, height };
 }
+/** Device metrics for the exact server device names, so `--device "Pixel 9"` works
+ *  alongside the friendly `mobile`/`tablet` presets. Mirrors agent-browser's own
+ *  descriptors; the server re-applies them, these are for filenames + meta. */
+const EXACT_DEVICE_VIEWPORTS = {
+    'iPhone 15': { width: 393, height: 852, deviceScaleFactor: 3, device: 'iPhone 15' },
+    'iPhone 16': { width: 393, height: 852, deviceScaleFactor: 3, device: 'iPhone 16' },
+    'iPhone 16 Pro': { width: 402, height: 874, deviceScaleFactor: 3, device: 'iPhone 16 Pro' },
+    'iPhone 17': { width: 402, height: 874, deviceScaleFactor: 3, device: 'iPhone 17' },
+    'iPad': { width: 820, height: 1180, deviceScaleFactor: 2, device: 'iPad' },
+    'iPad Pro': { width: 1024, height: 1366, deviceScaleFactor: 2, device: 'iPad Pro' },
+    'Pixel 9': { width: 412, height: 923, deviceScaleFactor: 2.625, device: 'Pixel 9' },
+    'Galaxy S25': { width: 360, height: 800, deviceScaleFactor: 3, device: 'Galaxy S25' },
+};
+/** Emulatable devices the server accepts (its BROWSER_DEVICES). Shared with
+ *  `page inspect` so both commands take the same names. */
+export const TOUCH_DEVICES = Object.keys(EXACT_DEVICE_VIEWPORTS);
+/** Case-insensitively resolve a device name or `mobile`/`tablet` alias to a server
+ *  device name. Used by `page inspect`, which takes one device rather than viewports. */
+export function resolveTouchDevice(name) {
+    const key = name.trim().toLowerCase();
+    if (TOUCH_DEVICE_ALIASES[key])
+        return TOUCH_DEVICE_ALIASES[key];
+    const exact = TOUCH_DEVICES.find((d) => d.toLowerCase() === key);
+    if (exact)
+        return exact;
+    throw new Error(`Unknown --device: "${name}" (known: mobile, tablet, ${TOUCH_DEVICES.join(', ')})`);
+}
 function resolveDevice(name) {
     const key = name.trim().toLowerCase();
     const preset = DEVICE_PRESETS[key];
-    if (!preset) {
-        const available = Object.keys(DEVICE_PRESETS).join(', ');
-        throw new Error(`Unknown --device preset: "${name}" (known: ${available})`);
-    }
-    return preset;
+    if (preset)
+        return preset;
+    const exact = TOUCH_DEVICES.find((d) => d.toLowerCase() === key);
+    if (exact)
+        return EXACT_DEVICE_VIEWPORTS[exact];
+    const available = [...Object.keys(DEVICE_PRESETS), ...TOUCH_DEVICES].join(', ');
+    throw new Error(`Unknown --device preset: "${name}" (known: ${available})`);
 }
 function splitCsv(values) {
     if (!values || values.length === 0)
@@ -104,7 +140,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 after the post-load delay, then settles again before the shot.')
     .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('--device <names>', `Viewport preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag)`, appendOption, [])
+    .option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device — touch events, mobile user-agent, DPR — so touch-gated mobile UI actually renders.`, appendOption, [])
     .option('--viewport <dims>', 'Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag)', appendOption, [])
     .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 (audio is a built-in tone, not real speech)')
@@ -194,6 +230,8 @@ export const pageScreenshotCommand = new Command('screenshot')
                     width: s.viewport.width,
                     height: s.viewport.height,
                     device_scale_factor: s.viewport.deviceScaleFactor,
+                    ...(s.viewport.device ? { device: s.viewport.device } : {}),
+                    touch: !!s.viewport.touch,
                 },
                 width: s.width,
                 height: s.height,
@@ -215,6 +253,8 @@ export const pageScreenshotCommand = new Command('screenshot')
             console.log(`${label('Web page status')} ${meta.status}`);
         if (meta.performance)
             console.log(`${label('Web page perf')} ${fmtPerformance(meta.performance)}`);
+        if (s.viewport.device)
+            console.log(`${label('Emulated device')} ${s.viewport.device} ${muted('(touch events, mobile user-agent)')}`);
         const sizePart = formatSize(s.screenshotSizeBytes) + (meta.full ? ' (full page)' : '');
         console.log(`${label('Screenshot size')} ${sizePart}`);
         if (s.width && s.height)
@@ -234,7 +274,8 @@ export const pageScreenshotCommand = new Command('screenshot')
     for (let i = 0; i < meta.screenshots.length; i++) {
         const s = meta.screenshots[i];
         const dims = `${s.viewport.width}×${s.viewport.height}${s.viewport.deviceScaleFactor > 1 ? ` @${s.viewport.deviceScaleFactor}x` : ''}`;
-        console.log(`\n${brand('@ ' + dims)}`);
+        const deviceTag = s.viewport.device ? muted(` — ${s.viewport.device}, touch`) : '';
+        console.log(`\n${brand('@ ' + dims)}${deviceTag}`);
         const sizePart = formatSize(s.screenshotSizeBytes) + (meta.full ? ' (full page)' : '');
         console.log(`${label('Screenshot size')} ${sizePart}`);
         if (s.width && s.height)

package/dist/commands/sandbox.js

@@ -2,7 +2,8 @@ import { Command } from 'commander';
 import { readFileSync, existsSync, statSync } from 'fs';
 import { dirname, extname, relative } from 'path';
 import { post } from '../api.js';
-import { resolveProjectContext, getConfigPath } from '../config.js';
+import { resolveProjectContext, getConfigPath, shouldIgnore } from '../config.js';
+import { SCRATCH_IGNORE } from '../setup.js';
 import { sync } from '../sync.js';
 import { error as clrError, dim } from '../colors.js';
 import { run } from '../helpers/index.js';
@@ -28,6 +29,81 @@ const INTERPRETERS = {
     bash: 'bash',
     sh: 'bash',
 };
+/** The three ways to pin a language, shown whenever none was pinned. */
+const PIN_LANGUAGE_HELP = [
+    '  gipity sandbox run bash "<code>"            # interpreter token (bash | python | node)',
+    '  gipity sandbox run --language bash "<code>" # explicit flag (js | py | bash)',
+    '  gipity sandbox run --file script.sh         # inferred from the file extension',
+].join('\n');
+/**
+ * Resolve the language from an explicit signal, or exit.
+ *
+ * Precedence: interpreter token > --language > --file extension.
+ *
+ * There is no default. js/python/bash are mutually exclusive, and plenty of
+ * snippets parse as more than one of them (`x = 1`, `a[0]`, `foo()`), so any
+ * default silently runs some fraction of input in the wrong interpreter. The old
+ * behavior defaulted to JavaScript, which meant a shell one-liner ran as JS and
+ * died with a Node `SyntaxError` at `/work/_run.js` - after paying for a project
+ * sync and a server round trip. Failing here instead costs nothing and says what
+ * to type. (`docs/skills/sandbox-tools.md` used to carry a hand-written "always
+ * pin the language" warning to work around this; the CLI enforces it now.)
+ */
+export function resolveLanguage(opts) {
+    const explicit = opts.langFromInterp
+        ?? (opts.langOpt ? LANG_MAP[opts.langOpt.toLowerCase()] ?? opts.langOpt : undefined);
+    if (explicit && !['javascript', 'python', 'bash'].includes(explicit)) {
+        console.error(clrError(`Invalid language: ${opts.langOpt}. Use: js, py, or bash`));
+        process.exit(1);
+    }
+    if (explicit)
+        return explicit;
+    const fromExt = opts.filePath
+        ? LANG_MAP[extname(opts.filePath).slice(1).toLowerCase()]
+        : undefined;
+    if (fromExt)
+        return fromExt;
+    if (opts.filePath) {
+        console.error(clrError(`Cannot infer the language of ${opts.filePath} from its extension (expected .js, .py, or .sh).`));
+        console.error(dim(`Pass --language explicitly:\n  gipity sandbox run --language py --file ${opts.filePath}`));
+        process.exit(1);
+    }
+    console.error(clrError('No language specified for inline code.'));
+    console.error(dim(`Pin it one of three ways:\n${PIN_LANGUAGE_HELP}`));
+    process.exit(1);
+}
+/** Truncate one arg for echoing back, so a 2 KB fragment doesn't flood the terminal. */
+function preview(arg) {
+    const flat = arg.replace(/\s+/g, ' ').trim();
+    return flat.length > 60 ? `${flat.slice(0, 57)}...` : flat;
+}
+/**
+ * Inline code arrived as several positional args, which means the caller's shell
+ * split it before the CLI ever saw it. The old message ("Unrecognized
+ * invocation") just restated the rules and left the caller to guess which one it
+ * broke - an agent that hits this typically retries the same mangled quoting.
+ *
+ * So: show the fragments we actually received (the split point is the evidence),
+ * then name the usual cause. On PowerShell a double-quoted string interpolates
+ * `$(...)` and backslash is NOT an escape character, so a POSIX-style
+ * `"... $(cmd) ... \"$f\" ..."` one-liner both runs `cmd` locally and terminates
+ * the string early at `\"`. That is exactly how one quoted arg becomes many.
+ */
+function explainSplitArgs(args) {
+    const looksInterpolated = args.some(a => a.includes('$(') || a.includes('`'));
+    const lines = [
+        clrError(`Inline code must be a single argument, but ${args.length} were received:`),
+        ...args.slice(0, 4).map((a, i) => dim(`  ${i + 1}: ${preview(a)}`)),
+        ...(args.length > 4 ? [dim(`  ... and ${args.length - 4} more`)] : []),
+        '',
+        'Your shell split the code before the CLI saw it.',
+    ];
+    if (looksInterpolated) {
+        lines.push(dim('In PowerShell a double-quoted string interpolates $(...), and backslash does not'), dim('escape a quote - so a POSIX one-liner runs its subshell locally and ends early.'));
+    }
+    lines.push('', 'Fix, in order of preference:', dim('  1. Put the code in a file (best for anything with quotes, $(...), or newlines):'), '       gipity sandbox run --file script.sh', dim('  2. Use the interpreter shorthand on a file:'), '       gipity sandbox run bash script.sh', dim('  3. Keep it inline, but as ONE argument your shell will not split:'), "       gipity sandbox run --language bash 'echo hi'");
+    return lines.join('\n');
+}
 /** Project-relative path from the process cwd, or undefined when there's
  *  no local config (one-off mode) or the cwd is at/above the project root. */
 function resolveRelativeCwd() {
@@ -45,7 +121,11 @@ export const sandboxCommand = new Command('sandbox')
 sandboxCommand
     .command('run [args...]')
     .description('Run code')
-    .option('--language <language>', 'Language: js, py, or bash', 'js')
+    // No default. js/python/bash are mutually exclusive and the same snippet can
+    // parse as more than one of them, so an implicit default silently runs code in
+    // the wrong interpreter. Every invocation must pin the language via this flag,
+    // an interpreter token, or a --file extension - see resolveLanguage().
+    .option('--language <language>', 'Language: js, py, or bash (required unless pinned by an interpreter token or --file extension)')
     .option('--file <path>', 'Read the code body from a file instead of the inline <code> arg; --language is inferred from the extension when not given')
     .option('--timeout <seconds>', 'Execution timeout in seconds', '30')
     .option('--input <path>', 'Narrow to specific project files instead of auto-mirroring the whole tree (repeatable). Use this only for >1 GB projects or when you want surgical control.', (v, prev) => [...(prev ?? []), v])
@@ -89,8 +169,12 @@ Pre-installed: Python (pandas, numpy, matplotlib, Pillow, scipy, bs4),
 CLI tools (ImageMagick, FFmpeg, webp/cwebp, optipng, jq, pandoc, exiftool,
 GCC/Rust).
 `)
-    .action((args = [], opts, command) => run('Sandbox', async () => {
-    const { config } = await resolveProjectContext();
+    .action((args = [], opts) => run('Sandbox', async () => {
+    // Everything below this point is pure argument validation - it reads the local
+    // filesystem and nothing else. It runs BEFORE resolveProjectContext() so a
+    // malformed invocation fails on the spot instead of first paying a project
+    // lookup (and printing a misleading "→ (project: …)" banner) only to reject
+    // the args a moment later.
     // Resolve the positional args into either inline code or a script-file path.
     // `run <interpreter> <file>` (e.g. `run python build_report.py`) is the natural
     // mental model, so accept it: a leading interpreter token + a path becomes
@@ -112,7 +196,7 @@ GCC/Rust).
         inlineCode = args[0];
     }
     else if (args.length > 1) {
-        console.error(clrError('Unrecognized invocation. Pass inline code as a single quoted arg, a script with --file <path>, or use the `run <python|node|bash> <file>` shorthand.'));
+        console.error(explainSplitArgs(args));
         process.exit(1);
     }
     if (inlineCode !== undefined && filePath) {
@@ -133,30 +217,32 @@ GCC/Rust).
             process.exit(1);
         }
     }
-    // Language precedence: interpreter token > file extension (unless --language
-    // was passed explicitly) > the --language value (default js).
-    const fromExt = filePath && !langFromInterp && command.getOptionValueSource('language') === 'default'
-        ? LANG_MAP[extname(filePath).slice(1).toLowerCase()]
-        : undefined;
-    const language = langFromInterp || fromExt || LANG_MAP[opts.language] || opts.language;
-    // True when the run fell back to the implicit JS default - nothing in the
-    // command shape pinned a language. Used to explain the execution mode if a
-    // shell/Python snippet gets parsed as JavaScript and blows up (see hint below).
-    const usedDefaultJs = !langFromInterp
-        && command.getOptionValueSource('language') === 'default'
-        && language === 'javascript';
-    if (!['javascript', 'python', 'bash'].includes(language)) {
-        console.error(clrError(`Invalid language: ${opts.language}. Use: js, py, or bash`));
-        process.exit(1);
-    }
+    // Language precedence: interpreter token > --language > file extension.
+    // There is deliberately no fallback: resolveLanguage() exits when nothing
+    // pinned one, rather than guessing. This runs BEFORE the project sync and the
+    // server round trip below, so a missing language costs nothing but the message.
+    const language = resolveLanguage({ langFromInterp, langOpt: opts.language, filePath });
+    // Args are good - now it's worth resolving (and announcing) the project.
+    const { config } = await resolveProjectContext();
     const timeout = parseInt(opts.timeout, 10);
     const cwd = resolveRelativeCwd();
+    // A scratch path is never synced, so it can never reach the VFS the sandbox
+    // mirrors from - `--input tmp/frame.png` would fail inside the container with
+    // a bare "no such file". Catch it here, where we can say why.
+    const scratchInputs = (opts.input ?? []).filter((p) => shouldIgnore(p.replace(/\\/g, '/').replace(/^\.\//, ''), SCRATCH_IGNORE));
+    if (scratchInputs.length) {
+        console.error(clrError(`Scratch paths are never mirrored into the sandbox: ${scratchInputs.join(', ')}`));
+        console.error(dim(`  ${SCRATCH_IGNORE.join(', ')} are ignored by sync, so the sandbox never sees them.`));
+        console.error(dim('  Stage inputs at a real project path (src/, docs/, assets/) and delete them afterward.'));
+        process.exit(1);
+    }
     // Push local working-tree changes up before executing. The sandbox mirrors
     // the *server* (VFS), not the local cwd, so any input staged outside Claude's
     // Write/Edit auto-push hook - a Bash `cp`/`ffmpeg`/redirect, or any external
     // 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").
+    // local state however files got there - with the one exception of the scratch
+    // namespaces above, which sync ignores and so the mirror never carries.
     // 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()) {
@@ -207,12 +293,8 @@ GCC/Rust).
                 console.log(`${f}`);
         }
         if (res.data.exitCode !== 0) {
-            // A SyntaxError / CJS-loader trace under the implicit JS default almost
-            // always means the input was shell or Python that got run as JavaScript.
-            // The raw Node stack trace never says which mode ran, so name it.
-            if (usedDefaultJs && /SyntaxError|cjs\/loader|wrapSafe/.test(res.data.stderr || '')) {
-                console.error(dim('Hint: ran as JavaScript (the default). For a shell command pass `--language bash` (or `gipity sandbox run bash "<cmd>"`); for Python pass `--language py`.'));
-            }
+            // No "did you mean another language?" hint is needed: the language is now
+            // always something the caller pinned, never a silent default we chose.
             process.exit(res.data.exitCode);
         }
     }

package/dist/commands/storage.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { get, patch } from '../api.js';
-import { brand, muted } from '../colors.js';
+import { formatBytes } from '../adopt-cwd.js';
+import { bold, brand, muted, warning } from '../colors.js';
 import { run } from '../helpers/index.js';
 /** Parse a CLI flag value as a positive whole number, or throw a friendly error.
  *  The server is the source of truth for the plan-cap bound; this just rejects
@@ -22,8 +23,62 @@ function printRetention(d, updated) {
     console.log(`  ${muted(`days: ${daysNote}, copies: ${countNote}`)}`);
     console.log(muted(`Plan allows up to ${d.maxDays} days / ${d.maxCount} copies.`));
 }
+function row(label, value, note = '') {
+    console.log(`  ${label.padEnd(16)} ${value.padStart(10)}${note ? `  ${muted(note)}` : ''}`);
+}
+function printUsage(d) {
+    const over = d.usedBytes > d.quotaBytes;
+    const pct = d.quotaBytes > 0 ? Math.round((d.usedBytes / d.quotaBytes) * 100) : 0;
+    const headline = `${formatBytes(d.usedBytes)} of ${formatBytes(d.quotaBytes)} used (${pct}%)`;
+    console.log(`Storage: ${over ? warning(headline) : brand(headline)}`);
+    console.log('');
+    const s = d.storage;
+    row('Live files', formatBytes(s.liveBytes), `${s.liveFiles.toLocaleString()} files`);
+    row('All versions', formatBytes(s.versionedBytes), `${s.versionCount.toLocaleString()} versions`);
+    row('Dedup saved', formatBytes(s.dedupSavedBytes), `${s.dedupedObjects.toLocaleString()} shared`);
+    row('Billed', formatBytes(s.physicalBytes), 'versions kept, dedup applied');
+    if (d.projects.length > 0) {
+        // The server returns only the biggest projects. Say so, and account for the
+        // rest - a list that looks exhaustive but isn't sends people hunting for
+        // space in the wrong place.
+        const totals = d.projectTotals;
+        const hidden = totals.count - d.projects.length;
+        console.log('');
+        const scope = hidden > 0
+            ? `(top ${d.projects.length} of ${totals.count.toLocaleString()}, live files only)`
+            : '(live files only)';
+        console.log(`${bold('By project')} ${muted(scope)}`);
+        for (const p of d.projects) {
+            const name = p.projectName ?? '(no project)';
+            row(name.length > 16 ? `${name.slice(0, 15)}…` : name, formatBytes(p.liveBytes), `${p.liveFiles.toLocaleString()} files`);
+        }
+        if (hidden > 0) {
+            const shownBytes = d.projects.reduce((n, p) => n + p.liveBytes, 0);
+            const shownFiles = d.projects.reduce((n, p) => n + p.liveFiles, 0);
+            row(`…and ${hidden.toLocaleString()} more`, formatBytes(totals.liveBytes - shownBytes), `${(totals.liveFiles - shownFiles).toLocaleString()} files`);
+        }
+    }
+    const r = d.versionRetention;
+    console.log('');
+    console.log(muted(`Version retention: ${r.days} days / ${r.count} copies (plan allows up to ${r.maxDays} / ${r.maxCount}).`));
+    if (over) {
+        console.log(warning('Over quota. Delete files you no longer need, or keep less history with `gipity storage retention`.'));
+    }
+}
 export const storageCommand = new Command('storage')
     .description('Manage file storage settings');
+storageCommand
+    .command('usage')
+    .description('Show what is using your storage, per project and live vs. version history')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Usage', async () => {
+    const res = await get('/users/me/storage');
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    printUsage(res.data);
+}));
 storageCommand
     .command('retention')
     .description('View or adjust your file version-retention policy')

package/dist/knowledge.js

@@ -154,7 +154,7 @@ To keep local-only material (research clones, scratch data, vendored references)
 Deploy is opt-in, not opt-out: the \`files\` phase uploads **only** what's under \`src/\` (plus \`functions/\` and \`migrations/\` as backend, not CDN files). Anything else at the project root is kept but never deployed. Put each kind of file in the right bucket so scratch and reference material can't bloat a deploy:
 
 - **\`src/\`** - the app itself. Synced **and** deployed to the CDN. Only app code, assets, and pages belong here.
-- **\`tmp/\`** - ephemeral scratch: file conversions, intermediate outputs, design staging. **Already ignored** (never synced, never deployed) - the one place to do throwaway work. Use this single root. (\`*_tmp/\` dirs and \`.gipityscratch/\` are auto-ignored too, as a safety net, so legacy scattered scratch like \`_vsd_tmp/\` can't leak - but write new scratch to \`tmp/\`, not scattered dirs.)
+- **\`tmp/\`** - ephemeral scratch: file conversions, intermediate outputs, design staging. **Already ignored** (never synced, never deployed) - the one place to do throwaway work. Use this single root. (\`*_tmp/\` dirs and \`.gipityscratch/\` are auto-ignored too, as a safety net, so legacy scattered scratch like \`_vsd_tmp/\` can't leak - but write new scratch to \`tmp/\`, not scattered dirs.) Because it never syncs, \`tmp/\` is also never mirrored into the sandbox: **don't stage \`gipity sandbox run\` inputs here** - the sandbox won't see them. Stage inputs under \`src/\`/\`docs/\` and delete them after.
 - **\`docs/\`** - reference material you want to keep: UI/architecture diagrams, design decks, notes, ADRs. Synced and versioned on the server (backed up, rollback-able) but **never deployed**, because it's outside \`src/\`. This is the home for "keep forever, don't ship" artifacts.
 - **\`tests/\`** - \`*.test.js\` suites. Synced, run by \`gipity test\`, never deployed. \`gipity test list [path]\` lists the test files (and what a filter selects) without running them.
 

package/dist/sync.js

@@ -1179,6 +1179,9 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
     // turns "files we failed to fetch" into "delete those files." Skip ALL deletes
     // this run and let a clean sync replan them once the pull succeeds.
     let deletesSkippedIncomplete = 0;
+    // Directories that lost a file to a delete-local this run. Only these are
+    // candidates for empty-dir cleanup — see cleanupEmptyDirs.
+    const dirsTouchedByDelete = new Set();
     for (const a of plannedToApply) {
         if (downloadIncomplete && (a.kind === 'delete-local' || a.kind === 'delete-remote')) {
             deletesSkippedIncomplete++;
@@ -1199,11 +1202,13 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
             }
             try {
                 unlinkSync(full);
+                dirsTouchedByDelete.add(dirname(full));
                 delete baseline.files[a.path];
                 applied++;
             }
             catch (err) {
                 if (err.code === 'ENOENT') {
+                    dirsTouchedByDelete.add(dirname(full));
                     delete baseline.files[a.path];
                     applied++;
                 }
@@ -1273,8 +1278,8 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
         errors.push(`Skipped ${deletesSkippedIncomplete} deletion${deletesSkippedIncomplete === 1 ? '' : 's'} because the download was incomplete - ` +
             `nothing was deleted. Re-run \`gipity sync\` once the pull finishes to apply any real deletions.`);
     }
-    // Clean up empty local directories after delete-local actions.
-    cleanupEmptyDirs(root, config.ignore);
+    // Clean up local directories emptied by this run's delete-local actions.
+    cleanupEmptyDirs(root, dirsTouchedByDelete);
     // Adopt agreed content-match state into the baseline, and prune stale entries.
     // `plan()` is pure, so it emits these as lists and the mutation happens here.
     // Adopting (FIX M1) makes sync convergent - a locally+remotely-identical file
@@ -1296,43 +1301,51 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
         deferredDeletes: skippedByGuard,
     };
 }
-function cleanupEmptyDirs(root, ignorePatterns) {
-    function walk(dir) {
-        let entries;
+/**
+ * Remove directories that THIS run's delete-local actions left empty.
+ *
+ * Scoped to `emptiedDirs` on purpose. The previous version walked the whole
+ * project tree and removed every empty directory it found, which also deleted
+ * ones the user had just created: `mkdir -p src/images/monsters` followed a few
+ * tool calls later by a write into it failed with ENOENT, because a full sync
+ * had pruned the directory in between. The VFS stores files only, so a freshly
+ * created empty directory has no remote counterpart and looked indistinguishable
+ * from "deleted on the server."
+ *
+ * Pruning only where sync actually removed a file preserves the original intent
+ * — don't leave an empty husk behind after a remote delete — while leaving every
+ * other directory alone. An unrelated empty directory is now simply never
+ * sync's business.
+ *
+ * Prunes upward, since removing `a/b/c` can leave `a/b` empty too. A directory
+ * holding only sync-ignored entries is not empty on disk, so it survives — the
+ * same outcome the old ignore-aware walk produced.
+ */
+function cleanupEmptyDirs(root, emptiedDirs) {
+    const isEmpty = (dir) => {
         try {
-            entries = readdirSync(dir, { withFileTypes: true });
+            return readdirSync(dir).length === 0;
         }
         catch {
             return false;
         }
-        let kept = 0;
-        for (const entry of entries) {
-            const full = join(dir, entry.name);
-            const rel = relative(root, full).replace(/\\/g, '/');
-            if (shouldIgnore(rel, ignorePatterns)) {
-                kept++;
-                continue;
-            }
-            if (entry.isDirectory()) {
-                if (!walk(full))
-                    kept++;
-            }
-            else {
-                kept++;
-            }
-        }
-        if (kept === 0 && dir !== root) {
+    };
+    // `emptiedDirs` holds dirname()s of resolveInRoot() results, which are
+    // lexically resolved — resolve the root the same way, or the containment
+    // guard below never matches and nothing is ever pruned.
+    const rootResolved = resolve(root);
+    for (const start of emptiedDirs) {
+        let dir = resolve(start);
+        while (dir !== rootResolved && dir.startsWith(rootResolved + sep) && isEmpty(dir)) {
             try {
                 rmdirSync(dir);
-                return true;
             }
             catch {
-                return false;
+                break;
             }
+            dir = dirname(dir);
         }
-        return false;
     }
-    walk(root);
 }
 // ─── Single-file push (used by `gipity push <file>`) ───────────
 export async function pushFile(filePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.419",
+  "version": "1.0.422",
   "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",