gipity 1.0.413 → 1.0.414

package/dist/api.js

@@ -211,6 +211,51 @@ export async function download(path, retried = false) {
     }
     return Buffer.from(await res.arrayBuffer());
 }
+/** Download raw bytes plus the response headers - for binary endpoints whose
+ *  metadata rides headers (e.g. `GET /projects/:guid/export`, where
+ *  `X-Gip-Skipped` and the Content-Disposition filename matter to the caller).
+ *  Non-2xx responses are parsed as standard JSON errors. */
+export async function downloadWithHeaders(path, retried = false) {
+    const url = `${baseUrl()}${path}`;
+    const res = await fetch(url, {
+        headers: { ...clientHeaders(), 'Authorization': `Bearer ${await bearerToken()}` },
+    });
+    if (await shouldRetryAfter401(res.status, retried)) {
+        return downloadWithHeaders(path, true);
+    }
+    if (!res.ok) {
+        const json = await res.json().catch(() => ({ error: { code: 'UNKNOWN', message: res.statusText } }));
+        const err = json.error || { code: 'UNKNOWN', message: res.statusText };
+        throw new ApiError(res.status, err.code, with401Hint(res.status, err.message), json.data);
+    }
+    return { buffer: Buffer.from(await res.arrayBuffer()), headers: res.headers };
+}
+/** POST raw bytes (e.g. a .gip bundle) and parse the JSON response, returning
+ *  the HTTP status alongside it so callers can tell a clean 201 from a 207
+ *  partial success. The timeout scales with the body size (same policy as the
+ *  presigned PUT path) so a large-but-progressing upload isn't cut off. */
+export async function postBinary(path, body, contentType = 'application/zip', retried = false) {
+    const url = `${baseUrl()}${path}`;
+    const headers = {
+        ...clientHeaders(),
+        'Authorization': `Bearer ${await bearerToken()}`,
+        'Content-Type': contentType,
+    };
+    const res = await fetchWithTimeout(url, {
+        method: 'POST',
+        headers,
+        body: new Uint8Array(body),
+    }, putTimeoutMs(body.length), `POST ${path}`);
+    if (await shouldRetryAfter401(res.status, retried)) {
+        return postBinary(path, body, contentType, true);
+    }
+    if (!res.ok) {
+        const json = await res.json().catch(() => ({ error: { code: 'UNKNOWN', message: res.statusText } }));
+        const err = json.error || { code: 'UNKNOWN', message: res.statusText };
+        throw new ApiError(res.status, err.code, with401Hint(res.status, err.message), json.data);
+    }
+    return { status: res.status, json: await res.json() };
+}
 /** Download a response as a Node.js Readable stream */
 export async function downloadStream(path, retried = false) {
     const { Readable } = await import('stream');

package/dist/client-context.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
-function cliVersion() {
+export function cliVersion() {
     try {
         const dir = dirname(fileURLToPath(import.meta.url));
         const pkg = JSON.parse(readFileSync(resolve(dir, '../package.json'), 'utf-8'));

package/dist/commands/github.js

@@ -0,0 +1,80 @@
+/**
+ * `gipity github <connect|status|repos|disconnect>` - manage the GitHub
+ * connection that powers `gipity load github:owner/repo`.
+ *
+ * Connect uses the GitHub App install flow: the URL is GitHub's own repo
+ * picker, so the user chooses exactly which repositories Gipity can read.
+ * Re-running connect doubles as the "grant more repositories" flow.
+ */
+import { Command } from 'commander';
+import { get, post } from '../api.js';
+import { brand, bold, muted } from '../colors.js';
+import { run, printList, printResult } from '../helpers/index.js';
+export const githubCommand = new Command('github')
+    .description('Connect GitHub for repo imports')
+    .addHelpText('after', '\nConnect once, then import any shared repo with `gipity load github:owner/repo`.');
+githubCommand
+    .command('connect')
+    .description('Connect your GitHub account - prints a link; GitHub lets you pick which repositories to share')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Connect', async () => {
+    const res = await get('/services/github/authorize');
+    if (opts.json) {
+        console.log(JSON.stringify({ url: res.url }));
+        return;
+    }
+    console.log('Open this link in your browser to connect GitHub - GitHub lets you pick which repositories to share:\n');
+    console.log(brand(res.url));
+    console.log(muted('\nWhen done, run `gipity github status` to confirm.'));
+    console.log(muted('Re-run `gipity github connect` any time to grant more repositories.'));
+}));
+githubCommand
+    .command('status', { isDefault: true })
+    .description('Show whether GitHub is connected')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Status', async () => {
+    const res = await get('/services/github/status');
+    if (opts.json) {
+        console.log(JSON.stringify(res.data));
+        return;
+    }
+    const s = res.data;
+    if (!s.connected) {
+        console.log('GitHub: not connected. Run `gipity github connect` to set it up.');
+        return;
+    }
+    console.log(`GitHub: ${bold('connected')}`);
+    if (s.email)
+        console.log(`  Account:   ${s.email}`);
+    if (s.connectedAt)
+        console.log(`  Connected: ${new Date(s.connectedAt).toLocaleDateString()}`);
+    console.log(muted('\nList reachable repositories with `gipity github repos`.'));
+    console.log(muted('Import one with `gipity load github:owner/repo`.'));
+}));
+githubCommand
+    .command('repos')
+    .description('List the repositories your GitHub connection can reach')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Repos', async () => {
+    const res = await get('/services/github/repos').catch((err) => {
+        if (err?.code === 'NOT_CONNECTED') {
+            throw new Error('GitHub is not connected - run `gipity github connect` first.');
+        }
+        throw err;
+    });
+    const width = res.data.length ? Math.max(...res.data.map(r => r.full_name.length)) : 0;
+    printList(res.data, opts, 'No repositories shared yet - run `gipity github connect` to grant some.', r => {
+        const vis = r.private ? 'private' : 'public ';
+        const desc = r.description ? `  ${muted(r.description)}` : '';
+        return `${r.full_name.padEnd(width)}  ${muted(vis)}  ${r.default_branch}${desc}`;
+    });
+}));
+githubCommand
+    .command('disconnect')
+    .description('Disconnect GitHub (imports via github: sources will stop working)')
+    .option('--json', 'Output as JSON')
+    .action((opts) => run('Disconnect', async () => {
+    await post('/services/github/disconnect');
+    printResult('GitHub disconnected.', opts, { disconnected: true });
+}));
+//# sourceMappingURL=github.js.map

