gipity 1.0.397 → 1.0.398

package/dist/adopt-cwd.js

@@ -11,7 +11,7 @@
  *      `.gipity.json`, sync, and install hooks/skills/gitignore.
  */
 import { readdirSync, statSync } from 'fs';
-import { join, resolve, sep } from 'path';
+import { join, resolve, sep, parse as parsePath } from 'path';
 import { homedir } from 'os';
 import { get, post, ApiError } from './api.js';
 import { isSyncIgnored } from './setup.js';
@@ -103,6 +103,15 @@ export function canAdoptCwd(cwd) {
         '/tmp', '/var', '/etc', '/usr', '/opt',
         '/mnt', '/mnt/c', '/mnt/d', '/mnt/wsl',
     ]);
+    // Filesystem root (POSIX `/` already covered by `sep`, but on Windows this
+    // catches drive roots like `C:\`). Plus the common Windows system dirs.
+    if (norm === parsePath(norm).root)
+        return false;
+    for (const envVar of ['windir', 'SystemRoot', 'ProgramFiles', 'ProgramFiles(x86)']) {
+        const v = process.env[envVar];
+        if (v && norm === resolve(v))
+            return false;
+    }
     if (blocked.has(norm))
         return false;
     // Workspace-parent heuristic: a directory at depth ≤1 below $HOME that

package/dist/api.js

@@ -2,6 +2,7 @@ import { Readable } from 'stream';
 import * as tar from 'tar-stream';
 import { getAuth, refreshTokenIfNeeded } from './auth.js';
 import { resolveApiBase, requireConfig, saveConfig } from './config.js';
