gipity 1.0.401 → 1.0.403

package/dist/api.js

@@ -17,6 +17,28 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+// Bound every network call so a wedged connection becomes a clear error instead
+// of an unbounded hang (the "sync gets stuck forever" bug). JSON API calls must
+// finish well within REQUEST_TIMEOUT_MS; the S3 PUT path keeps its own
+// size-based timeout. Streaming downloads can't use a single total cap (a large
+// but healthy tree would be cut off mid-stream), so downloadStream bounds only
+// the time-to-first-byte here and an idle watchdog in sync.ts guards the body.
+const REQUEST_TIMEOUT_MS = 60_000;
+const DOWNLOAD_HEADER_TIMEOUT_MS = 30_000;
+/** fetch() that rejects with a clean 408 ApiError if the whole exchange (headers
+ *  + body) doesn't complete within timeoutMs, instead of hanging forever. For
+ *  request/response JSON calls only - never wrap a long streaming body in this. */
+async function fetchWithTimeout(url, init, timeoutMs, label) {
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (e) {
+        if (e?.name === 'TimeoutError' || e?.name === 'AbortError') {
+            throw new ApiError(408, 'REQUEST_TIMEOUT', `${label} timed out after ${Math.round(timeoutMs / 1000)}s`);
+        }
+        throw e;
+    }
+}
 /** 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
@@ -55,11 +77,11 @@ export async function getAuthHeader() {
 async function request(method, path, body) {
     const headers = await getHeaders();
     const url = `${baseUrl()}${path}`;
-    const res = await fetch(url, {
+    const res = await fetchWithTimeout(url, {
         method,
         headers,
         body: body ? JSON.stringify(body) : undefined,
-    });
+    }, REQUEST_TIMEOUT_MS, `${method} ${path}`);
     if (!res.ok) {
         const json = await res.json().catch(() => ({ error: { code: 'UNKNOWN', message: res.statusText } }));
         const err = json.error || { code: 'UNKNOWN', message: res.statusText };
@@ -150,14 +172,45 @@ export async function download(path) {
 export async function downloadStream(path) {
     const { Readable } = await import('stream');
     const url = `${baseUrl()}${path}`;
-    const res = await fetch(url, {
-        headers: { ...clientHeaders(), 'Authorization': `Bearer ${await bearerToken()}` },
-    });
+    // Bound time-to-first-byte only: abort if no RESPONSE within the header window,
+    // then clear the timer so the (possibly large) body streams without a total cap.
+    // The body is guarded by an idle watchdog at the call site (sync.ts), which
+    // destroys this stream - cancelling the fetch - if bytes stop flowing.
+    const ac = new AbortController();
+    const headerTimer = setTimeout(() => ac.abort(), DOWNLOAD_HEADER_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { ...clientHeaders(), 'Authorization': `Bearer ${await bearerToken()}` },
+            signal: ac.signal,
+        });
+    }
+    catch (e) {
+        if (ac.signal.aborted) {
+            throw new ApiError(408, 'DOWNLOAD_TIMEOUT', `Download did not respond within ${DOWNLOAD_HEADER_TIMEOUT_MS / 1000}s`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(headerTimer);
+    }
     if (!res.ok) {
         throw new ApiError(res.status, 'DOWNLOAD_ERROR', `Download failed: ${res.statusText}`);
     }
     return Readable.fromWeb(res.body);
 }
+// A presigned PUT has no built-in deadline: `fetch` will wait forever if S3
+// accepts the connection then stalls mid-body. That can't surface as a retry
+// (a hang never throws), so one stalled PUT wedges an entire deploy/sync while
+// it holds the project lock. Bound every PUT with a throughput-scaled deadline:
+// a generous floor for tiny files plus time for the body at a conservative
+// assumed-minimum rate, so a genuinely-progressing large upload survives but a
+// true stall aborts and lets withRetry() retry it.
+const PUT_TIMEOUT_FLOOR_MS = 120_000; // 2 min minimum, regardless of size
+const PUT_MIN_BYTES_PER_SEC = 256 * 1024; // assume the link sustains ≥256 KB/s
+export function putTimeoutMs(contentLength) {
+    return Math.max(PUT_TIMEOUT_FLOOR_MS, Math.ceil(contentLength / PUT_MIN_BYTES_PER_SEC) * 1000);
+}
 /**
  * PUT raw bytes to a presigned URL (no auth header - the URL is signed).
  * Supports a Buffer or a Readable stream body. Returns the response ETag header
@@ -174,12 +227,25 @@ export async function putToPresignedUrl(url, body, contentLength, contentType) {
     const fetchBody = isStream
         ? Readable.toWeb(body)
         : new Uint8Array(body);
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers,
-        body: fetchBody,
-        ...(isStream ? { duplex: 'half' } : {}),
-    });
+    const timeoutMs = putTimeoutMs(contentLength);
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'PUT',
+            headers,
+            body: fetchBody,
+            signal: AbortSignal.timeout(timeoutMs),
+            ...(isStream ? { duplex: 'half' } : {}),
+        });
+    }
+    catch (err) {
+        // A timeout aborts with a TimeoutError/AbortError. Surface it as a 408 so
+        // withRetry() treats it as transient and retries the PUT.
+        if (err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+            throw new ApiError(408, 'S3_UPLOAD_TIMEOUT', `S3 PUT stalled (no completion in ${Math.round(timeoutMs / 1000)}s)`);
+        }
+        throw err;
+    }
     if (!res.ok) {
         const text = await res.text().catch(() => res.statusText);
         throw new ApiError(res.status, 'S3_UPLOAD', `S3 PUT failed: ${res.status} ${text.slice(0, 200)}`);

package/dist/auth.js

@@ -70,6 +70,24 @@ export function sessionExpired() {
         return false; // undecodable - let the refresh path decide
     return Date.now() > exp * 1000;
 }
+/** True when the access token is currently past its expiry. Unlike
+ *  sessionExpired() (which only inspects the refresh token's lifetime), this
+ *  reflects whether the NEXT authenticated request can actually succeed right
+ *  now. Meaningful only when read AFTER refreshTokenIfNeeded(): a normal
+ *  expired access token gets silently renewed, so a token that is STILL expired
+ *  after a refresh attempt means the renewal failed — the refresh token was
+ *  rejected (genuinely lapsed, or rotated away by a sibling process sharing this
+ *  auth.json) — and re-login is required. Used to keep the up-front "Logged in"
+ *  message from contradicting a 401 on the very next call. */
+export function accessTokenExpired() {
+    const auth = getAuth();
+    if (!auth)
+        return true;
+    const t = new Date(auth.expiresAt).getTime();
+    if (isNaN(t))
+        return false; // unparseable - let the live 401 path decide
+    return Date.now() >= t;
+}
 const delay = (ms) => new Promise(r => setTimeout(r, ms));
 // ─── Cross-process refresh lock ────────────────────────────────
 // Serializes token refreshes across every `gipity` process that shares this