package/dist/commands/load.js

@@ -0,0 +1,221 @@
+/**
+ * `gipity load <source>` - create a brand-new project from a .gip bundle or
+ * a GitHub repository.
+ *
+ * The counterpart of `gipity save`. Load ALWAYS creates a new project (the
+ * server retries slug collisions); it never merges into an existing one. Use
+ * `--inspect` to peek inside a source - metadata, contents, deploy phases,
+ * and each function's permission surface - without creating anything.
+ *
+ * Sources:
+ * - a local .gip file (from `gipity save`) - uploaded as raw zip bytes
+ * - `github:owner/repo[/sub/path][@ref]` or a github.com URL - resolved
+ *   server-side through the user's GitHub connection (`gipity github connect`);
+ *   the CLI sends a JSON `{source}` body, no repo bytes travel through the
+ *   client. Both transports feed the same import pipeline and response shapes.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Command } from 'commander';
+import { get, post, postBinary, getAccountSlug } from '../api.js';
+import { success, muted, warning, bold, info, brand } from '../colors.js';
+import { run } from '../helpers/index.js';
+import { withSpinner } from '../progress.js';
+import { formatBytes } from '../adopt-cwd.js';
+import { getProjectsRoot } from '../relay/paths.js';
+import { finalizeLocalProject } from '../project-setup.js';
+/** Server transport cap for a .gip upload - checked locally first so a too-big
+ *  bundle fails in milliseconds instead of after a full upload. */
+const MAX_BUNDLE_BYTES = 200 * 1024 * 1024;
+/** A source the server resolves via the user's GitHub connection: the
+ *  `github:owner/repo[/sub/path][@ref]` shorthand or a github.com URL. */
+function isGithubSource(source) {
+    return /^github:/i.test(source) || /^https?:\/\/(www\.)?github\.com\//i.test(source);
+}
+/** Append the recovery path when a GitHub-source call fails because the repo
+ *  isn't reachable through the user's connection (not connected, or connected
+ *  but this repo wasn't granted). The server's message names the problem; the
+ *  hint names the fix. Re-throws always. */
+function rethrowWithConnectHint(err) {
+    const e = err;
+    const msg = e?.message ?? '';
+    if (e?.code === 'NOT_CONNECTED' || /not covered by your GitHub connection|connect github/i.test(msg)) {
+        e.message = `${msg}\nRun \`gipity github connect\` to connect GitHub - re-run it any time to grant more repositories.`;
+    }
+    throw err;
+}
+function readBundle(source) {
+    const resolved = path.resolve(source.startsWith('~') ? os.homedir() + source.slice(1) : source);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Bundle not found: ${resolved}`);
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        throw new Error(`${resolved} is a directory - pass a .gip file (create one with \`gipity save\`) or a github: source.`);
+    }
+    if (stat.size > MAX_BUNDLE_BYTES) {
+        throw new Error(`Bundle is ${formatBytes(stat.size)} - over the ${formatBytes(MAX_BUNDLE_BYTES)} upload cap. Move large assets to Gipity Storage and re-save.`);
+    }
+    return { resolved, buffer: fs.readFileSync(resolved) };
+}
+/** Manifest permission surface, one line per function - what an importing user
+ *  needs to see before trusting a bundle. */
+function printManifest(m) {
+    if (!m.found) {
+        console.log(muted('No gipity.yaml in the source - static app (files deploy only).'));
+        return;
+    }
+    if (!m.valid) {
+        console.log(warning(`gipity.yaml is present but invalid: ${m.error ?? 'unparseable'}`));
+        return;
+    }
+    console.log(`Deploy phases: ${m.phases.map(p => `${p.name} (${p.type})`).join(', ') || 'none'}`);
+    console.log(`Database:      ${m.hasDatabase ? 'yes' : 'no'}`);
+    if (m.functions.length) {
+        console.log('');
+        console.log(bold('Functions and permissions:'));
+        const width = Math.max(...m.functions.map(f => f.name.length));
+        for (const f of m.functions) {
+            const parts = [`auth=${f.auth ?? 'public'}`];
+            if (f.tables?.length)
+                parts.push(`tables=${f.tables.join(',')}`);
+            if (f.fetch_domains?.length)
+                parts.push(`fetch=${f.fetch_domains.join(',')}`);
+            if (f.services?.length)
+                parts.push(`services=${f.services.join(',')}`);
+            console.log(`  ${f.name.padEnd(width)}  ${muted(parts.join('  '))}`);
+        }
+    }
+}
+function printInspect(d, source) {
+    if (d.meta) {
+        console.log(bold(d.meta.name));
+        if (d.meta.description)
+            console.log(muted(d.meta.description));
+        console.log(`Source:    project ${d.meta.source_project}, exported ${d.meta.exported_at}`);
+    }
+    else {
+        console.log(bold(isGithubSource(source) ? source : path.basename(source)));
+        console.log(muted('No Gipity bundle metadata - imports as a plain file tree.'));
+    }
+    console.log(`Contents:  ${d.fileCount} file(s), ${formatBytes(d.totalBytes)}`);
+    console.log(`Top level: ${d.topLevel.join(', ') || '(empty)'}`);
+    console.log('');
+    printManifest(d.manifest);
+    console.log('');
+    console.log(muted('Load it with `gipity load ' + source + '` - always creates a NEW project.'));
+}
+export const loadCommand = new Command('load')
+    .description('Create a new app from a .gip bundle or a GitHub repo')
+    .argument('<source>', 'A .gip file (from `gipity save`), github:owner/repo[/sub/path][@ref], or a github.com URL')
+    .option('--name <name>', 'Name for the new project (default: the source\'s saved name)')
+    .option('--inspect', 'Peek inside the source - contents, deploy phases, function permissions - without creating anything')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', '\nLoad always creates a NEW project - it never merges into an existing one.'
+    + '\nGitHub sources need a one-time `gipity github connect` (re-run it to grant more repos).')
+    .action((source, opts) => run('Load', async () => {
+    const github = isGithubSource(source);
+    if (!github && /^https?:\/\//i.test(source)) {
+        throw new Error('Only GitHub URLs are supported for now - pass github:owner/repo, a github.com URL, or a local .gip file.');
+    }
+    // Local .gip bundles upload raw zip bytes; GitHub sources send a tiny JSON
+    // body and the server pulls the tree through the user's connection.
+    let sourceLabel;
+    let doInspect;
+    let doImport;
+    if (github) {
+        sourceLabel = source;
+        doInspect = () => post('/projects/inspect', { source }).catch(rethrowWithConnectHint);
+        doImport = async () => {
+            const body = { source };
+            if (opts.name)
+                body.name = opts.name;
+            const res = await post('/projects/import', body).catch(rethrowWithConnectHint);
+            // The JSON helper hides the 201-vs-207 status; `failed` carries the
+            // same signal (the server only sets it on a partial write).
+            return { data: res.data, partial: !!res.data.failed?.length };
+        };
+    }
+    else {
+        const { resolved, buffer } = readBundle(source);
+        sourceLabel = path.basename(resolved);
+        doInspect = async () => (await postBinary('/projects/inspect', buffer)).json;
+        doImport = async () => {
+            const qs = new URLSearchParams();
+            if (opts.name)
+                qs.set('name', opts.name);
+            const { status, json } = await postBinary(`/projects/import${qs.size ? `?${qs}` : ''}`, buffer);
+            return { data: json.data, partial: status === 207 };
+        };
+    }
+    if (opts.inspect) {
+        const res = opts.json
+            ? await doInspect()
+            : await withSpinner('Inspecting…', doInspect, { done: null });
+        if (opts.json) {
+            console.log(JSON.stringify(res.data));
+            return;
+        }
+        printInspect(res.data, source);
+        return;
+    }
+    const { data, partial } = opts.json
+        ? await doImport()
+        : await withSpinner('Importing…', doImport, { done: null });
+    const project = data.project;
+    // Materialize a local dir and link it, exactly like `gipity project create`:
+    // `.gipity.json` is written directly inside the new dir, then a soft sync
+    // pulls the imported files down.
+    const dir = path.join(getProjectsRoot(), project.slug);
+    fs.mkdirSync(dir, { recursive: true });
+    const accountSlug = await getAccountSlug();
+    // Resolve the first assigned agent (if any) - not fatal if missing.
+    let agentGuid = '';
+    try {
+        const agents = await get(`/projects/${project.short_guid}/agents`);
+        if (agents.data.length > 0)
+            agentGuid = agents.data[0].short_guid;
+    }
+    catch {
+        // offline or no agents - non-fatal
+    }
+    const { applied } = await finalizeLocalProject({
+        dir,
+        projectGuid: project.short_guid,
+        projectSlug: project.slug,
+        projectName: project.name,
+        accountSlug,
+        agentGuid,
+        sync: 'soft',
+        interactive: false,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify({
+            created: project.slug,
+            name: project.name,
+            guid: project.short_guid,
+            dir,
+            written: data.written,
+            failed: data.failed,
+            partial,
+            applied,
+        }));
+        return;
+    }
+    console.log(success(`Created "${project.name}" (${project.slug}) from ${sourceLabel}`));
+    console.log(`Wrote ${data.written} file(s) to the new project.`);
+    console.log(`Initialized ${info(dir)}`);
+    if (applied > 0)
+        console.log(`Pulled ${applied} file(s) to local.`);
+    if (partial || data.failed?.length) {
+        console.log('');
+        console.warn(warning(`Partial import - ${data.failed?.length ?? 0} file(s) could not be written:`));
+        for (const f of data.failed ?? [])
+            console.warn(warning(`  ! ${f.path}: ${f.error}`));
+        console.warn(warning('The project was still created and linked; the files above are missing from it.'));
+    }
+    console.log('');
+    console.log(`${muted('Next:')} cd ${dir} && ${brand('gipity deploy dev')}`);
+}));
+//# sourceMappingURL=load.js.map