+import { clientHeaders } from './client-context.js';
 export class ApiError extends Error {
     statusCode;
     code;
@@ -32,6 +33,7 @@ async function bearerToken() {
 }
 async function getHeaders() {
     return {
+        ...clientHeaders(),
         'Authorization': `Bearer ${await bearerToken()}`,
         'Content-Type': 'application/json',
     };
@@ -137,7 +139,7 @@ export async function sendMessage(message) {
 export async function download(path) {
     const url = `${baseUrl()}${path}`;
     const res = await fetch(url, {
-        headers: { 'Authorization': `Bearer ${await bearerToken()}` },
+        headers: { ...clientHeaders(), 'Authorization': `Bearer ${await bearerToken()}` },
     });
     if (!res.ok) {
         throw new ApiError(res.status, 'DOWNLOAD_ERROR', `Download failed: ${res.statusText}`);
@@ -149,7 +151,7 @@ export async function downloadStream(path) {
     const { Readable } = await import('stream');
     const url = `${baseUrl()}${path}`;
     const res = await fetch(url, {
-        headers: { 'Authorization': `Bearer ${await bearerToken()}` },
+        headers: { ...clientHeaders(), 'Authorization': `Bearer ${await bearerToken()}` },
     });
     if (!res.ok) {
         throw new ApiError(res.status, 'DOWNLOAD_ERROR', `Download failed: ${res.statusText}`);
@@ -199,7 +201,7 @@ export async function publicPost(path, body) {
     const url = `${baseUrl()}${path}`;
     const res = await fetch(url, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { ...clientHeaders(), 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
     });
     if (!res.ok) {

package/dist/client-context.js

@@ -0,0 +1,63 @@
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+function cliVersion() {
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(resolve(dir, '../package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function hasEnvPrefix(prefix) {
+    return Object.keys(process.env).some((k) => k.startsWith(prefix));
+}
+function isCi() {
+    const ci = (process.env.CI ?? '').toLowerCase();
+    return ci === '1' || ci === 'true' || !!process.env.GITHUB_ACTIONS;
+}
+/** Identify the coding harness from its env footprint. Order = specificity. Exported for tests. */
+export function detectHarness() {
+    // Claude Code is the most reliable: CLAUDECODE=1 plus a versioned exec path.
+    if (process.env.CLAUDECODE === '1' || process.env.CLAUDE_CODE_ENTRYPOINT) {
+        const version = process.env.CLAUDE_CODE_EXECPATH?.match(/versions\/([^/\\]+)/)?.[1];
+        return { harness: 'claude-code', harnessVersion: version, harnessSession: process.env.CLAUDE_CODE_SESSION_ID };
+    }
+    if (hasEnvPrefix('CODEX_'))
+        return { harness: 'codex' };
+    if (process.env.CURSOR_TRACE_ID || hasEnvPrefix('CURSOR_') || (process.env.TERM_PROGRAM ?? '').toLowerCase().includes('cursor')) {
+        return { harness: 'cursor' };
+    }
+    if (hasEnvPrefix('AIDER_'))
+        return { harness: 'aider' };
+    if (process.env.GEMINI_CLI)
+        return { harness: 'gemini' };
+    if (isCi())
+        return { harness: 'ci' };
+    return { harness: 'manual' };
+}
+let cached;
+export function clientContext() {
+    if (cached)
+        return cached;
+    cached = {
+        cli: cliVersion(),
+        ...detectHarness(),
+        node: process.versions.node,
+        os: process.platform,
+        arch: process.arch,
+        ci: isCi() || undefined,
+    };
+    return cached;
+}
+/** Headers to merge into every API request so the server can attribute the call. */
+export function clientHeaders() {
+    const ctx = clientContext();
+    return {
+        'User-Agent': `gipity-cli/${ctx.cli} (${ctx.os}; ${ctx.arch}; harness=${ctx.harness})`,
+        'X-Gipity-Client': JSON.stringify(ctx),
+    };
+}
+//# sourceMappingURL=client-context.js.map

package/dist/commands/claude.js

@@ -4,19 +4,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdir
 import { execSync, spawn } from 'child_process';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
-/** On Windows, spawn without shell:true needs an explicit extension (.exe or .cmd) */
-function resolveCommand(cmd) {
-    if (process.platform !== 'win32')
-        return cmd;
-    try {
-        const lines = execSync(`where ${cmd}`, { encoding: 'utf-8' }).split(/\r?\n/).map(l => l.trim()).filter(Boolean);
-        // Prefer .exe (native) over .cmd (npm shim)
-        return lines.find(l => l.endsWith('.exe')) || lines.find(l => l.endsWith('.cmd')) || cmd;
-    }
-    catch {
-        return `${cmd}.cmd`;
-    }
-}
+import { resolveCommand } from '../platform.js';
 import { getAuth, saveAuth } from '../auth.js';
 import { get, post, publicPost, ApiError, getAccountSlug } from '../api.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, DEFAULT_API_BASE, getConfigPath } from '../config.js';
@@ -26,12 +14,35 @@ import { buildProjectContextBlock as buildProjectContextBlockText, buildNewProje
 import * as relayState from '../relay/state.js';
 import { maybeOfferRelayOn, ensureDaemonRunning } from '../relay/onboarding.js';
 import { prompt, pickOne, decodeJwtExp, confirm } from '../utils.js';
-import { brand, bold, info, success, error as clrError, muted } from '../colors.js';
+import { brand, bold, info, success, warning, error as clrError, muted } from '../colors.js';
 import { createProgressReporter } from '../progress.js';
 import { printBanner } from '../banner.js';
 import { scanForAdoption, isLikelyEmpty, canAdoptCwd, formatCwdLabel, formatBytes, adoptCurrentDir, ADOPT_THRESHOLDS, } from '../adopt-cwd.js';
 const __clDir = dirname(fileURLToPath(import.meta.url));
 const __clPkg = JSON.parse(readFileSync(resolve(__clDir, '../../package.json'), 'utf-8'));
+/** Report a sync run to the user. Beyond the applied-changes line, this SURFACES
+ *  sync.errors - a download that came back incomplete (truncated bulk tar, a file
+ *  that couldn't be refetched) lands here, so we never print "ready" over a
+ *  half-synced project as if nothing went wrong. Deletions are disarmed on an
+ *  incomplete pull, so we can tell the user plainly that nothing was deleted. */
+function reportSyncResult(result) {
+    if (result.aborted) {
+        console.log(`  ${warning('Merge cancelled — this folder was NOT synced with the project.')}`);
+        console.log(`  ${muted('For a clean copy, quit and open the project in an empty folder. To merge anyway, run `gipity sync`.')}`);
+        return;
+    }
+    if (result.applied > 0) {
+        console.log(`  Synced ${result.applied} change${result.applied > 1 ? 's' : ''} with Gipity.`);
+    }
+    if (result.errors.length) {
+        console.log(`  ${warning(`Sync finished with ${result.errors.length} problem${result.errors.length === 1 ? '' : 's'} — your local copy may be incomplete:`)}`);
+        for (const e of result.errors.slice(0, 8))
+            console.log(`    - ${e}`);
+        if (result.errors.length > 8)
+            console.log(`    …and ${result.errors.length - 8} more.`);
+        console.log(`  ${muted('Nothing was deleted. Re-run `gipity sync` to finish the pull.')}`);
+    }
+}
 import { getProjectsRoot } from '../relay/paths.js';
 /** Ask the server for recursive VFS counts. Server owns the file metadata
  *  (counts, bytes, paths), so a single aggregate query beats walking the
@@ -395,13 +406,11 @@ export const claudeCommand = new Command('claude')
             });
             console.log(`\n  Using ${projectDir}`);
             try {
-                const result = await sync({ interactive: !nonInteractive, progress: syncProgress });
-                if (result.applied > 0) {
-                    console.log(`  Synced ${result.applied} change${result.applied > 1 ? 's' : ''} with Gipity.`);
-                }
+                const result = await sync({ interactive: !nonInteractive, confirmMerge: !nonInteractive, progress: syncProgress });
+                reportSyncResult(result);
             }
-            catch {
-                console.log('  Could not sync files (will retry on next prompt).');
+            catch (err) {
+                console.log(`  ${warning('Could not sync files (will retry on next prompt):')} ${err.message}`);
             }
             setupClaudeHooks();
             setupClaudeMd();
@@ -445,13 +454,11 @@ export const claudeCommand = new Command('claude')
             }
             if (doSync) {
                 try {
-                    const result = await sync({ interactive: !nonInteractive, progress: syncProgress });
-                    if (result.applied > 0) {
-                        console.log(`  Synced ${result.applied} change${result.applied > 1 ? 's' : ''} with Gipity.`);
-                    }
+                    const result = await sync({ interactive: !nonInteractive, confirmMerge: !nonInteractive, progress: syncProgress });
+                    reportSyncResult(result);
                 }
-                catch {
-                    console.log('  Could not sync files (will retry on next prompt).');
+                catch (err) {
+                    console.log(`  ${warning('Could not sync files (will retry on next prompt):')} ${err.message}`);
                 }
             }
             // Interactive: no seeded prompt - CLAUDE.md carries the context now.
@@ -570,13 +577,11 @@ export const claudeCommand = new Command('claude')
                 console.log(`\n  Using ${projectDir}`);
                 // Unified sync - push and pull resolved via three-way merge (non-fatal)
                 try {
-                    const result = await sync({ interactive: !nonInteractive, progress: syncProgress });
-                    if (result.applied > 0) {
-                        console.log(`  Synced ${result.applied} change${result.applied > 1 ? 's' : ''} with Gipity.`);
-                    }
+                    const result = await sync({ interactive: !nonInteractive, confirmMerge: !nonInteractive, progress: syncProgress });
+                    reportSyncResult(result);
                 }
-                catch {
-                    console.log('  Could not sync files (will retry on next prompt).');
+                catch (err) {
+                    console.log(`  ${warning('Could not sync files (will retry on next prompt):')} ${err.message}`);
                 }
             }
             // Interactive launch: no seeded first message (new or existing). The

package/dist/commands/credits.js

@@ -1,15 +1,18 @@
 import { Command } from 'commander';
 import { spawn } from 'node:child_process';
 import { get } from '../api.js';
-import { brand, muted } from '../colors.js';
+import { brand, muted, success, error as clrError } from '../colors.js';
 import { run, printList } from '../helpers/index.js';
 const PRICING_URL = 'https://prompt.gipity.ai/pricing';
 function openInBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open' :
-        process.platform === 'win32' ? 'start' :
-            'xdg-open';
+    // Windows `start` is a cmd.exe builtin, not an executable - spawn can't
+    // launch it directly, so go through `cmd /c start`. The empty "" is the
+    // window-title arg; without it a quoted URL would be swallowed as the title.
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] :
+        process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] :
+            ['xdg-open', [url]];
     try {
-        spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref();
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
     }
     catch {
         // Spawn failed (no xdg-open on minimal Linux, etc.) - caller prints the URL.
@@ -19,17 +22,23 @@ export const creditsCommand = new Command('credits')
     .description('View credits')
     .option('--json', 'Output as JSON')
     .action((opts) => run('Credits', async () => {
-    const res = await get('/credits/balance');
     if (opts.json) {
+        const res = await get('/credits/balance');
         console.log(JSON.stringify(res.data));
+        return;
     }
-    else {
-        console.log(`Credits: ${brand(res.data.available.toLocaleString())}`);
-        if (res.data.balances.length > 0) {
-            for (const b of res.data.balances) {
-                const exp = new Date(b.expiresAt).toLocaleDateString();
-                console.log(`${b.source}: ${b.creditsRemaining.toLocaleString()}  ${muted(`expires ${exp}`)}`);
-            }
+    const [balRes, subRes] = await Promise.all([
+        get('/credits/balance'),
+        get('/credits/subscription'),
+    ]);
+    const sub = subRes.data;
+    const tierLabel = sub.tier === 'pro' ? 'Gipity Pro' : 'Free';
+    console.log(`Plan: ${brand(tierLabel)} ${muted(`(${sub.status})`)}`);
+    console.log(`Credits: ${brand(balRes.data.available.toLocaleString())}`);
+    if (balRes.data.balances.length > 0) {
+        for (const b of balRes.data.balances) {
+            const exp = new Date(b.expiresAt).toLocaleDateString();
+            console.log(`${b.source}: ${b.creditsRemaining.toLocaleString()}  ${muted(`expires ${exp}`)}`);
         }
     }
 }));
@@ -41,12 +50,42 @@ creditsCommand
     openInBrowser(PRICING_URL);
     console.log(muted("If your browser didn't open automatically, copy the URL above."));
 }));
+creditsCommand
+    .command('status')
+    .description('Show billing/Stripe configuration health (admin only)')
+    .option('--json', 'Output as JSON')
+    // optsWithGlobals(): the parent `credits` command also declares --json, which
+    // commander binds to the parent - so read merged opts to see the flag here.
+    .action((_opts, cmd) => run('Billing status', async () => {
+    const opts = cmd.optsWithGlobals();
+    const res = await get('/admin/billing-status');
+    const s = res.data;
+    if (opts.json) {
+        console.log(JSON.stringify(s));
+        return;
+    }
+    const mark = (ok) => (ok ? success('✓') : clrError('✗'));
+    console.log(`Stripe mode:     ${brand(s.mode)}`);
+    console.log(`Secret key:      ${mark(s.secretKeyConfigured)}`);
+    console.log(`Webhook secret:  ${mark(s.webhookSecretConfigured)}  ${muted(`endpoint ${s.webhookPath}`)}`);
+    console.log(`Credit packs:    ${mark(s.packsConfigured)}${s.packsError ? `  ${clrError(s.packsError)}` : ''}`);
+    for (const p of s.packs) {
+        console.log(`  ${p.name}  ${muted(p.priceId)}${p.hidden ? muted(' [hidden]') : ''}`);
+    }
+    console.log(`Test pack ($1):  ${mark(s.testPackConfigured)}  ${muted('set STRIPE_PACK_TEST_PRICE_ID to enable a cheap purchase smoke test')}`);
+    console.log('Subscription plans:');
+    for (const pl of s.subscriptionPlans) {
+        console.log(`  ${pl.name} (${pl.tier})  ${mark(pl.priceIdConfigured)}`);
+    }
+}));
 creditsCommand
     .command('usage')
     .description('Show recent usage')
     .option('--limit <n>', 'Number of entries', '20')
     .option('--json', 'Output as JSON')
-    .action((opts) => run('Usage', async () => {
+    // optsWithGlobals(): parent `credits` also declares --json (see status above).
+    .action((_opts, cmd) => run('Usage', async () => {
+    const opts = cmd.optsWithGlobals();
     const limit = parseInt(opts.limit, 10) || 20;
     const res = await get(`/credits/usage?limit=${limit}`);
     printList(res.data, opts, 'No usage history.', u => {

package/dist/commands/generate.js

@@ -5,6 +5,7 @@ import { pushFile } from '../sync.js';
 import { writeFileSync } from 'fs';
 import { resolve as resolvePath, dirname, relative, isAbsolute } from 'path';
 import { error as clrError, success, muted, info } from '../colors.js';
+import { printCommandError } from '../helpers/command.js';
 import { IMAGE_MODELS_DOC, IMAGE_GEMINI_ASPECT_RATIOS, IMAGE_GEMINI_SIZES, VIDEO_MODELS_DOC, TTS_PROVIDER_DESCRIPTIONS } from '../provider-docs.js';
 /** Download a URL and save to a local file, then push it up to the project so
  *  the cloud (and anything that mirrors it) immediately matches local disk.
@@ -98,7 +99,7 @@ Examples:
         }
     }
     catch (err) {
-        console.error(clrError(`Image generation failed: ${err.message}`));
+        printCommandError('Image generation', err);
         process.exit(1);
     }
 });
@@ -150,7 +151,7 @@ Examples:
         }
     }
     catch (err) {
-        console.error(clrError(`Video generation failed: ${err.message}`));
+        printCommandError('Video generation', err);
         process.exit(1);
     }
 });
@@ -209,7 +210,7 @@ Examples:
         }
     }
     catch (err) {
-        console.error(clrError(`Speech generation failed: ${err.message}`));
+        printCommandError('Speech generation', err);
         process.exit(1);
     }
 });
@@ -259,7 +260,7 @@ Examples:
         }
     }
     catch (err) {
-        console.error(clrError(`Music generation failed: ${err.message}`));
+        printCommandError('Music generation', err);
         process.exit(1);
     }
 });

package/dist/commands/sync.js

@@ -12,7 +12,11 @@ export const syncCommand = new Command('sync')
     try {
         // JSON mode stays machine-clean; otherwise show live progress on a TTY.
         const progress = opts.json ? undefined : createProgressReporter();
-        const result = await sync({ plan: opts.plan, force: opts.force, prune: opts.prune, progress });
+        // confirmMerge arms the uncertain-merge guard: a first-time sync into a
+        // folder that has its own files prompts on a TTY, proceeds with --yes, and
+        // fail-safe ABORTS when non-interactive without --yes - so a script never
+        // merges an unexpected folder into the project silently.
+        const result = await sync({ plan: opts.plan, force: opts.force, prune: opts.prune, confirmMerge: true, progress });
         if (opts.json) {
             console.log(JSON.stringify(result));
         }
@@ -33,7 +37,9 @@ export const syncCommand = new Command('sync')
             for (const e of result.errors)
                 console.error(clrError(e));
         }
-        if (result.errors.length > 0)
+        // A refused merge or any sync error is a non-zero exit so scripts/CI can
+        // detect that nothing was applied.
+        if (result.aborted || result.errors.length > 0)
             process.exit(1);
     }
     catch (err) {

package/dist/helpers/command.js

@@ -10,9 +10,24 @@ import { error as clrError } from '../colors.js';
  * Usage:
  *   .action((name, opts) => run('Create', async () => { ... }))
  */
+/**
+ * Print a command error. Out-of-credits is a recoverable, user-actionable
+ * state, so flag it plainly (and keep the server's message, which carries the
+ * buy link) - that way an agent reading this output, e.g. Claude Code, can tell
+ * the user they're out of Gipity credits and where to top up rather than
+ * treating it as a hard failure. Does not exit; the caller decides.
+ */
+export function printCommandError(label, err) {
+    if (err?.code === 'INSUFFICIENT_CREDITS') {
+        console.error(clrError(`${label} failed - out of Gipity credits.`));
+        console.error(err.message);
+        return;
+    }
+    console.error(clrError(`${label} failed: ${err.message}`));
+}
 export function run(label, action) {
     action().catch((err) => {
-        console.error(clrError(`${label} failed: ${err.message}`));
+        printCommandError(label, err);
         process.exit(1);
     });
 }

package/dist/platform.js

@@ -0,0 +1,26 @@
+import { execSync } from 'child_process';
+/**
+ * Resolve a command to something Node's spawn/spawnSync can launch directly.
+ *
+ * On Windows, npm-installed CLIs (npm, npx, gipity, claude) are `.cmd` batch
+ * shims, not `.exe`s. Node's spawn without `shell: true` cannot launch a bare
+ * `npm` - it fails with ENOENT and a null exit status. Resolving the real path
+ * (preferring `.exe`, falling back to `.cmd`) lets us spawn without `shell: true`
+ * (which would otherwise require escaping arguments).
+ */
+export function resolveCommand(cmd) {
+    if (process.platform !== 'win32')
+        return cmd;
+    try {
+        const lines = execSync(`where ${cmd}`, { encoding: 'utf-8' })
+            .split(/\r?\n/)
+            .map(l => l.trim())
+            .filter(Boolean);
+        // Prefer .exe (native) over .cmd (npm shim)
+        return lines.find(l => l.endsWith('.exe')) || lines.find(l => l.endsWith('.cmd')) || cmd;
+    }
+    catch {
+        return `${cmd}.cmd`;
+    }
+}
+//# sourceMappingURL=platform.js.map

package/dist/relay/daemon.js

@@ -21,6 +21,7 @@
  * See docs/feature-backlog/gipity-relay-phases.md (Phase A Step 7).
  */
 import { spawn } from 'child_process';
+import { resolveCommand } from '../platform.js';
 import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync, chmodSync, closeSync, openSync, unlinkSync } from 'fs';
 import { stat, readFile } from 'fs/promises';
 import { createInterface } from 'readline';
@@ -855,7 +856,10 @@ export async function killRunningForConv(convGuid) {
  *  resolution (the daemon itself doesn't chdir into projects).
  *  Non-blocking on failure - caller catches and logs. */
 async function spawnSync(cwd, timeoutMs) {
-    const cmd = process.env.GIPITY_RELAY_CLAUDE_CMD || 'gipity';
+    // resolveCommand: on Windows the bare `gipity` is a .cmd shim that spawn
+    // can't launch without an explicit path. An explicit env override is used
+    // verbatim (it may be a full path); only the default name is resolved.
+    const cmd = process.env.GIPITY_RELAY_CLAUDE_CMD || resolveCommand('gipity');
     return new Promise((resolve, reject) => {
         const child = spawn(cmd, ['sync', '--json'], {
             cwd,
@@ -901,7 +905,10 @@ async function spawnSync(cwd, timeoutMs) {
     });
 }
 export async function spawnGipityClaude(args, cwd, d) {
-    const cmd = process.env.GIPITY_RELAY_CLAUDE_CMD || 'gipity';
+    // resolveCommand: on Windows the bare `gipity` is a .cmd shim that spawn
+    // can't launch without an explicit path. An explicit env override is used
+    // verbatim (it may be a full path); only the default name is resolved.
+    const cmd = process.env.GIPITY_RELAY_CLAUDE_CMD || resolveCommand('gipity');
     // Inject stream-json flags here rather than at the call site so every
     // relay spawn path gets the same protocol. `--verbose` is required by
     // Claude Code when combining `-p` with `--output-format stream-json`.

package/dist/relay/onboarding.js

@@ -30,10 +30,13 @@ export function ensureDaemonRunning() {
     if (state.isDaemonRunning())
         return;
     try {
-        const child = spawn(resolveCliPath(), ['relay', 'run'], {
+        // Launch via the current Node binary + the CLI entry script. The previous
+        // `shell: true` on Windows ran the .js path through the shell, where the
+        // file association (Windows Script Host, not Node) would mis-handle it.
+        // process.execPath is cross-platform and needs no shell.
+        const child = spawn(process.execPath, [resolveCliPath(), 'relay', 'run'], {
             detached: true,
             stdio: 'ignore',
-            shell: process.platform === 'win32',
         });
         child.unref();
     }

package/dist/setup.js

@@ -5,6 +5,7 @@ import { resolve, join, dirname } from 'path';
 import { homedir } from 'os';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
+import { resolveCommand } from './platform.js';
 import { SKILLS_CONTENT, BUILD_VS_NON_BUILD_RULE, DEFINITION_OF_DONE } from './knowledge.js';
 export { SKILLS_CONTENT };
 /** Canonical list of workstation artifacts that are NOT part of the project.
@@ -268,11 +269,15 @@ export function ensureGipityPluginInstalled() {
     // Refresh the marketplace clone so `install` resolves the current version,
     // then (re)install at user scope - idempotent, and upgrades an older or
     // project-scoped install to the current one at user scope.
-    spawnSync('claude', ['plugin', 'marketplace', 'update', GIPITY_MARKETPLACE_NAME], {
+    // resolveCommand: on Windows `claude` is a .cmd shim that spawn can't launch
+    // without an explicit path, so resolve it (otherwise the install silently
+    // ENOENTs and the plugin's hooks never land at user scope).
+    const claudeCmd = resolveCommand('claude');
+    spawnSync(claudeCmd, ['plugin', 'marketplace', 'update', GIPITY_MARKETPLACE_NAME], {
         stdio: 'ignore',
         timeout: 120_000,
     });
-    spawnSync('claude', ['plugin', 'install', GIPITY_PLUGIN_ID, '--scope', 'user'], {
+    spawnSync(claudeCmd, ['plugin', 'install', GIPITY_PLUGIN_ID, '--scope', 'user'], {
         stdio: 'ignore',
         timeout: 120_000,
     });
@@ -478,7 +483,10 @@ export function setupGitignore() {
     const entries = ['.gipity/', '.gipity.json'];
     if (existsSync(gitignorePath)) {
         let content = readFileSync(gitignorePath, 'utf-8');
-        const lines = content.split('\n');
+        // Split on \r?\n so a CRLF .gitignore (the Windows default) doesn't leave a
+        // trailing \r on each entry - otherwise `lines.includes('.gipity/')` never
+        // matches '.gipity/\r' and every run re-appends the entries as duplicates.
+        const lines = content.split(/\r?\n/);
         const toAdd = entries.filter(e => !lines.includes(e));
         if (toAdd.length > 0) {
             content = content.trimEnd() + '\n' + toAdd.join('\n') + '\n';

package/dist/sync.js

@@ -235,6 +235,11 @@ async function downloadAll(projectGuid, onBytes) {
         });
         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);
         stream.pipe(extract);
     });
 }
@@ -579,6 +584,60 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
             deferredDeletes: 0,
         };
     }
+    // Uncertain-merge guard (armed via confirmMerge): syncing INTO a populated
+    // directory we've never synced for this project (empty baseline + local files
+    // that would upload or collide). Local-only files get pushed UP into the
+    // project and same-path differences fork into conflict copies - a two-way
+    // merge that may be unintended. Nothing here can delete.
+    //
+    // Three ways to resolve it, so both outcomes are scriptable:
+    //   --yes / autoConfirm → proceed (merge confirmed)
+    //   interactive TTY      → prompt the user
+    //   non-interactive      → fail safe: ABORT rather than merge blindly
+    if (opts.confirmMerge &&
+        remote.size > 0 && // project already has files - a real merge target
+        Object.keys(baseline.files).length === 0 && // we've never synced this folder for it
+        (planned.uploads > 0 || planned.conflicts > 0) // and local content would push up or collide
+    ) {
+        const f = (n) => `${n} file${n === 1 ? '' : 's'}`;
+        const shape = [`    Server: ${f(remote.size)}   ·   Local: ${f(local.size)}`];
+        if (planned.downloads > 0)
+            shape.push(`    ↓ download ${f(planned.downloads)} from the project into this folder`);
+        if (planned.uploads > 0)
+            shape.push(`    ↑ upload ${f(planned.uploads)} from this folder INTO the project (they become part of it)`);
+        if (planned.conflicts > 0)
+            shape.push(`    ! ${f(planned.conflicts)} differ on both sides — both kept (your copy is renamed)`);
+        const abort = () => ({
+            plan: planned, applied: 0, skipped: planned.actions.length, errors: [],
+            summary: [
+                `This folder has files that haven't been synced with this project yet — merge not confirmed.`,
+                ...shape,
+                `Re-run with --yes to merge, or sync into an empty folder.`,
+            ].join('\n'),
+            deferredDeletes: 0, aborted: true,
+        });
+        if (getAutoConfirm()) {
+            // --yes: proceed with the merge; the caller reports the applied counts.
+        }
+        else if (interactive) {
+            const answer = await prompt([
+                '',
+                `  This folder has files that haven't been synced with this project yet.`,
+                `  Syncing here MERGES the two — nothing is deleted:`,
+                '',
+                ...shape,
+                '',
+                `  Continue? [y/N]: `,
+            ].join('\n'));
+            if (!/^(y|yes|continue)$/i.test(answer.trim()))
+                return abort();
+        }
+        else {
+            // Non-interactive and not confirmed: don't silently merge a folder we
+            // weren't told to. `--yes` opts in.
+            return abort();
+        }
+    }
     // Bulk-delete guard over the *planned* deletes.
     const knownFiles = local.size + remote.size;
     const deletesOk = await bulkDeleteGuard(planned, knownFiles, { ...opts, interactive });
@@ -590,8 +649,14 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
     // ── Pre-fetch remote bytes once for all downloads (conflict-originating
     //    remote versions are fetched on demand after 409). ──
     const downloadedBytes = new Map();
-    const needsBulkDownload = plannedToApply.some(a => a.kind === 'download' || a.kind === 'conflict');
-    if (needsBulkDownload) {
+    // Set when the download phase could not retrieve every byte the plan needs.
+    // A delete is only safe against a complete, authoritative view, so an
+    // incomplete download disarms the deletes pass below - this is what breaks
+    // the "truncated pull → files missing locally → next sync deletes them"
+    // amplification loop.
+    let downloadIncomplete = false;
+    const wantedDownloads = plannedToApply.filter(a => a.kind === 'download' || a.kind === 'conflict');
+    if (wantedDownloads.length) {
         // The tree endpoint streams the *whole* remote tree as one tar (the caller
         // then picks out only the paths it planned to apply), so the bytes that
         // actually move = the sum of every remote file's size. That's the honest
@@ -609,22 +674,46 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
             : undefined;
         try {
             const all = await downloadAll(config.projectGuid, onBytes);
-            for (const a of plannedToApply) {
-                if (a.kind === 'download' || a.kind === 'conflict') {
-                    const buf = all.get(a.path);
-                    if (buf)
-                        downloadedBytes.set(a.path, buf);
-                }
+            for (const a of wantedDownloads) {
+                const buf = all.get(a.path);
+                if (buf)
+                    downloadedBytes.set(a.path, buf);
             }
         }
         catch (err) {
-            errors.push(`Download batch failed: ${err.message}`);
+            // The bulk tar can truncate mid-stream on a large project (transport or
+            // proxy timeout) and either reject here or "finish" with a partial set.
+            // Either way we fall through to the single-file recovery below rather than
+            // proceeding on a half-empty tree - a partial download must never be
+            // mistaken for a complete one.
+            errors.push(`Bulk download incomplete (${err.message}); recovering files individually…`);
         }
         finally {
             // Settle the bar even if the extracted-byte tally fell short of the
             // estimate (the live line stays open until something hits 100% or finish()).
             p?.finish();
         }
+        // Recover whatever the bulk tar dropped over the reliable single-file
+        // endpoint. This is what lets a project whose tar keeps truncating still
+        // sync to completion - and what recovers a checkout left half-downloaded by
+        // an earlier truncated pull.
+        const missing = wantedDownloads.filter(a => !downloadedBytes.has(a.path));
+        if (missing.length) {
+            p?.phase(`Recovering ${missing.length} file${missing.length === 1 ? '' : 's'} the bulk download dropped…`);
+            for (const a of missing) {
+                let buf = null;
+                for (let attempt = 0; attempt < 3 && !buf; attempt++) {
+                    buf = await fetchOne(config.projectGuid, a.path);
+                }
+                if (buf)
+                    downloadedBytes.set(a.path, buf);
+            }
+        }
+        // Anything still missing is a hard failure: the plan needs bytes we could
+        // not retrieve. Mark the download incomplete so the deletes pass is skipped;
+        // the per-path "Download missing" errors below carry the detail.
+        if (wantedDownloads.some(a => !downloadedBytes.has(a.path)))
+            downloadIncomplete = true;
     }
     // ── Writes pass: uploads, downloads, conflicts (rename + download + upload copy) ──
     // We serialize conflicts; uploads run with bounded concurrency.
@@ -911,7 +1000,17 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
         }
     }
     // ── Deletes pass ──
+    // A delete is only safe against a complete, authoritative view. If the
+    // download phase couldn't retrieve everything it planned, the local tree is
+    // not a trustworthy deletion signal - this is exactly how a truncated pull
+    // 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;
     for (const a of plannedToApply) {
+        if (downloadIncomplete && (a.kind === 'delete-local' || a.kind === 'delete-remote')) {
+            deletesSkippedIncomplete++;
+            continue;
+        }
         if (a.kind === 'delete-local') {
             try {
                 unlinkSync(resolveInRoot(root, a.path));
@@ -977,6 +1076,10 @@ async function syncInner(projectGuid, root, ignore, opts, interactive) {
             }
         }
     }
+    if (deletesSkippedIncomplete > 0) {
+        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);
     baseline.lastFullSync = new Date().toISOString();

package/dist/updater/bootstrap.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { spawnSync } from 'child_process';
 import { join } from 'path';
 import { LOCAL_DIR, LOCAL_ENTRY, LOCAL_PKG_DIR, writeState, readState } from './state.js';
+import { resolveCommand } from '../platform.js';
 export function isBootstrapped() {
     return existsSync(LOCAL_ENTRY);
 }
@@ -25,7 +26,7 @@ export function bootstrap(version, quiet = false) {
     // --ignore-scripts: don't run install lifecycle hooks (gipity ships
     // precompiled, deps need no build), so a compromised package can't execute
     // code during this self-managed install.
-    const res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
+    const res = spawnSync(resolveCommand('npm'), ['install', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
         cwd: LOCAL_DIR,
         stdio: ['ignore', 'pipe', 'pipe'],
         encoding: 'utf-8',
@@ -38,7 +39,10 @@ export function bootstrap(version, quiet = false) {
                 process.stderr.write(`gipity v${version} is not yet published to npm - using the currently installed build.\n`);
             }
             else {
-                const firstLine = stderr.split('\n').map(l => l.trim()).find(l => l.length > 0) || `npm exit ${res.status}`;
+                // res.error (e.g. ENOENT when npm can't be launched) carries the real
+                // cause; res.status is null in that case, so prefer the error message.
+                const firstLine = stderr.split('\n').map(l => l.trim()).find(l => l.length > 0)
+                    || (res.error ? res.error.message : `npm exit ${res.status}`);
                 const reason = firstLine.length > 160 ? firstLine.slice(0, 157) + '...' : firstLine;
                 process.stderr.write(`gipity: could not set up local install (${reason}). Using the currently installed build.\n`);
             }

package/dist/updater/check.js

@@ -4,6 +4,7 @@
 import { spawnSync } from 'child_process';
 import { appendFileSync, existsSync } from 'fs';
 import { LOCAL_DIR, LOCAL_ENTRY, UPDATE_LOG, readState, writeState, updatesDisabled } from './state.js';
+import { resolveCommand } from '../platform.js';
 const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000; // 4 hours
 function log(line) {
     try {
@@ -37,10 +38,12 @@ function installVersion(version) {
     // --ignore-scripts: this runs unattended in the background, so don't let a
     // compromised package's install lifecycle hooks execute. gipity ships
     // precompiled (dist/) and its deps need no build step, so nothing is lost.
-    const res = spawnSync('npm', ['install', '--silent', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
+    const res = spawnSync(resolveCommand('npm'), ['install', '--silent', '--no-audit', '--no-fund', '--ignore-scripts', `gipity@${version}`], {
         cwd: LOCAL_DIR,
         stdio: 'ignore',
     });
+    if (res.error)
+        log(`npm spawn failed: ${res.error.message}`);
     return res.status === 0 && existsSync(LOCAL_ENTRY);
 }
 export async function runCheck(opts = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.397",
+  "version": "1.0.398",
   "description": "The full-stack platform tuned for AI agents. Database, storage, auth, functions, deploy, and drop-in kits - all agent-tuned. Pair with Claude Code or use standalone.",
   "bin": {
     "gipity": "dist/updater/shim.js",
@@ -12,8 +12,9 @@
     "build": "tsc && chmod +x dist/index.js dist/gipcc.js dist/gipccd.js dist/updater/shim.js dist/updater/check.js",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
-    "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-live.test.js dist/__tests__/cli-e2e-services-media-live.test.js dist/__tests__/cli-e2e-workflow-live.test.js dist/__tests__/cli-e2e-sandbox-live.test.js dist/__tests__/cli-e2e-page-fetch-live.test.js dist/__tests__/cli-e2e-page-test-live.test.js",
+    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
+    "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-live.test.js dist/__tests__/cli-e2e-sync-live.test.js dist/__tests__/cli-e2e-services-media-live.test.js dist/__tests__/cli-e2e-workflow-live.test.js dist/__tests__/cli-e2e-sandbox-live.test.js dist/__tests__/cli-e2e-page-fetch-live.test.js dist/__tests__/cli-e2e-page-test-live.test.js",
+    "test:e2e:sync": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sync-live.test.js",
     "test:e2e:sandbox": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sandbox-live.test.js"
   },
   "dependencies": {