gipity 1.0.402 → 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,9 +172,28 @@ 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}`);
     }

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/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/knowledge.js

@@ -128,7 +128,7 @@ Deploy is opt-in, not opt-out: the \`files\` phase uploads **only** what's under
 - **\`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.
+- **\`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/\`.
 

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/sync.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();
@@ -89,11 +93,28 @@ export function isLockReclaimable(path, now = Date.now()) {
     } // 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. */
-export async function acquireLock() {
+/** 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');
@@ -108,6 +129,7 @@ export async function acquireLock() {
                 catch { /* lock gone */ }
             }, LOCK_HEARTBEAT_MS);
             beat.unref?.();
+            settleWait(true);
             return () => { clearInterval(beat); try {
                 unlinkSync(path);
             }
@@ -124,9 +146,15 @@ export async function acquireLock() {
                 continue;
             }
             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));
         }
     }
@@ -257,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
@@ -297,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;
@@ -569,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.402",
+  "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",