package/dist/commands/relay.js

@@ -225,6 +225,35 @@ relayCommand
     state.setPaused(false);
     console.log(success('Resumed.'));
 });
+// ─── gipity relay diagnostics [on|off] ─────────────────────────────────
+relayCommand
+    .command('diagnostics [state]')
+    .description('View or set sharing of anonymous host/version diagnostics (on|off)')
+    .action((arg) => {
+    if (arg === undefined) {
+        const stored = state.getDiagnosticsConsent();
+        const effective = state.diagnosticsConsented();
+        const label = stored === undefined ? 'on (default, not yet chosen)' : stored ? 'on' : 'off';
+        console.log(`Diagnostics sharing: ${effective ? success(label) : muted(label)}`);
+        if (effective !== (stored !== false)) {
+            console.log(muted('  (overridden off by GIPITY_NO_DIAGNOSTICS / DO_NOT_TRACK)'));
+        }
+        console.log(muted('  Non-PII only: CPU/GPU/memory/disk specs, OS + tool versions. No file paths, hostname, or username.'));
+        console.log(muted('  Set with `gipity relay diagnostics on` / `gipity relay diagnostics off`.'));
+        return;
+    }
+    const on = /^(on|true|yes|1|enable)$/i.test(arg);
+    const off = /^(off|false|no|0|disable)$/i.test(arg);
+    if (!on && !off) {
+        console.log(clrError("Expected 'on' or 'off'."));
+        process.exitCode = 1;
+        return;
+    }
+    state.setDiagnosticsConsent(on);
+    console.log(on
+        ? `${success('Diagnostics sharing on.')} ${muted('Reported on the next daily heartbeat.')}`
+        : `${success('Diagnostics sharing off.')} ${muted('No host/version data will be sent.')}`);
+});
 // ─── gipity relay rename <name> ────────────────────────────────────────
 relayCommand
     .command('rename <new-name>')

package/dist/commands/save.js

