gipity 1.0.416 → 1.0.419

package/dist/commands/claude.js

@@ -148,6 +148,17 @@ function formatElapsed(ms) {
  *  truncate the file. Best-effort: a malformed or unreadable config is left
  *  untouched and never blocks the launch. Headless `-p` runs skip the dialog
  *  already, so this is only needed for interactive launches. */
+/** True when the Claude Code argv asks for stream-json output (both the
+ *  `--output-format stream-json` and `--output-format=stream-json` forms).
+ *  Combined with an inherited GIPITY_CONVERSATION_GUID this identifies a
+ *  relay-daemon spawn, where the daemon owns capture and lifecycle-hook
+ *  capture must stand down. Exported for tests. */
+export function hasStreamJsonFlag(args) {
+    const idx = args.indexOf('--output-format');
+    if (idx !== -1 && args[idx + 1] === 'stream-json')
+        return true;
+    return args.includes('--output-format=stream-json');
+}
 export function markFolderTrusted(dir) {
     try {
         const file = join(homedir(), '.claude.json');
@@ -675,12 +686,15 @@ export const claudeCommand = new Command('claude')
         // we can't satisfy the claude_code ownership rule, so hooks stay
         // offline for this run.
         //
-        // Note: when `--output-format stream-json` is present in argv, the
-        // relay daemon is capturing Claude's stdout directly and the hook-
-        // based transcript capture would double-post every event. In that
-        // case we intentionally do NOT propagate GIPITY_CONVERSATION_GUID
-        // to the Claude child (see childEnv assignment below) - the hook's
-        // existing "no guid → silent no-op" guard then skips capture.
+        // Note: when this process was spawned BY the relay daemon (inherited
+        // GIPITY_CONVERSATION_GUID) with `--output-format stream-json`, the
+        // daemon is capturing Claude's stdout directly and hook-based capture
+        // would double-post every event. In that case we set GIPITY_CAPTURE=off
+        // on the Claude child (see childEnv assignment below) so the hook
+        // runner stands down. A USER-supplied stream-json run has no daemon
+        // behind it - hooks stay armed there, or the conversation would sit
+        // empty forever (the qwen-flight zero-message bug, 2026-07-07).
+        const inheritedConvGuid = Boolean(process.env.GIPITY_CONVERSATION_GUID);
         let convGuidForHooks = process.env.GIPITY_CONVERSATION_GUID ?? null;
         if (!convGuidForHooks) {
             const device = relayState.getDevice();
@@ -819,14 +833,16 @@ export const claudeCommand = new Command('claude')
         // throws EINVAL on Node >=18.20.2/20.12.2 - the CVE-2024-27980 fix).
         const claudeCmd = resolveCommand('claude');
         const childEnv = { ...process.env };
-        // Gate hook-based capture: when the daemon is streaming via
-        // --output-format stream-json, it owns the capture and any hook
-        // post would be a dupe. Leaving GIPITY_CONVERSATION_GUID unset in
-        // the child's env trips the hook runner's early-return guard.
-        const streamJsonIdx = allArgs.indexOf('--output-format');
-        const daemonCapturing = streamJsonIdx !== -1 && allArgs[streamJsonIdx + 1] === 'stream-json';
+        // Gate hook-based capture: only when the DAEMON is streaming via
+        // --output-format stream-json (inherited guid = daemon spawn) does it
+        // own the capture; any hook post would then be a dupe. GIPITY_CAPTURE=off
+        // stands the hook runner down explicitly - merely unsetting the guid is
+        // no longer enough now that the runner self-arms from .gipity.json.
+        // A user-supplied stream-json run (no inherited guid) keeps hooks armed.
+        const daemonCapturing = inheritedConvGuid && hasStreamJsonFlag(allArgs);
         if (daemonCapturing) {
             delete childEnv.GIPITY_CONVERSATION_GUID;
+            childEnv.GIPITY_CAPTURE = 'off';
         }
         else if (convGuidForHooks) {
             childEnv.GIPITY_CONVERSATION_GUID = convGuidForHooks;

package/dist/commands/generate.js

@@ -274,11 +274,61 @@ Examples:
         process.exit(1);
     }
 });
+// ── SOUND ──────────────────────────────────────────────────────────────
+const soundCommand = new Command('sound')
+    .description(`Generate a sound effect from a text description using AI.
+
+Always billed to you (the caller) - the app's service billing_mode does not
+apply to direct generation, so there is never a reason to flip a service to
+owner_pays just to create assets.
+
+Tips:
+  - Describe the sound, not a scene (e.g. "cartoon boing with a springy wobble")
+  - Omit --duration to let the model pick a natural length (billing is per second)
+  - --influence closer to 1 follows the text more literally
+
+Examples:
+  gipity generate sound "cartoon character saying oof"
+  gipity generate sound "thunder rolling in the distance" --duration 5
+  gipity generate sound "sci-fi laser blast" -o src/assets/sounds/laser.mp3`)
+    .argument('<text>', 'Text description of the sound effect (max 1000 characters)')
+    .option('--duration <seconds>', 'Clip length in seconds (0.5-30; default: automatic)', (v) => parseFloat(v))
+    .option('--influence <n>', 'How closely to follow the prompt, 0.0-1.0 (higher = more literal)', (v) => parseFloat(v))
+    .option('-o, --output <file>', 'Output path (default ./sound.mp3). For audio your app ships, write it into the source tree so it deploys, e.g. -o src/assets/sounds/boing.mp3; the cwd default is fine for one-off generation.')
+    .option('--json', 'Output as JSON')
+    .action(async (text, opts) => {
+    try {
+        const { config } = await resolveProjectContext();
+        const doGenerate = () => post(`/projects/${config.projectGuid}/generate/sound`, {
+            text,
+            duration_seconds: opts.duration,
+            prompt_influence: opts.influence,
+        });
+        const result = opts.json
+            ? await doGenerate()
+            : await withSpinner('Generating sound effect…', doGenerate, { done: null });
+        const filename = opts.output || 'sound.mp3';
+        const savedPath = await downloadFile(result.url, filename);
+        if (opts.json) {
+            console.log(JSON.stringify({ ...result, saved: savedPath }));
+        }
+        else {
+            const sizeKb = Math.round(result.size_bytes / 1024);
+            console.log(`${muted(`Generated sound effect (${sizeKb}KB)`)}`);
+            console.log(success(`Saved to ${savedPath}`));
+        }
+    }
+    catch (err) {
+        printCommandError('Sound generation', err);
+        process.exit(1);
+    }
+});
 // ── PARENT COMMAND ─────────────────────────────────────────────────────
 export const generateCommand = new Command('generate')
-    .description('Generate images, video, speech, or music')
+    .description('Generate images, video, speech, sound effects, or music')
     .addCommand(imageCommand)
     .addCommand(videoCommand)
     .addCommand(speechCommand)
+    .addCommand(soundCommand)
     .addCommand(musicCommand);
 //# sourceMappingURL=generate.js.map

package/dist/commands/init.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { basename, resolve, dirname } from 'path';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { getAccountSlug } from '../api.js';
 import { getConfig, getConfigPath, saveConfigAt } from '../config.js';
 import { getAuth } from '../auth.js';
@@ -26,6 +26,7 @@ export const initCommand = new Command('init')
     .addHelpText('after', '\nWrites CLAUDE.md/AGENTS.md primer files so your AI coding tool understands Gipity.')
     .argument('[name]', 'Project name/slug (defaults to current directory name)')
     .option('--agent <guid>', 'Agent GUID to use')
+    .option('--no-capture', 'Don\'t record Claude Code sessions in this directory to your Gipity project (sets captureHooks: false in .gipity.json)')
     .option('--for <tools>', `Which AI tool primer files to write (comma-separated). Default: all except aider (opt-in - it also writes .aider.conf.yml). Choices: ${TOOL_KEYS.join(', ')}, all`)
     .addHelpText('after', `
 Examples:
@@ -86,14 +87,28 @@ Working with an existing Gipity project:
             // artifact introduced by a newer CLI (e.g. aider's .aider.conf.yml)
             // would sync up as project content. Union in the current defaults.
             if (existing) {
+                let changed = false;
                 const cur = existing.ignore ?? (existing.ignore = []);
                 const missing = DEFAULT_SYNC_IGNORE.filter(e => !cur.includes(e));
                 if (missing.length) {
                     cur.push(...missing);
-                    saveConfigAt(cwd, existing);
+                    changed = true;
+                }
+                // `--no-capture` on a re-init is the documented way to opt an
+                // existing project out of session recording. One-way from flags:
+                // a bare re-run never silently reverses an explicit opt-out
+                // (delete the key or set it true in .gipity.json to re-enable).
+                if (opts.capture === false && existing.captureHooks !== false) {
+                    existing.captureHooks = false;
+                    changed = true;
                 }
+                if (changed)
+                    saveConfigAt(cwd, existing);
             }
             console.log(success(`Refreshed primer files: ${primerSummary}.`));
+            if (opts.capture === false) {
+                console.log(success('Session recording disabled for this project (captureHooks: false in .gipity.json).'));
+            }
             return;
         }
         // Refuse $HOME / system roots - adopting one as a project root would
@@ -156,9 +171,27 @@ Working with an existing Gipity project:
         }
         if (adopted.applied > 0)
             console.log(`Synced ${adopted.applied} change${adopted.applied > 1 ? 's' : ''} with Gipity.`);
+        // Session recording opt-out. Written after adopt so it lands in the
+        // freshly created .gipity.json regardless of how the link happened.
+        if (opts.capture === false) {
+            try {
+                const cfg = JSON.parse(readFileSync(resolve(cwd, '.gipity.json'), 'utf-8'));
+                cfg.captureHooks = false;
+                saveConfigAt(cwd, cfg);
+            }
+            catch { /* config missing/unreadable - nothing to opt out of */ }
+        }
         console.log(success(`Wrote primer files: ${primerSummary}.`));
         if (wantsClaude) {
             console.log(success('Ready! Run `gipity claude` for Claude Code, or open this directory in your other AI coding tool.'));
+            // Recording happens by default (however Claude Code is launched), so
+            // say so up front - consent should be explicit, not discovered later.
+            if (opts.capture === false) {
+                console.log(muted('Session recording is off for this project (captureHooks: false in .gipity.json).'));
+            }
+            else {
+                console.log(muted('Claude Code sessions here are recorded to your Gipity project (view at prompt.gipity.ai). Opt out: gipity init --no-capture.'));
+            }
         }
         else {
             console.log(success('Ready! Open this directory in your AI coding tool.'));

package/dist/commands/service.js

@@ -13,7 +13,7 @@ const SERVICES = [
     { name: 'image/models', method: 'GET', desc: 'List image providers/models' },
     { name: 'tts', method: 'POST', desc: 'Text-to-speech ({ text, voice?, ... })' },
     { name: 'tts/voices', method: 'GET', desc: 'List TTS voices' },
-    { name: 'sound', method: 'POST', desc: 'Sound effect ({ prompt, duration_seconds? })' },
+    { name: 'sound', method: 'POST', desc: 'Sound effect ({ text, duration_seconds? })' },
     { name: 'music', method: 'POST', desc: 'Music generation ({ prompt, duration_seconds? })' },
     { name: 'video', method: 'POST', desc: 'Video generation ({ prompt, ... })' },
     { name: 'location/ip', method: 'POST', desc: 'IP geolocation ({ ip? })' },

package/dist/commands/uninstall.js

@@ -10,7 +10,7 @@
  */
 import { Command } from 'commander';
 import { existsSync, rmSync, unlinkSync, readFileSync, writeFileSync } from 'fs';
-import { homedir } from 'os';
+import { homedir, platform as osPlatform } from 'os';
 import { join, resolve } from 'path';
 import { spawnSyncCommand } from '../platform.js';
 import { post } from '../api.js';
@@ -52,6 +52,45 @@ function removeGipityPluginConfig() {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     return changed;
 }
+/** The install.sh / install.ps1 launcher appends a line to the user's shell rc
+ *  files putting ~/.gipity/launcher/bin on PATH. Once ~/.gipity is deleted that
+ *  line points at nothing, so strip it back out - matched by the installer's own
+ *  marker comment and the launcher bin path. Unix shells only; on Windows the
+ *  installer edits the user PATH env var, which we leave untouched. Returns the
+ *  rc files we actually changed. */
+function removeInstallerPathLines() {
+    if (osPlatform() === 'win32')
+        return [];
+    const marker = '# Added by the Gipity installer';
+    const touched = [];
+    for (const name of ['.bashrc', '.zshrc', '.profile']) {
+        const rc = join(homedir(), name);
+        if (!existsSync(rc))
+            continue;
+        let text;
+        try {
+            text = readFileSync(rc, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const lines = text.split('\n');
+        const kept = lines.filter((line) => line.trim() !== marker && !line.includes('.gipity/launcher/bin'));
+        if (kept.length === lines.length)
+            continue;
+        try {
+            writeFileSync(rc, kept.join('\n'));
+            touched.push(rc);
+        }
+        catch { /* ignore */ }
+    }
+    return touched;
+}
+/** Render an absolute path under $HOME back to ~ for display. */
+function tildify(p) {
+    const home = homedir();
+    return p === home || p.startsWith(home + '/') ? '~' + p.slice(home.length) : p;
+}
 function resolveCliPath() {
     return resolve(process.argv[1] ?? 'gipity');
 }
@@ -129,14 +168,28 @@ export const uninstallCommand = new Command('uninstall')
     .action(async (opts) => {
     const autoYes = opts.yes || getAutoConfirm();
     const gipityDir = join(homedir(), '.gipity');
+    // Installs from install.sh / install.ps1 keep the launcher binary itself
+    // under ~/.gipity/launcher/bin, so wiping ~/.gipity removes the binary too -
+    // the only leftover is the PATH line the installer added to the shell rc
+    // files (cleaned up below). An npm-global install instead leaves the binary
+    // in npm's bin dir, which the user removes with `npm uninstall -g gipity`.
+    const launcherBin = join(gipityDir, 'launcher', 'bin', 'gipity');
+    const installedViaLauncher = existsSync(launcherBin);
     console.log(`${bold('Gipity uninstall')} - this will:`);
     console.log(`• Stop the running relay daemon (if any)`);
     console.log(`• Remove the OS autostart service (launchd / systemd / Task Scheduler)`);
     console.log(`• Revoke this device on the server (best-effort)`);
     console.log(`• Remove the Gipity Claude Code plugin enablement (all Gipity hooks)`);
-    console.log(`• Delete ${gipityDir}/`);
+    console.log(`• Delete ${gipityDir}/${installedViaLauncher ? dim(' (includes the gipity launcher binary itself)') : ''}`);
+    if (installedViaLauncher)
+        console.log(`• Remove the launcher PATH line from your shell startup files`);
     console.log('');
-    console.log(`${dim('It will NOT remove the `gipity` binary. Run `npm uninstall -g gipity` afterward if you want that too.')}`);
+    if (installedViaLauncher) {
+        console.log(`${dim('The `gipity` launcher lives under ~/.gipity, so this removes the binary too - no separate `npm uninstall` needed.')}`);
+    }
+    else {
+        console.log(`${dim('It will NOT remove the `gipity` binary. Run `npm uninstall -g gipity` afterward if you want that too.')}`);
+    }
     console.log('');
     if (!autoYes) {
         const ok = await confirm('Proceed?');
@@ -179,8 +232,23 @@ export const uninstallCommand = new Command('uninstall')
     else {
         console.log(`${muted(`${gipityDir}/ already gone.`)}`);
     }
+    // 6. Strip the launcher PATH line the installer added to shell rc files, so
+    //    we don't leave a dangling entry pointing at the dir we just deleted.
+    const touchedRc = removeInstallerPathLines();
+    if (touchedRc.length) {
+        console.log(`${success('Removed the launcher PATH line from')} ${dim(touchedRc.map(tildify).join(', '))}`);
+    }
     console.log('');
-    console.log(`${success('Uninstall complete.')} ${dim('Run')} ${brand('npm uninstall -g gipity')} ${dim('to remove the binary too.')}`);
-    console.log(`${dim('Then run')} ${brand('hash -r')} ${dim('(or open a new shell) - your shell caches the old binary path, and a reinstall may place it elsewhere.')}`);
+    console.log(`${success('Uninstall complete.')}`);
+    if (installedViaLauncher) {
+        console.log(`${dim('The launcher binary was under ~/.gipity and is now gone - nothing left to remove.')}`);
+    }
+    else {
+        console.log(`${dim('Run')} ${brand('npm uninstall -g gipity')} ${dim('to remove the `gipity` binary too.')}`);
+    }
+    // The current shell caches the removed binary's path in its command hash, so
+    // the next `gipity` here reports "No such file or directory" until it's
+    // cleared. A new terminal always fixes it; `hash -r` fixes this one.
+    console.log(`${dim('Open a new terminal - or run')} ${brand('hash -r')} ${dim('in this one - so your shell forgets the removed binary’s path.')}`);
 });
 //# sourceMappingURL=uninstall.js.map

package/dist/hooks/capture-runner.js

@@ -2,7 +2,7 @@
 /**
  * Internal hook runner - invoked by Claude Code's lifecycle hooks
  * (SessionStart, Stop, SubagentStop, SessionEnd, and a throttled
- * PostToolUse for mid-run flushing) to mirror a terminal `gipity claude`
+ * PostToolUse for mid-run flushing) to mirror a terminal Claude Code
  * session into the Gipity server so the web CLI can display it read-only.
  *
  * Not a user-facing `gipity` subcommand by design: users never invoke
@@ -16,9 +16,22 @@
  *   source: 'claude-code' (today) | future: 'codex', …
  *   event:  'session-start' | 'stop' | 'subagent-stop' | 'session-end' | 'post-tool-use' | 'pre-compact'
  *
+ * Conversation binding, in order:
+ *   1. GIPITY_CONVERSATION_GUID env var - set by `gipity claude`, which
+ *      created/reused the conversation before spawning Claude Code.
+ *   2. A session_id → conv mapping persisted in the capture-state dir by
+ *      an earlier event of this session.
+ *   3. Self-arm: the session was launched WITHOUT `gipity claude` (bare
+ *      `claude` in a linked project dir). Resolve the project from
+ *      .gipity.json and ask the server to bind this session_id to a
+ *      conversation (POST /remote-sessions/resolve), then persist the
+ *      mapping. This is what makes bare `claude` sessions record.
+ *
  * Graceful no-ops (exit 0 silently):
- *   - GIPITY_CONVERSATION_GUID env var unset (hook fired from a bare
- *     `claude`, not `gipity claude`).
+ *   - GIPITY_CAPTURE=off - the relay daemon owns capture for this run
+ *     (it parses stream-json from stdout), or the caller opted out.
+ *   - No binding resolvable: not a Gipity project, `captureHooks: false`
+ *     in .gipity.json, or the resolve call failed.
  *   - The machine isn't paired - no device token available.
  *   - Anything unexpected (parse error, network error, etc.). We must
  *     not break the user's interactive session.
@@ -28,6 +41,7 @@ import { homedir } from 'os';
 import { join } from 'path';
 import { getDevice } from '../relay/state.js';
 import { deviceFetch } from '../relay/device-http.js';
+import { getConfig } from '../config.js';
 import { parseTranscript, } from '../capture/sources/claude-code.js';
 const CAPTURE_DIR = join(homedir(), '.gipity', 'capture-state');
 const INGEST_BATCH_MAX = 100; // server caps at 200; stay comfortably under
@@ -159,6 +173,117 @@ export function acquireLock(convGuid) {
     }
     return null;
 }
+// ─── conversation binding ────────────────────────────────────────────
+// Sessions launched via `gipity claude` carry GIPITY_CONVERSATION_GUID.
+// Bare `claude` in a linked project has no env binding, so the first
+// event resolves one from the server (keyed by the agent session_id) and
+// persists it here for every later event of the session.
+/** session_id is Claude Code's session UUID - filesystem-safe by
+ *  construction; the character guard keeps a hostile hook payload from
+ *  escaping the capture-state dir (used for both the mapping file and
+ *  the resolve lock). */
+function safeSessionKey(sessionId) {
+    return `sid-${sessionId.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+}
+function sessionMapPath(sessionId) {
+    return join(CAPTURE_DIR, `${safeSessionKey(sessionId)}.json`);
+}
+function readSessionMap(sessionId) {
+    try {
+        const parsed = JSON.parse(readFileSync(sessionMapPath(sessionId), 'utf-8'));
+        return typeof parsed.conv_guid === 'string' ? parsed.conv_guid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeSessionMap(sessionId, convGuid) {
+    mkdirSync(CAPTURE_DIR, { recursive: true });
+    writeFileSync(sessionMapPath(sessionId), JSON.stringify({ conv_guid: convGuid }) + '\n');
+}
+function deleteSessionMap(sessionId) {
+    try {
+        unlinkSync(sessionMapPath(sessionId));
+    }
+    catch { /* already gone */ }
+}
+/** Ask the server which conversation this session belongs to: the conv
+ *  already bound to this session_id (resume), the project's still-empty
+ *  placeholder, or a fresh one. Returns null on any failure - capture is
+ *  best-effort and must never break the session. */
+async function resolveFromServer(projectGuid, hook) {
+    let res;
+    try {
+        res = await deviceFetch('POST', '/remote-sessions/resolve', {
+            project_guid: projectGuid,
+            session_id: hook.session_id,
+            cwd: hook.cwd,
+        }, 15_000);
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    try {
+        const body = await res.json();
+        return body.data?.conversation_guid ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the conversation this event writes to. Env binding first (set
+ *  by `gipity claude`), then the session's persisted mapping, then the
+ *  self-arm server resolve. The resolve is serialized per-session with
+ *  the same crash-safe lock the flushers use, so concurrent hooks (Stop +
+ *  SubagentStop) can't each mint a conversation: the loser polls for the
+ *  winner's mapping instead of racing the server. */
+export async function resolveConvGuid(hook, sleep = (ms) => new Promise(r => setTimeout(r, ms))) {
+    const fromEnv = process.env.GIPITY_CONVERSATION_GUID;
+    if (fromEnv)
+        return fromEnv;
+    const sessionId = hook.session_id;
+    if (!sessionId)
+        return null;
+    const mapped = readSessionMap(sessionId);
+    if (mapped)
+        return mapped;
+    // Self-arm gates: linked project, capture not opted out, machine paired
+    // (main() already checked the device, but resolveConvGuid is also the
+    // unit-tested entry - keep it self-sufficient).
+    const config = getConfig();
+    if (!config?.projectGuid || config.captureHooks === false)
+        return null;
+    if (!getDevice())
+        return null;
+    const release = acquireLock(safeSessionKey(sessionId));
+    if (!release) {
+        // Another hook instance is resolving this session right now. Give it
+        // a moment and use its result; bail silently if it never lands (the
+        // next event retries the whole resolution).
+        for (let i = 0; i < 10; i++) {
+            await sleep(300);
+            const conv = readSessionMap(sessionId);
+            if (conv)
+                return conv;
+        }
+        return null;
+    }
+    try {
+        // Re-check under the lock - the previous holder may have just finished.
+        const raced = readSessionMap(sessionId);
+        if (raced)
+            return raced;
+        const conv = await resolveFromServer(config.projectGuid, hook);
+        if (conv)
+            writeSessionMap(sessionId, conv);
+        return conv;
+    }
+    finally {
+        release();
+    }
+}
 async function readStdin() {
     if (process.stdin.isTTY)
         return '';
@@ -262,6 +387,8 @@ async function handleSessionEnd(convGuid, hook, source) {
         }];
     await postEntries(convGuid, entries);
     deleteState(convGuid);
+    if (hook.session_id)
+        deleteSessionMap(hook.session_id);
 }
 function displayName(source) {
     if (source === 'claude-code')
@@ -269,9 +396,12 @@ function displayName(source) {
     return source;
 }
 async function main() {
-    const convGuid = process.env.GIPITY_CONVERSATION_GUID;
-    if (!convGuid)
-        return; // bare `claude`, not `gipity claude`
+    // Explicit capture opt-out. Set by the relay daemon's dispatch spawns
+    // (the daemon parses stream-json from stdout - hook capture would
+    // double-post every event) and available to anyone wanting a one-off
+    // unrecorded session.
+    if (process.env.GIPITY_CAPTURE === 'off')
+        return;
     if (!getDevice())
         return; // machine not paired
     const [source, event] = process.argv.slice(2);
@@ -285,6 +415,9 @@ async function main() {
         }
         catch { /* ignore - event may not require transcript */ }
     }
+    const convGuid = await resolveConvGuid(hook);
+    if (!convGuid)
+        return; // not a Gipity-bound session - nothing to capture
     try {
         switch (event) {
             case 'session-start':

package/dist/knowledge.js

@@ -51,7 +51,7 @@ Prefer the cheapest option that works - CLI and sandbox are instant and free, ap
 
 1. CLI commands (fast, no agent overhead). The \`gipity\` CLI covers add, deploy, db, fn, logs, browser, sync, memory, skill, email, and more. All commands support \`--json\`. You can send email yourself - \`gipity email send\` goes out as the agent from \`gipity@gipity.ai\` with no setup or API keys (\`gipity skill read email\`); don't build a \`mailto:\` workaround or reach for an SMTP library.
 2. Cloud sandbox via \`gipity sandbox run\` - Docker container with pre-installed tools for media (ffmpeg, ImageMagick, sox), documents (pandoc, LibreOffice), and data (pandas, matplotlib, sqlite3). Run \`gipity skill read sandbox-tools\` for the full toolkit. No network from inside the sandbox - fetch what you need before sending it in.
-3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location, push notifications (Gipity Notify - \`gipity add notify\`, send from a function with the injected \`notify()\`; see \`app-notify\`). Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|music>\` or \`gipity chat\`. \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) - pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
+3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location, push notifications (Gipity Notify - \`gipity add notify\`, send from a function with the injected \`notify()\`; see \`app-notify\`). Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|sound|music>\` or \`gipity chat\` - direct generation always bills you (the owner), regardless of any service \`billing_mode\` (that setting only governs the deployed app's runtime calls; never flip it just to create assets). \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) - pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
 4. Delegate to Gip (\`gipity chat "<task>"\`) - only when the work genuinely needs agent reasoning or a tool not in the CLI, sandbox, or app services. Required for: Twitter/X search, Gmail, calendar, push notifications, video understanding, audio source isolation, cross-model second opinions, multi-step orchestration. Don't use \`gipity chat\` for anything the sandbox can do - it's slower and burns tokens.
 
 You are the developer. Write files in this directory - the Gipity Claude Code plugin's hooks auto-sync them to Gipity. Don't run \`npm install\`, \`npm start\`, \`node\`, or \`python\` locally; there is no local runtime. Code runs in the Gipity sandbox.
@@ -84,6 +84,8 @@ The one exception is app-level libraries the user imports into their own \`src/\
 
 ## Build loop
 
+Prefer a live Gipity URL over an ephemeral artifact. When you'd otherwise reach for a Claude Code Artifact (or any host's built-in page preview) to show the user something, build it as a Gipity app and \`gipity deploy dev\` instead - the result is a real, shareable URL on their own project, not a throwaway.
+
 The full "when to add a template" rule and the definition of done are spelled out in the two sections at the end of this document. In short: if the user wants something deployable (web app, game, API), \`gipity add <template>\` first (default \`web-simple\`); for a one-off task (analysis, PDFs, data work), use \`gipity sandbox run\` instead; to add a reusable building block to an existing app (e.g. multiplayer), \`gipity add <kit>\`.
 
 Build loop: \`gipity add\` → edit files → \`gipity deploy dev\` → \`gipity page inspect <url>\` → fix any errors → repeat until the definition of done is met.

package/dist/relay/daemon.js

@@ -1233,7 +1233,12 @@ export async function spawnGipityClaude(args, cwd, d, queue, meta) {
     // feed the ephemeral live-typing channel (see stream-delta.ts); whole
     // assistant/tool events still arrive unchanged for the persistent path.
     const fullArgs = [...args, '--output-format', 'stream-json', '--verbose', '--include-partial-messages'];
-    const env = childEnv({ GIPITY_CONVERSATION_GUID: d.conversation_guid });
+    // GIPITY_CAPTURE=off: the daemon owns capture for this dispatch (it
+    // parses the stream-json on stdout), so the plugin's lifecycle-hook
+    // capture must stand down. `gipity claude` sets the same sentinel on the
+    // Claude child when it detects a daemon spawn; setting it here too keeps
+    // dispatches double-post-free even across CLI version skew.
+    const env = childEnv({ GIPITY_CONVERSATION_GUID: d.conversation_guid, GIPITY_CAPTURE: 'off' });
     return new Promise((resolve, reject) => {
         const child = spawnCommand(cmd, fullArgs, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
         // `exited` fires when the child fully unwinds (exit event). Callers

package/dist/setup.js

@@ -145,7 +145,7 @@ export const LEGACY_MARKETPLACE_REPO = 'GipityAI/claude-plugin';
 // an installed plugin when the marketplace advances - only an explicit
 // `plugin install`/`update` does - so this constant is how a CLI upgrade tells
 // ensureGipityPluginInstalled() to refresh a stale user-scope install.
-export const GIPITY_PLUGIN_VERSION = '0.4.1';
+export const GIPITY_PLUGIN_VERSION = '0.5.0';
 /** True for hook commands the CLI itself wrote into settings.json in past
  *  versions. Matched by signature so migration strips exactly our own
  *  entries and never touches user-authored hooks. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.416",
+  "version": "1.0.419",
   "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-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": "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__/capture-lock.test.js dist/__tests__/capture-resolve.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",