package/dist/commands/claude.js

@@ -5,7 +5,7 @@ import { spawn } from 'child_process';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { resolveCommand } from '../platform.js';
-import { getAuth, saveAuth, sessionExpired } from '../auth.js';
+import { getAuth, saveAuth, sessionExpired, accessTokenExpired, refreshTokenIfNeeded } from '../auth.js';
 import { get, post, publicPost, ApiError, getAccountSlug } from '../api.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, DEFAULT_API_BASE, getConfigPath } from '../config.js';
 import { sync } from '../sync.js';
@@ -307,11 +307,35 @@ export const claudeCommand = new Command('claude')
         if (!nonInteractive) {
             printBanner({ version: __clPkg.version, email: auth?.email, cwd: process.cwd() });
         }
-        if (auth && sessionExpired()) {
-            // The cached auth.json exists but its refresh token has lapsed, so the
-            // first API call below would 401 anyway. Re-login up front instead of
-            // printing "Logged in" and immediately contradicting it with "session
-            // expired" once the projects fetch fails.
+        // A GIPITY_TOKEN env token authenticates every request on its own, so the
+        // saved session's expiry is irrelevant when one is set — never re-login or
+        // warn about expiry in that case.
+        const hasEnvToken = Boolean(process.env.GIPITY_TOKEN?.trim());
+        // For an interactive saved-session run, renew the access token UP FRONT so
+        // the login line we're about to print is actually true. A saved session
+        // can look valid locally (refresh token not past its JWT expiry, so
+        // sessionExpired() is false) yet be dead on the server — most often because
+        // a sibling process sharing this auth.json already consumed the single-use
+        // refresh token (GipRunner runs many gipity processes against one auth dir).
+        // refreshTokenIfNeeded() attempts the rotation here; if it fails, the
+        // access token stays expired and accessTokenExpired() catches it below.
+        if (auth && !hasEnvToken && !nonInteractive && !sessionExpired()) {
+            await refreshTokenIfNeeded();
+            auth = getAuth();
+        }
+        // Re-login is genuinely required when the refresh token has lapsed, OR the
+        // proactive renewal above could not produce a still-valid access token
+        // (refresh token rejected/rotated away). The access-token check is gated to
+        // interactive runs: headless runs can't prompt, and their downstream API
+        // call renews the token itself. Never triggered while a GIPITY_TOKEN env
+        // token is supplying auth.
+        const reloginRequired = auth != null && !hasEnvToken &&
+            (sessionExpired() || (!nonInteractive && accessTokenExpired()));
+        if (auth && reloginRequired) {
+            // The saved session is dead (refresh token lapsed, or rotated away by a
+            // sibling process), so the first API call below would 401. Re-login up
+            // front instead of printing "Logged in" and immediately contradicting it
+            // with "session expired" once the projects fetch fails.
             console.log(`  ${muted('Your session expired. Let\'s sign you back in.')}\n`);
             auth = await interactiveLogin();
         }

package/dist/commands/page-eval.js

@@ -148,6 +148,7 @@ export const pageEvalCommand = new Command('eval')
     .option('--wait <ms>', 'Sleep this many ms after DOMContentLoaded before evaluating (lets late async work settle; max 30000)', '500')
     .option('--wait-for <selector>', 'Wait until this CSS selector appears before evaluating (deterministic; replaces --wait)')
     .option('--wait-timeout <ms>', 'Max ms to wait for --wait-for before giving up', '5000')
+    .option('--auth', 'Evaluate signed in as you (your Gipity account), so a page behind a Sign-in-with-Gipity login is reachable. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
     .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
@@ -205,6 +206,7 @@ export const pageEvalCommand = new Command('eval')
             url, expr: sentExpr, waitMs,
             waitForSelector: opts.waitFor || undefined,
             waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
+            auth: opts.auth || undefined,
         });
         const d = await pollEvalResult(kickoff.data.evalJobId, waitMs);
         const { result, noValue } = normalizeEvalResult(d.result);

package/dist/commands/page-inspect.js