@@ -0,0 +1,90 @@
+/**
+ * `gipity save [output]` - export the linked project as a portable .gip bundle.
+ *
+ * A .gip is a zip of the project's file tree plus a reserved
+ * `_gip/manifest.json` metadata entry. It pairs with `gipity load`, which
+ * creates a brand-new project from a bundle. Code-only: secrets, custom
+ * domains, chats, and database rows are never in a .gip.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { Command } from 'commander';
+import { downloadWithHeaders } from '../api.js';
+import { requireConfig } from '../config.js';
+import { success, muted, warning } from '../colors.js';
+import { run } from '../helpers/index.js';
+import { withSpinner } from '../progress.js';
+import { formatBytes } from '../adopt-cwd.js';
+/** Count archive entries by reading the zip end-of-central-directory record -
+ *  cheap (no inflation, no dependency) and good enough for a summary line.
+ *  Returns null when the record can't be found or the count is zip64-saturated,
+ *  in which case the line is simply omitted. */
+export function zipEntryCount(buf) {
+    const EOCD_SIG = 0x06054b50;
+    const MIN_EOCD = 22; // fixed EOCD size with an empty comment
+    if (buf.length < MIN_EOCD)
+        return null;
+    // The EOCD sits at the end, preceded only by an optional comment (<= 64KB).
+    const floor = Math.max(0, buf.length - MIN_EOCD - 0xffff);
+    for (let i = buf.length - MIN_EOCD; i >= floor; i--) {
+        if (buf.readUInt32LE(i) === EOCD_SIG) {
+            const n = buf.readUInt16LE(i + 10); // total central-directory records
+            return n === 0xffff ? null : n;
+        }
+    }
+    return null;
+}
+/** Pull the server's suggested filename out of Content-Disposition
+ *  (`attachment; filename="<slug>.gip"`). The server slug is fresher than the
+ *  locally cached one if the project was renamed. */
+function dispositionFilename(headers) {
+    const m = /filename="([^"]+)"/.exec(headers.get('content-disposition') ?? '');
+    return m ? m[1] : null;
+}
+export const saveCommand = new Command('save')
+    .description('Save this app as a portable .gip bundle')
+    .argument('[output]', 'Output .gip path, or a directory to write <slug>.gip into (default: ./<slug>.gip)')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', '\nRestore anywhere with `gipity load <file>.gip` - it always creates a NEW project.')
+    .action((output, opts) => run('Save', async () => {
+    const config = requireConfig();
+    const doExport = () => downloadWithHeaders(`/projects/${config.projectGuid}/export`);
+    const { buffer, headers } = opts.json
+        ? await doExport()
+        : await withSpinner('Exporting…', doExport, { done: null });
+    const filename = dispositionFilename(headers) ?? `${config.projectSlug}.gip`;
+    let dest = path.resolve(output ?? filename);
+    if (output && fs.existsSync(dest) && fs.statSync(dest).isDirectory()) {
+        dest = path.join(dest, filename);
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, buffer);
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    const skipped = Number(headers.get('x-gip-skipped') ?? 0);
+    const entries = zipEntryCount(buffer);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            path: dest,
+            bytes: buffer.length,
+            sha256,
+            ...(entries !== null ? { entries } : {}),
+            skipped,
+        }));
+        return;
+    }
+    console.log(success(`Saved ${path.basename(dest)}`));
+    console.log(`  Path:     ${dest}`);
+    console.log(`  Size:     ${formatBytes(buffer.length)}`);
+    if (entries !== null)
+        console.log(`  Entries:  ${entries} (including the bundle manifest)`);
+    console.log(`  SHA-256:  ${sha256}`);
+    if (skipped > 0) {
+        console.log('');
+        console.warn(warning(`${skipped} file(s) were skipped (unreadable or over 100 MB) - this bundle is partial.`));
+        console.warn(warning('Large assets belong in Gipity Storage, not in a code bundle.'));
+    }
+    console.log('');
+    console.log(muted('Restore anywhere with `gipity load ' + path.basename(dest) + '` (creates a new project).'));
+}));
+//# sourceMappingURL=save.js.map

package/dist/commands/status.js

@@ -5,7 +5,7 @@ import { homedir } from 'os';
 import { getAuth, sessionExpired } from '../auth.js';
 import { getConfig, liveUrl } from '../config.js';
 import { brand, success, warning, muted, error as clrError } from '../colors.js';
-import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, setupClaudeHooks, ensureGipityPlugin, ensureGipityPluginInstalled, userScopePluginCurrent } from '../setup.js';
+import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, setupClaudeHooks, ensureGipityPlugin, ensureGipityPluginInstalled, userScopeInstallState } from '../setup.js';
 /** Hooks ship in the Gipity Claude Code plugin now. "Installed" means three
  *  things must all hold: the user-scope settings register the marketplace and
  *  enable the plugin (declarative), AND Claude Code actually has a user-scope
@@ -27,9 +27,15 @@ function checkGipityPlugin() {
         missing.push('marketplace');
     if (settings?.enabledPlugins?.[GIPITY_PLUGIN_ID] !== true)
         missing.push('plugin');
-    if (!userScopePluginCurrent())
+    const install = userScopeInstallState();
+    if (!install.current)
         missing.push('install');
-    return { missing, ok: missing.length === 0 };
+    // "stale" = declaratively enabled AND a user-scope install exists; it's just
+    // behind the version this CLI needs. The hooks still LOAD (at the old
+    // version), so this is a version-lag update, not a dead plugin - don't warn
+    // as if files aren't syncing at all. Only true when `install` is the sole gap.
+    const stale = missing.length === 1 && missing[0] === 'install' && install.exists;
+    return { missing, ok: missing.length === 0, stale };
 }
 export const statusCommand = new Command('status')
     .description('Show project and login status')
@@ -89,13 +95,28 @@ export const statusCommand = new Command('status')
             ensureGipityPlugin(true);
             setupClaudeHooks();
             // Re-enabling the declarative keys isn't enough on CC >=2.1.x - also
-            // materialize the user-scope install so the hooks actually load.
+            // materialize (or update) the user-scope install so the hooks load.
             ensureGipityPluginInstalled();
-            console.log(`${muted('Hooks:')}   ${success('repaired - Gipity plugin re-enabled')}`);
+            // Re-check rather than claim success blindly: a stale user-scope
+            // install only advances via `plugin update`, and if `claude` is off
+            // PATH nothing changed at all - reporting "repaired" then would be a
+            // lie the next `gipity status` immediately contradicts.
+            const after = checkGipityPlugin();
+            if (after.ok) {
+                console.log(`${muted('Hooks:')}   ${success('repaired - Gipity plugin enabled')}`);
+            }
+            else {
+                console.log(`${muted('Hooks:')}   ${warning(`repair incomplete (still missing: ${after.missing.join(', ')})`)}`);
+                console.log(muted('Ensure `claude` is on PATH, then re-run. Restart Claude Code to load the update.'));
+            }
+        }
+        else if (hookCheck.stale) {
+            console.log(`${muted('Hooks:')}   ${warning('Gipity plugin out of date (an update is available)')}`);
+            console.log(muted('Hooks still load, but run `gipity status --repair-hooks` to update to the latest.'));
         }
         else {
             console.log(`${muted('Hooks:')}   ${warning(`Gipity plugin not enabled (missing: ${hookCheck.missing.join(', ')})`)}`);
-            console.log(muted('Run `gipity status --repair-hooks` to re-enable.'));
+            console.log(muted('Run `gipity status --repair-hooks` to enable.'));
             console.log(muted('Without it, files don\'t auto-sync and web CLI dispatches can\'t show Claude Code output.'));
         }
     }

package/dist/index.js

@@ -30,6 +30,8 @@ import { storageCommand } from './commands/storage.js';
 import { claudeCommand } from './commands/claude.js';
 import { addCommand } from './commands/add.js';
 import { removeCommand } from './commands/remove.js';
+import { saveCommand } from './commands/save.js';
+import { loadCommand } from './commands/load.js';
 import { logsCommand } from './commands/logs.js';
 import { pageCommand } from './commands/page.js';
 import { recordsCommand } from './commands/records.js';
@@ -39,6 +41,7 @@ import { secretsCommand } from './commands/secrets.js';
 import { notifyCommand } from './commands/notify.js';
 import { bugCommand } from './commands/bug.js';
 import { paymentsCommand } from './commands/payments.js';
+import { githubCommand } from './commands/github.js';
 import { jobCommand } from './commands/job.js';
 import { rbacCommand } from './commands/rbac.js';
 import { auditCommand } from './commands/audit.js';
@@ -125,11 +128,11 @@ const program = new Command();
 // --from Y`). enablePositionalOptions draws the boundary at the first command.
 program.enablePositionalOptions();
 // ── Command groups (logical ordering within each) ──────────────────────
-const commonGroup = [skillCommand, projectCommand, addCommand, removeCommand, deployCommand];
+const commonGroup = [skillCommand, projectCommand, addCommand, removeCommand, saveCommand, loadCommand, deployCommand];
 const connectGroup = [claudeCommand, setupCommand, relayCommand];
 const projectGroup = [domainCommand, statusCommand, initCommand];
 const filesGroup = [fileCommand, storageCommand, syncCommand, pushCommand, uploadCommand];
-const appBuildingGroup = [testCommand, fnCommand, serviceCommand, secretsCommand, notifyCommand, paymentsCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
+const appBuildingGroup = [testCommand, fnCommand, serviceCommand, secretsCommand, notifyCommand, paymentsCommand, githubCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
 const utilitiesGroup = [pageCommand, sandboxCommand, generateCommand, emailCommand, gmailCommand, locationCommand, textCommand];
 const agentGroup = [chatCommand, memoryCommand, agentCommand, approvalCommand, bugCommand];
 const setupGroup = [loginCommand, logoutCommand, tokenCommand, creditsCommand, doctorCommand, updateCommand, uninstallCommand];

package/dist/knowledge.js

@@ -108,6 +108,7 @@ mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <s
 
 Key commands: \`gipity add <template|kit>\`, \`gipity deploy dev\`, \`gipity sandbox run\`, \`gipity page inspect <url>\`, \`gipity page screenshot <url>\`, \`gipity db query "SQL"\`, \`gipity fn call <name>\`, \`gipity logs fn <name>\`, \`gipity secrets set <NAME> <value> [--account]\` (store an API key/token encrypted; read in functions via \`secrets.get('NAME')\` — never hardcode keys), \`gipity email send --to <addr> --subject <s> --body <b>\` (sends as \`gipity@gipity.ai\`; omit \`--to\` to self-send), \`gipity skill read <name>\`.
 Pull an existing remote project local (given its URL/slug): \`mkdir -p ~/GipityProjects/<slug> && cd ~/GipityProjects/<slug> && gipity init <slug>\` (adopts the matching project and syncs files down - this is the "clone").
+Move whole apps in/out: \`gipity save\` (export this project as a portable \`.gip\` bundle), \`gipity load <file.gip | github:owner/repo>\` (import as a NEW project; \`--inspect\` to preview), \`gipity github connect\` (1-2 click GitHub access for imports). Porting a Vercel/Replit/Lovable app? Load the \`app-import\` skill first.
 For deterministic text questions (letter/word counts, substring occurrences, nth word/char, anagrams), use \`gipity text analyze "<text>"\` - local and instant, no sandbox or LLM needed.
 Hit a platform bug or friction? File it in real time: \`gipity bug report --category <cli|deploy|template|kit|db|docs|skill|service|sandbox|other> --severity <S1|S2|S3|S4> --summary "<7 words max>" [--detail "<what failed + workaround>"]\` (see below).
 Run \`gipity --help\` for the full list. Use \`--help\` on any command for details.
@@ -180,6 +181,7 @@ App development skills:
 - \`app-database\` - app Postgres database: migrations, the db helper, transactions, table permissions
 - \`app-debugging\` - debug a deployed app: page inspect/eval, screenshots, function logs
 - \`app-development\` - functions, database, and API
+- \`app-import\` - import apps from GitHub/.gip bundles (incl. Vercel/Replit/Lovable porting) and export any project as a portable .gip - app_import tool, gipity save/load
 - \`app-testing\` - testing deployed app functions (ctx.fn.call/callAs, the isolated test DB)
 - \`deploy\` - the deploy pipeline & gipity.yaml manifest
 - \`jobs\` - long-running CPU + GPU compute jobs (Python / Node / bash)

package/dist/relay/agent-token.js

@@ -19,6 +19,11 @@ import { hostname } from 'os';
 import { post, del } from '../api.js';
 import { resolveApiBase } from '../config.js';
 import * as state from './state.js';
+/** Relay agent tokens carry a finite expiry so an orphaned one - left behind
+ *  when a user deletes ~/.gipity by hand, losing the guid we'd revoke it with -
+ *  self-expires instead of living forever. A live relay is unaffected:
+ *  ensureRelayAgentToken() re-mints on the first 401 after expiry. */
+const RELAY_AGENT_TOKEN_EXPIRY_DAYS = 60;
 /** Validate a stored token against the API. Only a definitive 401 counts as
  *  invalid - transient failures (network, 5xx) must not discard a good token
  *  and trigger a re-mint storm. */