@@ -39,6 +39,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('--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.
     .addOption(new Option('--screenshot [path]', 'Capture a screenshot').hideHelp())
@@ -59,6 +60,7 @@ export const pageInspectCommand = new Command('inspect')
             waitForSelector: opts.waitFor || undefined,
             waitForTimeoutMs: opts.waitFor ? waitForTimeoutMs : undefined,
             fakeMedia: opts.fakeMedia || undefined,
+            auth: opts.auth || undefined,
         };
         const res = await post(`/tools/browser/inspect`, inspectBody);
         const b = res.data;

package/dist/commands/page-screenshot.js

@@ -108,6 +108,7 @@ export const pageScreenshotCommand = new Command('screenshot')
     .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)')
+    .option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai.')
     .option('--json', 'Output JSON metadata instead of a friendly summary')
     .addOption(new Option('--wait <ms>', 'Alias for --post-load-delay').hideHelp())
     // `--full-page` is the Puppeteer/Playwright name for this (their `fullPage`),
@@ -142,6 +143,7 @@ export const pageScreenshotCommand = new Command('screenshot')
         reloadBetween: opts.reloadBetween !== false,
         ...(userSpecifiedViewports ? { viewports: customViewports } : {}),
         ...(opts.fakeMedia ? { fakeMedia: true } : {}),
+        ...(opts.auth ? { auth: true } : {}),
         ...(opts.action ? { action: opts.action } : {}),
     };
     // Load + render across viewports runs server-side and can take many

package/dist/commands/test.js

@@ -231,6 +231,47 @@ testCommand
         }
     }
 }));
+// ── List subcommand (show test files without running) ─────────────────
+testCommand
+    .command('list')
+    .description('List the test files that would run — no run, optional path filter')
+    .argument('[path]', 'Test path filter (e.g. "api", "e2e/portal")')
+    .option('--json', 'Output as JSON')
+    // optsWithGlobals: see the status subcommand — `--json` lands on the parent.
+    .action((pathFilter, _o, command) => run('List', async () => {
+    const opts = command.optsWithGlobals();
+    const config = requireConfig();
+    const qs = pathFilter ? `?filterPath=${encodeURIComponent(pathFilter)}` : '';
+    const res = await get(`/projects/${config.projectGuid}/test/list${qs}`);
+    const { files, total } = res.data;
+    if (opts.json) {
+        console.log(JSON.stringify(res.data, null, 2));
+        return;
+    }
+    if (total === 0) {
+        console.log(muted(pathFilter
+            ? `No test files matched filter: ${pathFilter}`
+            : 'No test files found. Add *.test.js files under tests/.'));
+        return;
+    }
+    console.log(bold(`Test files${pathFilter ? ` (filter: ${pathFilter})` : ''}: ${total}`));
+    console.log('');
+    // Group by directory so the layout mirrors `gipity test` run output.
+    const groups = new Map();
+    for (const f of files) {
+        const key = f.path || '(root)';
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(f.name);
+    }
+    for (const [dir, names] of groups) {
+        console.log(`  ${dim(dir)}`);
+        for (const name of names)
+            console.log(`    ${name}`);
+    }
+    console.log('');
+    console.log(muted(`Run them: gipity test${pathFilter ? ` ${pathFilter}` : ''}`));
+}));
 // ── History subcommand ─────────────────────────────────────────────────
 testCommand
     .command('history')

package/dist/commands/uninstall.js

@@ -181,6 +181,6 @@ export const uninstallCommand = new Command('uninstall')
     }
     console.log('');
     console.log(`${success('Uninstall complete.')} ${dim('Run')} ${brand('npm uninstall -g gipity')} ${dim('to remove the binary too.')}`);
-    console.log(`${dim('Then run')} ${brand('hash -r')} ${dim('(or open a new shell) so bash forgets the old binary path.')}`);
+    console.log(`${dim('Then run')} ${brand('hash -r')} ${dim('(or open a new shell) - your shell caches the old binary path, and a reinstall may place it elsewhere.')}`);
 });
 //# sourceMappingURL=uninstall.js.map

package/dist/flag-aliases.js

@@ -24,6 +24,7 @@ export const FLAG_ALIASES = {
     '--ratio': '--aspect-ratio',
     '--res': '--resolution',
     '--desc': '--description',
+    '--body': '--data',
     '--src': '--source-dir',
     '--srcdir': '--source-dir',
     '--parallel': '--concurrency',

package/dist/hooks/capture-runner.js

@@ -23,7 +23,7 @@
  *   - Anything unexpected (parse error, network error, etc.). We must
  *     not break the user's interactive session.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, openSync, closeSync, createReadStream, } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, openSync, closeSync, statSync, utimesSync, createReadStream, } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { getDevice } from '../relay/state.js';
@@ -74,33 +74,90 @@ function deleteState(convGuid) {
     }
     catch { /* already gone */ }
 }