@@ -48,7 +53,7 @@ export async function ensureRelayAgentToken() {
     }
     try {
         const name = `Relay on ${state.getDevice()?.name ?? hostname()}`;
-        const res = await post('/auth/agent-tokens', { name });
+        const res = await post('/auth/agent-tokens', { name, expiresInDays: RELAY_AGENT_TOKEN_EXPIRY_DAYS });
         state.setAgentToken(res.data.token, res.data.shortGuid);
         return res.data.token;
     }

package/dist/relay/daemon.js

@@ -18,6 +18,7 @@ import { deviceFetch, bridgeAbort as bridgeAbortImpl } from './device-http.js';
 import { ensureRelayAgentToken } from './agent-token.js';
 import { redactEntries, redactString, normalizeSecrets } from './redact.js';
 import { getMachineId } from './machine-id.js';
+import { collectDiagnostics } from './diagnostics.js';
 // Re-exported so the existing `relay-bridge-abort.test.ts` keeps working.
 // New callers should import from device-http.js directly.
 export const bridgeAbort = bridgeAbortImpl;
@@ -28,6 +29,10 @@ export const RELAY_LOG_PATH = join(homedir(), '.gipity', 'relay.log');
 // slightly after its own deadline; we accept that. Values can be overridden
 // by env for tests.
 const HEARTBEAT_INTERVAL_MS = parseInt(process.env.GIPITY_RELAY_HEARTBEAT_MS || '60000', 10);
+// How often the heartbeat carries a fresh diagnostics snapshot (host specs +
+// versions). The 60s liveness ping stays bare; only this cadence runs the
+// costlier version/GPU probes. First tick fires immediately at daemon start.
+const DIAGNOSTICS_INTERVAL_MS = parseInt(process.env.GIPITY_RELAY_DIAGNOSTICS_MS || String(24 * 60 * 60 * 1000), 10);
 const LONG_POLL_TIMEOUT_MS = parseInt(process.env.GIPITY_RELAY_POLL_TIMEOUT_MS || '35000', 10);
 const BACKOFF_BASE_MS = parseInt(process.env.GIPITY_RELAY_BACKOFF_BASE_MS || '1000', 10);
 const BACKOFF_MAX_MS = parseInt(process.env.GIPITY_RELAY_BACKOFF_MAX_MS || '30000', 10);
@@ -284,9 +289,24 @@ async function heartbeatLoop(ctx) {
     // Log the "session expired" warning only on the transition into that state,
     // not every 60s, so a genuinely-lapsed session doesn't spam the relay log.
     let sessionWarnLogged = false;
+    // Diagnostics: attach a fresh snapshot on the first heartbeat and every
+    // DIAGNOSTICS_INTERVAL_MS after, but only if the user consented. Between
+    // refreshes the heartbeat is a bare liveness ping.
+    let lastDiagnosticsAt = 0;
     while (!ctx.abort.signal.aborted) {
         try {
-            const r = await deviceFetch('POST', '/remote-devices/heartbeat', {}, 10_000, ctx.abort.signal);
+            let body = {};
+            if (state.diagnosticsConsented() && Date.now() - lastDiagnosticsAt >= DIAGNOSTICS_INTERVAL_MS) {
+                try {
+                    body = { diagnostics: await collectDiagnostics() };
+                    lastDiagnosticsAt = Date.now();
+                }
+                catch (err) {
+                    // Never let a diagnostics probe failure block the liveness ping.
+                    log('debug', 'diagnostics collection failed', { err: err?.message });
+                }
+            }
+            const r = await deviceFetch('POST', '/remote-devices/heartbeat', body, 10_000, ctx.abort.signal);
             if (r.status === 401) {
                 log('warn', 'heartbeat 401 - device revoked, exiting clean');
                 ctx.abort.abort('revoked');

package/dist/relay/diagnostics.js

@@ -0,0 +1,173 @@
+/**
+ * Relay diagnostics snapshot: non-PII host + version telemetry the daemon
+ * reports on its heartbeat (once at startup, then ~daily). Sent as the
+ * heartbeat body `{ diagnostics }` and stored on the server as
+ * `remote_devices.diagnostics` (JSONB); the web client surfaces it in the
+ * Relays table (versions inline, host specs on hover).
+ *
+ * Design rules:
+ *   - EVERY probe is best-effort: a failure yields undefined/null for that
+ *     field, never a thrown error. `collectDiagnostics()` always resolves.
+ *   - NO personally-identifying data: no paths, no hostname, no username -
+ *     only counts and non-identifying machine specs.
+ *   - Cheap in-memory `os.*` reads are gathered inline; the costlier probes
+ *     (agent `--version` subprocesses, GPU detection) are bounded with a short
+ *     timeout and only run when the daemon refreshes the snapshot (startup +
+ *     ~daily), never on the plain 60s liveness ping.
+ *
+ * Wire shape mirrors packages/shared `RelayDiagnostics` on the platform side.
+ */
+import { cpus, freemem, totalmem, loadavg, release, uptime, homedir } from 'os';
+import { statfsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { resolveCommand, spawnCommand } from '../platform.js';
+import { cliVersion } from '../client-context.js';
+const PROBE_TIMEOUT_MS = 4000;
+/** Extract a semver-ish token from a `--version` line ("2.0.14 (Claude Code)"
+ *  → "2.0.14"). Returns undefined when nothing version-like is present.
+ *  Exported for unit tests. */
+export function parseVersion(out) {
+    const m = out.match(/\d+\.\d+(?:\.\d+)?(?:[-.\w]*)?/);
+    return m ? m[0] : undefined;
+}
+/**
+ * Run a command and capture stdout, ASYNC + non-blocking with a hard timeout.
+ * This must not be `spawnSync`: `collectDiagnostics()` runs inside the daemon's
+ * heartbeat loop, which shares one event loop with the dispatch + cancellation
+ * loops - a synchronous spawn would freeze all of them for the probe's
+ * duration. Resolves '' on spawn error, timeout (child SIGKILL'd), or non-zero
+ * exit with no output; never rejects.
+ */
+function runProbe(cmd, args) {
+    return new Promise((resolve) => {
+        let out = '';
+        let settled = false;
+        const done = (s) => { if (!settled) {
+            settled = true;
+            resolve(s);
+        } };
+        let child;
+        try {
+            child = spawnCommand(resolveCommand(cmd), args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        }
+        catch {
+            return done('');
+        }
+        const timer = setTimeout(() => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* gone */ } done(out); }, PROBE_TIMEOUT_MS);
+        child.stdout?.on('data', (d) => { out += d.toString(); });
+        child.on('error', () => { clearTimeout(timer); done(''); });
+        child.on('close', () => { clearTimeout(timer); done(out); });
+    });
+}
+/** Run `<cmd> --version` (bounded, best-effort). undefined if the command is
+ *  absent, errors, or prints nothing version-like. */
+async function probeVersion(cmd) {
+    return parseVersion(await runProbe(cmd, ['--version']));
+}
+/** Best-effort GPU description. Short-timeout, platform-specific, null on any
+ *  failure - never blocks the snapshot. */
+async function detectGpu() {
+    if (process.platform === 'darwin') {
+        const m = (await runProbe('system_profiler', ['SPDisplaysDataType'])).match(/Chipset Model:\s*(.+)/);
+        return m ? m[1].trim() : null;
+    }
+    if (process.platform === 'linux') {
+        // nvidia-smi is fast + precise when present; fall back to lspci.
+        const nvName = (await runProbe('nvidia-smi', ['--query-gpu=name', '--format=csv,noheader'])).split('\n')[0]?.trim();
+        if (nvName)
+            return nvName;
+        const line = (await runProbe('sh', ['-c', "lspci | grep -iE 'vga|3d|display'"])).split('\n')[0]?.trim();
+        if (!line)
+            return null;
+        // Strip the "00:02.0 VGA compatible controller: " prefix.
+        const after = line.split(/:\s/).slice(2).join(': ').trim();
+        return after || line;
+    }
+    if (process.platform === 'win32') {
+        const line = (await runProbe('wmic', ['path', 'win32_VideoController', 'get', 'name']))
+            .split('\n').map(l => l.trim()).filter(l => l && l !== 'Name')[0];
+        return line ?? null;
+    }
+    return null;
+}
+/** Free/total bytes on the projects volume (best-effort). */
+function diskUsage() {
+    try {
+        if (typeof statfsSync !== 'function')
+            return undefined;
+        const st = statfsSync(join(homedir(), 'GipityProjects'), { bigint: false });
+        if (!st || !st.bsize)
+            return undefined;
+        return { total: st.bsize * st.blocks, free: st.bsize * st.bavail };
+    }
+    catch {
+        // Projects dir may not exist yet - try the home volume instead.
+        try {
+            const st = statfsSync(homedir(), { bigint: false });
+            return { total: st.bsize * st.blocks, free: st.bsize * st.bavail };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Count of directories under ~/GipityProjects (no names). */
+function localProjectCount() {
+    try {
+        return readdirSync(join(homedir(), 'GipityProjects'), { withFileTypes: true })
+            .filter(e => e.isDirectory() && !e.name.startsWith('.')).length;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Gather the full snapshot. Cheap `os.*` reads plus the bounded subprocess
+ * probes. Always resolves (best-effort per field).
+ */
+export async function collectDiagnostics() {
+    const cores = (() => { try {
+        return cpus();
+    }
+    catch {
+        return [];
+    } })();
+    // Run the subprocess probes concurrently (each already bounded + best-effort)
+    // so the whole snapshot costs one timeout, not the sum of four.
+    const [claude, codex, cursor, gpu] = await Promise.all([
+        probeVersion('claude'), probeVersion('codex'), probeVersion('cursor'), detectGpu(),
+    ]);
+    const agents = {};
+    if (claude)
+        agents.claude_code = claude;
+    if (codex)
+        agents.codex = codex;
+    if (cursor)
+        agents.cursor = cursor;
+    return {
+        collected_at: new Date().toISOString(),
+        gipity_version: cliVersion(),
+        node_version: process.versions.node,
+        os: { platform: process.platform, release: safe(() => release()), arch: process.arch },
+        cpu: { count: cores.length || undefined, model: cores[0]?.model?.trim() || undefined },
+        mem: { total: safe(() => totalmem()), free: safe(() => freemem()) },
+        load1: safe(() => Math.round(loadavg()[0] * 100) / 100),
+        uptime_s: safe(() => Math.round(uptime())),
+        disk: diskUsage(),
+        gpu,
+        agents: Object.keys(agents).length ? agents : undefined,
+        projects_local: localProjectCount(),
+    };
+}
+function safe(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/relay/onboarding.js

@@ -109,6 +109,14 @@ export async function runRelaySetup(opts) {
             }
         }
     }
+    // Diagnostics consent - default on, clearly opt-out. Only ask once.
+    if (state.getDiagnosticsConsent() === undefined) {
+        const diag = await confirm('  Share anonymous diagnostics (CPU/GPU/memory/disk/versions) to improve reliability?', { default: 'yes' });
+        state.setDiagnosticsConsent(diag);
+        console.log(`  ${dim(diag
+            ? 'Thanks - no personal data or file paths are ever sent. Turn off anytime with `gipity relay diagnostics off`.'
+            : 'Diagnostics off. Turn on anytime with `gipity relay diagnostics on`.')}`);
+    }
     console.log('');
     console.log(`  ${success(`Registered as ${bold(device.name)} (${device.guid}).`)}`);
     console.log(`  ${dim('In the Gipity web CLI, type `/claude` to dispatch messages to this PC.')}`);

package/dist/relay/state.js

@@ -38,6 +38,7 @@ export function loadState() {
             paused: Boolean(raw.paused),
             relay_enabled: typeof raw.relay_enabled === 'boolean' ? raw.relay_enabled : undefined,
             onboard_shown: Boolean(raw.onboard_shown),
+            diagnostics_consent: typeof raw.diagnostics_consent === 'boolean' ? raw.diagnostics_consent : undefined,
             agent_token: typeof raw.agent_token === 'string' ? raw.agent_token : null,
             agent_token_guid: typeof raw.agent_token_guid === 'string' ? raw.agent_token_guid : null,
         };
@@ -113,6 +114,23 @@ export function isRelayEnabled() {
 export function setRelayEnabled(enabled) {
     mutate(s => { s.relay_enabled = enabled; });
 }
+// ─── Diagnostics consent (tri-state, default-on) ───────────────────────
+/** Stored preference: `undefined` = never asked; `true`/`false` = explicit. */
+export function getDiagnosticsConsent() {
+    return loadState().diagnostics_consent;
+}
+export function setDiagnosticsConsent(consent) {
+    mutate(s => { s.diagnostics_consent = consent; });
+}
+/** Effective consent used by the daemon: default-on unless the user explicitly
+ *  opted out OR a headless opt-out env var (GIPITY_NO_DIAGNOSTICS / DO_NOT_TRACK)
+ *  is set. Truthy env value ("1"/"true"/anything non-empty) disables. */
+export function diagnosticsConsented() {
+    const env = process.env.GIPITY_NO_DIAGNOSTICS ?? process.env.DO_NOT_TRACK;
+    if (env && env !== '0' && env.toLowerCase() !== 'false')
+        return false;
+    return loadState().diagnostics_consent !== false;
+}
 // ─── Daemon PID file (lives at ~/.gipity/relay.pid) ────────────────────
 const RELAY_PID_FILE = join(RELAY_DIR, 'relay.pid');
 export function getDaemonPidPath() {

package/dist/setup.js

@@ -244,27 +244,39 @@ function versionGte(have, want) {
     }
     return true;
 }
-/** True when Claude Code already records a USER-scope install of the Gipity
- *  plugin at >= the version this CLI needs - the common case, letting the
- *  caller skip the (slow) reinstall. Reads installed_plugins.json directly so
- *  the check costs no subprocess. Exported so `gipity status` can tell an
- *  actually-loaded plugin apart from one that's merely enabled-but-uninstalled
- *  (which would otherwise read as a false-green "hooks enabled"). */
-export function userScopePluginCurrent() {
+/** Parsed user-scope install state for the Gipity plugin, read straight from
+ *  installed_plugins.json (no subprocess). `exists` is true when Claude Code
+ *  records ANY user-scope install; `current` narrows that to one at >= the
+ *  version this CLI needs. The two differ exactly when a stale install lags a
+ *  plugin-version bump - the case that must be UPGRADED, not freshly installed
+ *  (a bare `claude plugin install` no-ops on an already-present user install
+ *  and never advances its version). */
+export function userScopeInstallState() {
     try {
         const p = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
         const data = JSON.parse(readFileSync(p, 'utf-8'));
         const entries = data?.plugins?.[GIPITY_PLUGIN_ID];
         if (!Array.isArray(entries))
-            return false;
-        return entries.some((e) => e?.scope === 'user' &&
-            typeof e?.version === 'string' &&
-            versionGte(e.version, GIPITY_PLUGIN_VERSION));
+            return { exists: false, current: false };
+        const userEntries = entries.filter((e) => e?.scope === 'user');
+        return {
+            exists: userEntries.length > 0,
+            current: userEntries.some((e) => typeof e?.version === 'string' && versionGte(e.version, GIPITY_PLUGIN_VERSION)),
+        };
     }
     catch {
-        return false;
+        return { exists: false, current: false };
     }
 }
+/** True when Claude Code already records a USER-scope install of the Gipity
+ *  plugin at >= the version this CLI needs - the common case, letting the
+ *  caller skip the (slow) reinstall. Reads installed_plugins.json directly so
+ *  the check costs no subprocess. Exported so `gipity status` can tell an
+ *  actually-loaded plugin apart from one that's merely enabled-but-uninstalled
+ *  (which would otherwise read as a false-green "hooks enabled"). */
+export function userScopePluginCurrent() {
+    return userScopeInstallState().current;
+}
 function claudeOnPath() {
     const probe = spawnSyncCommand(process.platform === 'win32' ? 'where' : 'which', ['claude'], {
         encoding: 'utf-8',
@@ -286,22 +298,31 @@ function claudeOnPath() {
  *  never break `gipity claude`. Skips entirely when the user-scope install is
  *  already current, so it shells out at most once per plugin-version bump. */
 export function ensureGipityPluginInstalled() {
-    if (userScopePluginCurrent())
+    const state = userScopeInstallState();
+    if (state.current)
         return;
     if (!claudeOnPath())
         return;
-    // 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.
+    // Refresh the marketplace clone so install/update resolves the current version.
     // resolveCommand: on Windows `claude` is a .cmd shim that spawn can't launch
-    // without an explicit path, so resolve it (otherwise the install silently
+    // without an explicit path, so resolve it (otherwise the command silently
     // ENOENTs and the plugin's hooks never land at user scope).
     const claudeCmd = resolveCommand('claude');
     spawnSyncCommand(claudeCmd, ['plugin', 'marketplace', 'update', GIPITY_MARKETPLACE_NAME], {
         stdio: 'ignore',
         timeout: 120_000,
     });
-    spawnSyncCommand(claudeCmd, ['plugin', 'install', GIPITY_PLUGIN_ID, '--scope', 'user'], {
+    // A bare `plugin install` only materializes a MISSING install - on an
+    // already-present but stale user-scope install (the version this CLI just
+    // bumped past) it no-ops and leaves the old version registered, so
+    // userScopePluginCurrent() stays false forever and `gipity status` reports
+    // `missing: install` on every run. `plugin update` is the command that
+    // actually advances a registered user-scope install to the marketplace's
+    // current version; `install` is only right when nothing is installed yet.
+    const verb = state.exists
+        ? ['plugin', 'update', GIPITY_PLUGIN_ID, '--scope', 'user']
+        : ['plugin', 'install', GIPITY_PLUGIN_ID, '--scope', 'user'];
+    spawnSyncCommand(claudeCmd, verb, {
         stdio: 'ignore',
         timeout: 120_000,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.413",
+  "version": "1.0.414",
   "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",
@@ -13,7 +13,7 @@
     "postbuild": "node scripts/gen-build-info.mjs",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/platform.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__/api-401-retry.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__/ingest-queue.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.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-storage.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-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
+    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/platform.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__/api-401-retry.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-diagnostics.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__/ingest-queue.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.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-storage.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-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
     "test:smoke:quick": "node scripts/smoke-quick.mjs",
     "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-sync-stress-live.test.js dist/__tests__/cli-e2e-rollback-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",