-/** Simple exclusive file-lock via `wx` open. Stop and SubagentStop can
- *  fire concurrently on the same conv (e.g. a Task subagent finishing
- *  while the parent is also wrapping up), and a crashed hook retry would
- *  race the next one. Holding a lock for the duration serializes them.
- *  Returns a releaser (or null if the lock is already held - in which
- *  case we skip this run; the holder will catch our data on its next
- *  transcript scan). */
-function acquireLock(convGuid) {
-    mkdirSync(CAPTURE_DIR, { recursive: true });
-    const path = lockPath(convGuid);
-    let fd;
+// Crash-safe reclaim, mirroring the advisory lock in src/sync.ts: a holder
+// writes its PID and heartbeats the lock's mtime; a peer reclaims it when the
+// holder crashed (dead PID), died before writing a PID (empty/garbage file), or
+// went silent past the stale window (wedged, or its PID was reused by an
+// unrelated process). Without this a SIGKILL'd hook would strand the lock and
+// silently disable capture for that conversation until SessionEnd.
+const LOCK_HEARTBEAT_MS = 15_000;
+export const LOCK_STALE_MS = 90_000;
+/** Decide whether an existing capture lock is reclaimable. Exported for tests.
+ *  Kept in sync with sync.ts's namesake. */
+export function isLockReclaimable(path, now = Date.now()) {
+    let raw;
+    let mtimeMs;
     try {
-        fd = openSync(path, 'wx');
+        raw = readFileSync(path, 'utf-8').trim();
+        mtimeMs = statSync(path).mtimeMs;
     }
     catch {
-        return null;
+        return false; // unreadable / already gone - don't steal, just skip
+    }
+    const pid = parseInt(raw, 10);
+    if (!raw || !pid || isNaN(pid))
+        return true; // empty/garbage = crashed mid-create
+    try {
+        process.kill(pid, 0);
     }
-    return () => {
+    catch {
+        return true;
+    } // holder PID is dead
+    return now - mtimeMs > LOCK_STALE_MS; // alive but heartbeat went silent
+}
+/** Exclusive file-lock via `wx` open, with crash-safe reclaim. Stop and
+ *  SubagentStop can fire concurrently on the same conv (e.g. a Task subagent
+ *  finishing while the parent is also wrapping up), and a crashed hook retry
+ *  would race the next one. Holding a lock for the duration serializes them.
+ *  Returns a releaser, or null when a *live* holder is already flushing - in
+ *  which case we skip this run; the holder will catch our data on its next
+ *  transcript scan. A dead/abandoned holder's lock is reclaimed once and
+ *  retried rather than waited on (capture is fire-and-forget; we never block
+ *  the user's session). Exported for tests. */
+export function acquireLock(convGuid) {
+    mkdirSync(CAPTURE_DIR, { recursive: true });
+    const path = lockPath(convGuid);
+    // At most one reclaim+retry: a genuinely live holder is flushing the same
+    // transcript, so we just skip; only a crashed/stale holder is stolen.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let fd;
         try {
-            closeSync(fd);
+            fd = openSync(path, 'wx'); // fails if the file exists
+        }
+        catch {
+            if (attempt === 0 && isLockReclaimable(path)) {
+                try {
+                    unlinkSync(path);
+                }
+                catch { /* race - someone else got it */ }
+                continue;
+            }
+            return null; // live holder (or lost the reclaim race) - let it cover us
         }
-        catch { /* ignore */ }
         try {
-            unlinkSync(path);
+            writeFileSync(fd, String(process.pid));
         }
-        catch { /* ignore */ }
-    };
+        finally {
+            closeSync(fd);
+        }
+        // Heartbeat the mtime so a long flush isn't mistaken for abandoned. unref()
+        // so the timer never keeps the hook process alive on its own.
+        const beat = setInterval(() => {
+            try {
+                utimesSync(path, new Date(), new Date());
+            }
+            catch { /* lock gone */ }
+        }, LOCK_HEARTBEAT_MS);
+        beat.unref?.();
+        return () => {
+            clearInterval(beat);
+            try {
+                unlinkSync(path);
+            }
+            catch { /* already gone */ }
+        };
+    }
+    return null;
 }
 async function readStdin() {
     if (process.stdin.isTTY)

package/dist/index.js

@@ -223,16 +223,47 @@ function fullCommandName(cmd) {
         parts.unshift(c.name());
     return parts.join(' ');
 }
+// Resolve the deepest (sub)command the user actually targeted by walking the
+// command tree against the leading positional tokens of argv (skipping flags,
+// and a root value-option's value). Used at error time to render the RIGHT
+// command's help — see enableHelpAfterError below for why we can't just capture
+// the command in a closure.
+function resolveTargetCommand(argv) {
+    const args = argv.slice(2);
+    const rootValueFlags = new Set(program.options.filter(o => o.long && o.required).map(o => o.long));
+    let cmd = program;
+    for (let i = 0; i < args.length; i++) {
+        const tok = args[i];
+        if (tok.startsWith('-')) {
+            if (!tok.includes('=') && rootValueFlags.has(tok))
+                i++; // consume its value
+            continue;
+        }
+        const next = cmd.commands.find(c => c.name() === tok || c.aliases().includes(tok));
+        if (!next)
+            break; // first non-subcommand operand ends the command chain
+        cmd = next;
+    }
+    return cmd;
+}
 function enableHelpAfterError(cmd) {
     cmd.configureOutput({
-        // Commander calls this on the offending (sub)command. We render that exact
-        // command's full help (via outputHelp, so addHelpText blocks are included)
-        // FIRST, then write the one-line error LAST. Both go to the same writeErr
-        // stream synchronously, so the order holds. We do NOT call
+        // Render the offending command's full help (via outputHelp, so addHelpText
+        // blocks are included) FIRST, then the one-line error LAST. Both go to the
+        // same writeErr stream synchronously, so the order holds. We do NOT call
         // showHelpAfterError - that would render help a second time, before the error.
+        //
+        // We must resolve the target command from argv rather than capturing `cmd`
+        // here: commander shares ONE _outputConfiguration object across a command
+        // and all its subcommands (copyInheritedSettings copies it by reference, and
+        // configureOutput mutates it in place). So every subcommand's closure would
+        // clobber its siblings', leaving only the last-registered subcommand's — and
+        // an unknown option on `fn call` would print `fn delete`'s help. Installing
+        // one identical, self-resolving handler everywhere sidesteps the clobber.
         outputError: (str, write) => {
-            write(`Showing \`${fullCommandName(cmd)} --help\`:\n\n`);
-            cmd.outputHelp({ error: true });
+            const target = resolveTargetCommand(process.argv);
+            write(`Showing \`${fullCommandName(target)} --help\`:\n\n`);
+            target.outputHelp({ error: true });
             write(`\n${str.replace(/\n+$/, '')}\n`);
         },
     });

package/dist/knowledge.js

@@ -121,6 +121,19 @@ Write files locally - the Gipity Claude Code plugin's hooks auto-push every save
 
 To keep local-only material (research clones, scratch data, vendored references) in the project directory without syncing or deploying it, list it in a \`.gipityignore\` at the project root - gitignore-style, one pattern per line, \`#\` comments. Ignored paths are invisible to sync in both directions; anything that already synced before being ignored stays on the server until you delete it.
 
+### Where files go: deploy only ships \`src/\`
+
+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.)
+- **\`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.
+
+Rule of thumb: shipping to users → \`src/\`; keep as reference → \`docs/\`; throwaway → \`tmp/\`.
+
+Watch for **bulky output dirs dropped loose at the root** (e.g. \`out/\`, \`vsd_out/\`, \`renders/\`). Unlike scratch, those are NOT ignored - they sync on every push and re-hash on every deploy, which is the classic cause of a slow, bloated deploy. Move them into \`docs/\` if you want to keep them or \`tmp/\` if they're disposable.
+
 ## Skills (detailed documentation)
 
 Run \`gipity skill list\` to see every skill. Run \`gipity skill read <name>\` to read one. Load the relevant skill before starting a task - they have the correct API patterns, code examples, and common mistakes.

package/dist/progress.js

@@ -22,10 +22,13 @@ const CLEAR_TO_EOL = '\x1b[K';
 const BAR_WIDTH = 18;
 const RENDER_THROTTLE_MS = 60;
 // Indeterminate bounce: a short block sliding across the same BAR_WIDTH track
-// the determinate bar fills. Frame cadence is slow enough to read, fast enough
-// to feel alive.
+// the determinate bar fills. Redraw cadence steps down once the wait gets long:
+// a snappy 10×/s under 10s, then once a second so a long wait reads as a calm
+// clock rather than a frantic blur.
 const SPIN_BLOCK = 5;
-const SPIN_FRAME_MS = 90;
+const SPIN_FRAME_FAST_MS = 100;
+const SPIN_FRAME_SLOW_MS = 1000;
+const SPIN_SLOWDOWN_AFTER_MS = 10_000;
 /** Compact elapsed: "8s", "1m 04s". Keeps the timer narrow and glanceable. */
 function formatElapsed(ms) {
     const s = Math.floor(ms / 1000);
@@ -34,12 +37,25 @@ function formatElapsed(ms) {
     const m = Math.floor(s / 60);
     return `${m}m ${String(s % 60).padStart(2, '0')}s`;
 }
+/**
+ * Spinner clock. Under 10s shows tenths ("2.2s") so a fresh wait visibly moves;
+ * at/after 10s switches to m:ss ("0:11", "1:02") - whole seconds are plenty once
+ * the redraw has slowed to once a second.
+ */
+function formatSpinClock(ms) {
+    if (ms < SPIN_SLOWDOWN_AFTER_MS)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const total = Math.floor(ms / 1000);
+    return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
+}
 class TerminalProgress {
     /** True while an in-place transfer/spinner line is on screen and not committed. */
     liveOpen = false;
     lastRenderAt = 0;
     /** The label of the current transfer session; a change starts a fresh one. */
     barLabel = null;
+    /** Wall-clock start of the current transfer session, for the elapsed timer. */
+    barStartedAt = 0;
     /** True once the current session hit 100% - late/overshoot ticks are dropped. */
     barSettled = false;
     /** Active indeterminate spinner timer, if any. */
@@ -60,6 +76,7 @@ class TerminalProgress {
         if (label !== this.barLabel) {
             this.barLabel = label;
             this.barSettled = false;
+            this.barStartedAt = Date.now();
         }
         if (this.barSettled)
             return;
@@ -82,13 +99,16 @@ class TerminalProgress {
         const startedAt = Date.now();
         let tick = 0;
         const draw = () => {
+            const elapsed = Date.now() - startedAt;
             this.liveOpen = true;
-            process.stdout.write('\r' + this.spinFrame(label, tick++, Date.now() - startedAt) + CLEAR_TO_EOL);
+            process.stdout.write('\r' + this.spinFrame(tick++, elapsed) + CLEAR_TO_EOL);
+            // Reschedule each frame so the cadence can step down as the wait lengthens.
+            const next = elapsed < SPIN_SLOWDOWN_AFTER_MS ? SPIN_FRAME_FAST_MS : SPIN_FRAME_SLOW_MS;
+            this.spinTimer = setTimeout(draw, next);
+            // Don't let the animation keep the event loop (and process) alive on its own.
+            this.spinTimer.unref?.();
         };
         draw();
-        this.spinTimer = setInterval(draw, SPIN_FRAME_MS);
-        // Don't let the animation keep the event loop (and process) alive on its own.
-        this.spinTimer.unref?.();
         const settle = (icon, message) => {
             this.stopSpinTimer();
             if (this.liveOpen)
@@ -118,7 +138,7 @@ class TerminalProgress {
     }
     stopSpinTimer() {
         if (this.spinTimer) {
-            clearInterval(this.spinTimer);
+            clearTimeout(this.spinTimer);
             this.spinTimer = null;
         }
     }
@@ -133,9 +153,14 @@ class TerminalProgress {
         const filled = Math.round((pct / 100) * BAR_WIDTH);
         const bar = brand('█'.repeat(filled)) + dim('░'.repeat(BAR_WIDTH - filled));
         const sizes = muted(`${formatSize(done)} / ${formatSize(total)}`);
-        return `  ${muted(label)}  ${bar}  ${brandBold(`${pct}%`)}  ${sizes}`;
+        // Same built-in elapsed timer the spinner carries, so a determinate transfer
+        // that stalls mid-flight (slow upload, wedged S3 PUT) still visibly ticks
+        // instead of freezing at "80%" - and the in-place line and the committed
+        // 100% frame both show how long the transfer took.
+        const elapsed = muted(formatElapsed(Date.now() - this.barStartedAt));
+        return `  ${muted(label)}  ${bar}  ${brandBold(`${pct}%`)}  ${sizes}  ${elapsed}`;
     }
-    spinFrame(label, tick, elapsedMs) {
+    spinFrame(tick, elapsedMs) {
         // Ping-pong the block's left edge between 0 and (BAR_WIDTH - SPIN_BLOCK).
         const span = BAR_WIDTH - SPIN_BLOCK;
         const cycle = span * 2;
@@ -144,7 +169,8 @@ class TerminalProgress {
         const bar = dim('░'.repeat(pos)) +
             brand('█'.repeat(SPIN_BLOCK)) +
             dim('░'.repeat(BAR_WIDTH - pos - SPIN_BLOCK));
-        return `  ${muted(label)}  ${bar}  ${muted(formatElapsed(elapsedMs))}`;
+        // No label: a bare track plus a clock, framed by three spaces on each side.
+        return `   ${bar}   ${muted(formatSpinClock(elapsedMs))}`;
     }
 }
 const NOOP_SPINNER = { succeed() { }, fail() { }, stop() { } };

package/dist/setup.js

@@ -39,8 +39,23 @@ export const PRIMER_FILES = {
 /** Aider's config file. We write/merge a `read:` entry into it so aider loads
  *  AGENTS.md - a per-workstation artifact like the primers, never synced. */
 export const AIDER_CONF_FILE = '.aider.conf.yml';
+/** Project-local scratch namespaces: file conversions, intermediate outputs,
+ *  design staging - work the agent wants on disk but should never sync or
+ *  deploy. These MUST mirror the sandbox's `isEphemeralSandboxPath` denylist
+ *  (`platform/server/src/services/sandbox/no-persist.ts`) so the same dirs are
+ *  treated as throwaway everywhere: a sandbox run refuses to persist them, and
+ *  `gipity sync`/deploy refuses to upload them. Keeping the two in lockstep is
+ *  what makes scratch coherent across the platform - update both together.
+ *  `tmp/` is the one we teach agents to use (see knowledge.ts "Files and sync");
+ *  `*_tmp/` and `.gipityscratch/` are caught defensively so legacy/scattered
+ *  scratch (the `_vsd_tmp/`/`_convert_tmp/` dirs that bloated past deploys)
+ *  can't leak in either. Reference material to KEEP (diagrams, decks, ADRs) goes
+ *  in `docs/` instead - synced and versioned, but outside `src/` so it's never
+ *  deployed. Gitignore-glob form, matched by the `ignore` package in config.ts. */
+export const SCRATCH_IGNORE = ['tmp/', '.tmp/', '*_tmp/', '.gipityscratch/'];
 export const DEFAULT_SYNC_IGNORE = [
     'node_modules', '.git', '.gipity.json', '.gipity/', '.claude/', '.gitignore', AIDER_CONF_FILE,
+    ...SCRATCH_IGNORE,
     ...new Set(Object.values(PRIMER_FILES)),
 ];
 /** True if `name` (a top-level dir entry) is a workstation artifact that
@@ -480,7 +495,9 @@ export const SUPPORTED_TOOLS = [
 export const DEFAULT_TOOLS = SUPPORTED_TOOLS.filter(t => !t.optIn);
 export function setupGitignore() {
     const gitignorePath = resolve(process.cwd(), '.gitignore');
-    const entries = ['.gipity/', '.gipity.json'];
+    // Sync already skips the scratch namespaces (DEFAULT_SYNC_IGNORE); ignore them
+    // in git too so ephemeral conversion/staging work never gets committed.
+    const entries = ['.gipity/', '.gipity.json', ...SCRATCH_IGNORE];
     if (existsSync(gitignorePath)) {
         let content = readFileSync(gitignorePath, 'utf-8');
         // Split on \r?\n so a CRLF .gitignore (the Windows default) doesn't leave a

package/dist/sync.js

@@ -21,7 +21,7 @@
  * `name (conflict from <host> YYYY-MM-DD-HHMMSS).ext` and then uploaded on
  * the next pass so every client sees it. No content merging, ever.
  */
-import { writeFileSync, mkdirSync, existsSync, statSync, unlinkSync, readdirSync, rmdirSync, readFileSync, renameSync, openSync, closeSync } from 'fs';
+import { writeFileSync, mkdirSync, existsSync, statSync, unlinkSync, readdirSync, rmdirSync, readFileSync, renameSync, openSync, closeSync, utimesSync } from 'fs';
 import { join, relative, dirname, extname, resolve, sep } from 'path';
 import { hostname } from 'os';
 import { get, del, downloadStream, ApiError } from './api.js';
@@ -38,6 +38,10 @@ import * as tar from 'tar-stream';
  *  project probably are intentional. */
 const BULK_DELETE_COUNT = 10;
 const BULK_DELETE_FRACTION = 0.25;
+/** A tar download that stops producing bytes for this long - without ever
+ *  ending the stream - is treated as a stall and aborted, so a wedged
+ *  connection becomes a recoverable error instead of an unbounded hang. */
+const DOWNLOAD_IDLE_MS = 30_000;
 // ─── Paths ─────────────────────────────────────────────────────
 function syncStatePath() {
     const configPath = getConfigPath();
@@ -54,44 +58,103 @@ function projectDir() {
 // ─── Advisory lock ─────────────────────────────────────────────
 const LOCK_WAIT_MS = 30_000;
 const LOCK_POLL_MS = 500;
-/** Acquire the per-project sync lock. Returns a release function. Exported for tests. */
-export async function acquireLock() {
+// While a holder works it refreshes the lock's mtime on this cadence; a lock
+// whose mtime is older than the stale window is treated as abandoned and
+// reclaimed even if a process with its PID still exists. This catches the two
+// cases a dead-PID check misses: a CPU-wedged holder that stopped heartbeating,
+// and PID reuse (some unrelated process now owns the old holder's PID). The
+// stale window must stay comfortably larger than the heartbeat so a briefly
+// busy holder isn't robbed mid-run.
+const LOCK_HEARTBEAT_MS = 15_000;
+export const LOCK_STALE_MS = 90_000;
+/** Decide whether an existing lock file is reclaimable. Exported for tests.
+ *  Reclaim when: the file is empty/garbage (holder crashed between creating the
+ *  lock and writing its PID), the holder PID is dead, or the lock's heartbeat
+ *  went silent past {@link LOCK_STALE_MS}. A live, freshly-heartbeating holder
+ *  is never reclaimed. */
+export function isLockReclaimable(path, now = Date.now()) {
+    let raw;
+    let mtimeMs;
+    try {
+        raw = readFileSync(path, 'utf-8').trim();
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return false; // can't read it (likely already gone / racing) - retry, don't steal
+    }
+    const pid = parseInt(raw, 10);
+    if (!raw || !pid || isNaN(pid))
+        return true; // empty/garbage = crashed mid-create
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return true;
+    } // holder PID is dead
+    return now - mtimeMs > LOCK_STALE_MS; // alive but heartbeat went silent
+}
+/** Acquire the per-project sync lock. Returns a release function. Exported for tests.
+ *  Pass `progress` so a *contended* wait (another sync/push holds the lock) shows a
+ *  live "Waiting for another sync…" spinner instead of a silent stall - the lock is
+ *  taken before any sync phase prints, so without this an agent or user staring at a
+ *  frozen terminal can't tell a 30s lock wait from a genuine hang. The spinner is
+ *  created lazily, only when we actually have to wait, so the common instant-acquire
+ *  path stays output-free (and on a non-TTY the reporter is a no-op regardless). */
+export async function acquireLock(progress) {
     const path = lockPath();
     mkdirSync(dirname(path), { recursive: true });
     const start = Date.now();
+    // Lazily-opened spinner for the contended case; settled before we return.
+    let waitSpinner = null;
+    const settleWait = (ok) => {
+        if (!waitSpinner)
+            return;
+        if (ok)
+            waitSpinner.stop();
+        else
+            waitSpinner.fail('Gave up waiting for the sync lock');
+        waitSpinner = null;
+    };
     while (true) {
         try {
             const fd = openSync(path, 'wx');
             writeFileSync(fd, String(process.pid));
             closeSync(fd);
-            return () => { try {
+            // Heartbeat: keep the lock's mtime fresh so peers can distinguish a live
+            // holder from an abandoned one. unref() so it never holds the process open.
+            const beat = setInterval(() => {
+                try {
+                    utimesSync(path, new Date(), new Date());
+                }
+                catch { /* lock gone */ }
+            }, LOCK_HEARTBEAT_MS);
+            beat.unref?.();
+            settleWait(true);
+            return () => { clearInterval(beat); try {
                 unlinkSync(path);
             }
             catch { /* already gone */ } };
         }
         catch {
-            // Either lock exists, or the race gave us a transient error. Check for
-            // staleness (holder PID is dead → treat as unlocked).
-            try {
-                const pid = parseInt(readFileSync(path, 'utf-8').trim(), 10);
-                if (pid && !isNaN(pid)) {
-                    try {
-                        process.kill(pid, 0);
-                    }
-                    catch {
-                        try {
-                            unlinkSync(path);
-                        }
-                        catch { /* race */ }
-                        continue;
-                    }
+            // Lock exists (or the race gave a transient error). Reclaim it if the
+            // holder is dead/abandoned; otherwise wait and retry.
+            if (isLockReclaimable(path)) {
+                try {
+                    unlinkSync(path);
                 }
+                catch { /* race - someone else got it */ }
+                continue;
             }
-            catch { /* couldn't read - retry */ }
             if (Date.now() - start > LOCK_WAIT_MS) {
+                settleWait(false);
                 throw new Error(`Another sync is in progress (${path}). Waited ${LOCK_WAIT_MS / 1000}s. ` +
                     `Remove the file manually if you're sure no sync is running.`);
             }
+            // First time we're forced to wait: open the spinner so the wait is visible
+            // (with an elapsed timer) rather than reading as a frozen process.
+            if (!waitSpinner) {
+                waitSpinner = progress?.spinner('Waiting for another sync to finish…') ?? null;
+            }
             await new Promise(r => setTimeout(r, LOCK_POLL_MS));
         }
     }
@@ -222,27 +285,67 @@ async function fetchRemote(projectGuid) {
     }
     return out;
 }
-async function downloadAll(projectGuid, onBytes) {
-    const stream = await downloadStream(`/projects/${projectGuid}/files/tree?content=tar`);
+/**
+ * Extract a tar stream into a path→bytes map, guarded by an idle watchdog.
+ *
+ * The sync hang was here: the server delivered every byte (progress bar hit
+ * 100%) but never cleanly ended the stream, so tar's 'finish' never fired and
+ * the awaiting Promise never settled - an unbounded hang. The watchdog turns
+ * that into a recoverable error: if no bytes arrive for idleMs without the
+ * stream ending, destroy it (closing the socket) and reject. pipe() also doesn't
+ * forward source errors to the destination, so we reject on a source 'error' too
+ * - a truncated body must never look like a clean 'finish' with partial files.
+ *
+ * `keep` filters which entries to buffer (default: all); every entry is still
+ * drained so the stream can progress. Exported for tests.
+ */
+export function extractTarToMap(stream, idleMs, onBytes, keep) {
     const extract = tar.extract();
     const files = new Map();
     return new Promise((resolve, reject) => {
+        let settled = false;
+        let idle;
+        const arm = () => {
+            clearTimeout(idle);
+            idle = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                const e = new Error(`download stalled: no data for ${idleMs / 1000}s`);
+                stream.destroy(e);
+                reject(e);
+            }, idleMs);
+            idle.unref?.();
+        };
+        const done = (fn, arg) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(idle);
+            fn(arg);
+        };
         extract.on('entry', (header, entryStream, next) => {
+            arm();
+            const name = normalizeTreePath(header.name);
+            const wanted = keep ? keep(name) : true;
             const chunks = [];
-            entryStream.on('data', (c) => { chunks.push(c); onBytes?.(c.length); });
-            entryStream.on('end', () => { files.set(normalizeTreePath(header.name), Buffer.concat(chunks)); next(); });
+            entryStream.on('data', (c) => { if (wanted)
+                chunks.push(c); onBytes?.(c.length); arm(); });
+            entryStream.on('end', () => { if (wanted)
+                files.set(name, Buffer.concat(chunks)); next(); });
             entryStream.resume();
         });
-        extract.on('finish', () => resolve(files));
-        extract.on('error', reject);
-        // pipe() does NOT forward source-stream errors to the destination, so a
-        // truncated/aborted HTTP body would otherwise surface as a clean tar
-        // 'finish' with a partial file set. Reject explicitly so a short download is
-        // an error the caller can recover from, never a silent partial.
-        stream.on('error', reject);
+        extract.on('finish', () => done(resolve, files));
+        extract.on('error', (e) => done(reject, e));
+        stream.on('error', (e) => done(reject, e));
+        arm();
         stream.pipe(extract);
     });
 }
+async function downloadAll(projectGuid, onBytes) {
+    const stream = await downloadStream(`/projects/${projectGuid}/files/tree?content=tar`);
+    return extractTarToMap(stream, DOWNLOAD_IDLE_MS, onBytes);
+}
 async function fetchOne(projectGuid, path) {
     // Exact single-file read first. The tree-tar endpoint below treats its `path`
     // as a DIRECTORY prefix, so a single root file (e.g. `gipity.yaml`) comes back
@@ -262,24 +365,12 @@ async function fetchOne(projectGuid, path) {
     }
     try {
         const stream = await downloadStream(`/projects/${projectGuid}/files/tree?content=tar&path=${encodeURIComponent(path)}`);
-        const extract = tar.extract();
-        return await new Promise((resolve, reject) => {
-            let found = null;
-            extract.on('entry', (header, entryStream, next) => {
-                if (normalizeTreePath(header.name) === normalizeTreePath(path)) {
-                    const chunks = [];
-                    entryStream.on('data', (c) => chunks.push(c));
-                    entryStream.on('end', () => { found = Buffer.concat(chunks); next(); });
-                }
-                else {
-                    entryStream.on('end', () => next());
-                }
-                entryStream.resume();
-            });
-            extract.on('finish', () => resolve(found));
-            extract.on('error', reject);
-            stream.pipe(extract);
-        });
+        // Same idle-guarded extraction as the bulk path; keep only the one entry we
+        // asked for. The recovery path must not hang either, or a single stalled file
+        // wedges the whole sync.
+        const want = normalizeTreePath(path);
+        const files = await extractTarToMap(stream, DOWNLOAD_IDLE_MS, undefined, (p) => p === want);
+        return files.get(want) ?? null;
     }
     catch {
         return null;
@@ -534,7 +625,7 @@ export async function sync(opts = {}) {
     const root = projectDir();
     const interactive = opts.interactive ?? process.stdout.isTTY ?? false;
     const ignore = effectiveIgnore(root, config.ignore);
-    const releaseLock = await acquireLock();
+    const releaseLock = await acquireLock(opts.progress);
     try {
         return await syncInner(config.projectGuid, root, ignore, opts, interactive);
     }

package/package.json

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