gipity 1.0.429 → 1.1.1

package/dist/commands/sandbox.js

@@ -1,6 +1,6 @@
-import { Command } from 'commander';
-import { readFileSync, existsSync, statSync } from 'fs';
-import { dirname, extname, relative, resolve } from 'path';
+import { Command, Option } from 'commander';
+import { readFileSync, existsSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname, extname, relative, resolve, sep } from 'path';
 import { post } from '../api.js';
 import { resolveProjectContext, getConfigPath, getProjectRoot, shouldIgnore } from '../config.js';
 import { SCRATCH_IGNORE } from '../setup.js';
@@ -167,19 +167,28 @@ sandboxCommand
     // an interpreter token, or a --file extension - see resolveLanguage().
     .option('--language <language>', 'Language: js, py, or bash (required unless pinned by an interpreter token or --file extension)')
     .option('--file <path>', 'Read the code body from a file instead of the inline <code> arg; --language is inferred from the extension when not given')
+    // `--code "<code>"` is the natural first guess for passing inline code (the
+    // positional arg is the canonical spelling). Accept it as a working alias
+    // rather than bouncing the guess into an unknown-option --help detour.
+    .addOption(new Option('--code <code>', 'Alias for the positional inline <code> arg').hideHelp())
     .option('--timeout <seconds>', 'Execution timeout in seconds', '30')
     .option('--input <path>', 'Narrow to specific project files instead of auto-mirroring the whole tree (repeatable). Use this only for >1 GB projects or when you want surgical control.', (v, prev) => [...(prev ?? []), v])
-    // Commander maps a `--no-` prefixed flag to the un-prefixed camelCase name
-    // (`opts.syncOutput`); the explicit `[]` default stops commander's negated-
-    // boolean convention from defaulting it to `true`. Collected as an array so
-    // the flag is repeatable.
-    .option('--no-sync-output <glob>', 'Do not persist run outputs matching this glob back to the project (repeatable). For byproducts you want to inspect once but never keep, e.g. --no-sync-output "docs/preview*". Supports *, **, and dir/ prefixes.', (v, prev) => [...prev, v], [])
+    // Named "discard", not "no-sync": in Gipity vocabulary "sync" means the
+    // local<->cloud file sync, so a no-sync spelling reads as "give me the file
+    // locally, just don't sync it" - which is the tmp/ scratch path below, not
+    // this flag. Collected as an array so the flag is repeatable.
+    .option('--discard-output <glob>', 'Discard run outputs matching this glob entirely - not saved, not returned (repeatable). To LOOK at an output without keeping it, write it under tmp/ instead: scratch outputs land on local disk only and never enter the project. Supports *, **, and dir/ prefixes.', (v, prev) => [...prev, v], [])
     .option('--json', 'Output as JSON')
     .addHelpText('after', `
 By default the whole project is auto-mirrored into /work/ (up to 1 GB) -
 so your code can reference project files by their relative path, and any
 file you write lands back in the project. No manual copy needed.
 
+Exception: tmp/ is scratch. An output written under tmp/ comes back to
+your local tmp/ for inspection but is never saved to the project - use it
+for previews and other look-once artifacts (no cleanup needed). To drop
+an output entirely, --discard-output <glob>.
+
 Use --input only for projects over the auto-mirror cap, or when you want
 to restrict what the sandbox sees.
 
@@ -196,6 +205,11 @@ Examples:
   $ gipity sandbox run --language python \\
       "import pandas as pd; print(pd.read_csv('data/sales.csv').describe())"
 
+  # Preview a generated PDF without saving the preview: write it to tmp/
+  $ gipity sandbox run bash \\
+      "pdftoppm -png -r 90 docs/report.pdf tmp/preview"
+  # -> tmp/preview-1.png lands on local disk only; Read it, done.
+
   # Run a script file directly (language inferred from .py)
   $ gipity sandbox run --file build_report.py
   $ gipity sandbox run python build_report.py   # same thing, interpreter shorthand
@@ -228,6 +242,14 @@ GCC/Rust).
     let inlineCode;
     let filePath = opts.file;
     let langFromInterp;
+    // --code alias: fold it into the positional slot before the shape checks.
+    if (opts.code !== undefined) {
+        if (args.length) {
+            console.error(clrError('Pass the code once: either positionally or via --code, not both'));
+            process.exit(1);
+        }
+        args = [opts.code];
+    }
     if (args.length >= 2 && INTERPRETERS[args[0].toLowerCase()] !== undefined) {
         langFromInterp = INTERPRETERS[args[0].toLowerCase()];
         const rest = args.slice(1).join(' ');
@@ -268,11 +290,11 @@ GCC/Rust).
     // This runs BEFORE the project sync and the server round trip below, so a
     // missing language costs nothing but the message.
     const language = resolveLanguage({ langFromInterp, langOpt: opts.language, filePath, inlineCode });
-    // Validate --no-sync-output globs while we're still pre-network: an empty
+    // Validate --discard-output globs while we're still pre-network: an empty
     // pattern (e.g. a quoting mishap) would silently match nothing server-side.
-    const noSyncOutput = opts.syncOutput ?? [];
-    if (noSyncOutput.some((g) => !g.trim())) {
-        console.error(clrError('--no-sync-output requires a non-empty glob (e.g. --no-sync-output "docs/preview*")'));
+    const discardOutput = opts.discardOutput ?? [];
+    if (discardOutput.some((g) => !g.trim())) {
+        console.error(clrError('--discard-output requires a non-empty glob (e.g. --discard-output "*.ppm")'));
         process.exit(1);
     }
     // Args are good - now it's worth resolving (and announcing) the project.
@@ -311,8 +333,9 @@ GCC/Rust).
         cwd,
         // The filter must run SERVER-side (in the output extractor): skipping
         // only in the CLI would still write the files into project storage and
-        // make every later sync propose deleting them.
-        noSyncOutput: noSyncOutput.length ? noSyncOutput : undefined,
+        // make every later sync propose deleting them. (`noSyncOutput` is the
+        // wire name for --discard-output.)
+        noSyncOutput: discardOutput.length ? discardOutput : undefined,
     });
     const res = opts.json
         ? await doRun()
@@ -326,8 +349,26 @@ GCC/Rust).
     if (pulledLocal) {
         await sync({ interactive: false, progress: opts.json ? undefined : createProgressReporter() });
     }
+    // Scratch outputs (tmp/ and friends) never enter the project: the server
+    // returns their bytes inline instead of persisting them, and we land them
+    // here. The scratch namespace is ignored by sync in both directions, so
+    // the file exists on local disk only - inspect it, no cleanup required.
+    const scratchWritten = [];
+    if (res.data.scratchFiles?.length) {
+        const base = resolve(getProjectRoot() ?? process.cwd());
+        for (const f of res.data.scratchFiles) {
+            const rel = f.path.replace(/\\/g, '/');
+            const abs = resolve(base, rel);
+            if (abs !== base && !abs.startsWith(base + sep))
+                continue; // traversal guard
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, Buffer.from(f.contentBase64, 'base64'));
+            scratchWritten.push(rel);
+        }
+    }
     if (opts.json) {
-        console.log(JSON.stringify({ ...res.data, filesSynced: pulledLocal }));
+        const { scratchFiles: _omit, ...rest } = res.data;
+        console.log(JSON.stringify({ ...rest, scratchFiles: scratchWritten, filesSynced: pulledLocal }));
     }
     else {
         if (res.data.autoMirrorSkipped) {
@@ -367,8 +408,13 @@ GCC/Rust).
                     console.log(dim("Not pulled locally - run 'gipity sync' to fetch them."));
             }
         }
+        if (scratchWritten.length > 0) {
+            console.log('\nScratch outputs (local only - never synced or deployed):');
+            for (const f of scratchWritten)
+                console.log(`${f}`);
+        }
         if (res.data.skippedOutputFiles && res.data.skippedOutputFiles.length > 0) {
-            console.log(dim('\nNot persisted (--no-sync-output):'));
+            console.log(dim('\nDiscarded (--discard-output):'));
             for (const f of res.data.skippedOutputFiles)
                 console.log(dim(`${f}`));
         }

package/dist/commands/setup.js

@@ -1,12 +1,17 @@
 /**
- * `gipity setup` — get this computer ready as a relay, then stop.
+ * `gipity connect` — connect this computer to gipity.ai, then stop.
  *
- * Runs the SAME first steps as `gipity claude` (log in, then pair + start the
+ * Runs the SAME first steps as `gipity build` (log in, then pair + start the
  * relay + install the OS login service) but does NOT pick a project or launch
- * Claude Code. For the user who wants their machine available as a relay in the
- * web CLI without being dropped into a coding session.
+ * an agent. For the user who wants their machine drivable from the web CLI
+ * without being dropped into a coding session.
  *
- * Shares one implementation with `gipity claude`: auth via `login-flow.ts`,
+ * Named `connect` because "setup" and "init" are synonyms in plain English -
+ * the machine-scoped verb needed its own word (and it matches `gipity
+ * payments connect`). `setup` stays as a hidden alias for muscle memory and
+ * old docs.
+ *
+ * Shares one implementation with `gipity build`: auth via `login-flow.ts`,
  * relay setup via `relay/onboarding.ts` (`runRelaySetup`). Nothing to maintain
  * twice.
  */
@@ -16,12 +21,13 @@ import { interactiveLogin } from '../login-flow.js';
 import { runRelaySetup } from '../relay/onboarding.js';
 import * as relayState from '../relay/state.js';
 import { bold, brand, success, muted, error as clrError } from '../colors.js';
-export const setupCommand = new Command('setup')
-    .description('Set up this computer as a relay (no project, no launch)')
+export const connectCommand = new Command('connect')
+    .alias('setup') // legacy name, kept working but not advertised
+    .description('Connect this computer to gipity.ai so the web CLI can drive it (no project, no launch)')
     .action(async () => {
     try {
         // Leading blank comes from the central output frame (installOutputFrame).
-        console.log(`  ${bold('Gipity setup')} ${muted('- get this computer ready as a relay')}`);
+        console.log(`  ${bold('Gipity connect')} ${muted('- let gipity.ai drive this computer')}`);
         console.log('');
         // ── Step 1: Auth ──────────────────────────────────────────────────
         let auth = getAuth();
@@ -44,10 +50,10 @@ export const setupCommand = new Command('setup')
         if (enabled) {
             const running = relayState.isRelayEnabled() && !relayState.isPaused();
             console.log(`  ${success('Done')} — your relay ${running ? 'is running in the background' : 'is set up'} and will start with your computer.`);
-            console.log(`  ${muted('Open')} ${brand('gipity.ai')} ${muted('and start a chat to drive Claude Code here. Manage it with `gipity relay status`.')}`);
+            console.log(`  ${muted('Open')} ${brand('gipity.ai')} ${muted('and start a chat to drive your coding agent here. Manage it with `gipity relay status`.')}`);
         }
         else {
-            console.log(`  ${muted('No relay set up. Run `gipity setup` again anytime, or `gipity claude` to build with Gipity.')}`);
+            console.log(`  ${muted('No relay set up. Run `gipity connect` again anytime, or `gipity build` to start building.')}`);
         }
         console.log('');
     }

package/dist/commands/uninstall.js

@@ -12,14 +12,14 @@ import { Command } from 'commander';
 import { existsSync, rmSync, unlinkSync, readFileSync, writeFileSync } from 'fs';
 import { homedir, platform as osPlatform } from 'os';
 import { join, resolve } from 'path';
-import { spawnSyncCommand } from '../platform.js';
+import { spawnSyncCommand, resolveCommand } from '../platform.js';
 import { post } from '../api.js';
 import { getAuth } from '../auth.js';
 import { confirm, getAutoConfirm } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as relayState from '../relay/state.js';
 import { planFor, UnsupportedPlatformError } from '../relay/installers.js';
-import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, stripGipityHooks } from '../setup.js';
+import { GIPITY_PLUGIN_ID, GIPITY_MARKETPLACE_NAME, stripGipityHooks, grokInstallState, agentSkillsState, AGENTS_SKILLS_DIR } from '../setup.js';
 /** Remove Gipity's entries from the user-scope Claude Code settings: the
  *  plugin enablement, the marketplace registration, and any legacy hook
  *  blocks older CLI versions wrote there. Surgical - everything else in the
@@ -219,7 +219,29 @@ export const uninstallCommand = new Command('uninstall')
     else {
         console.log(`${muted('No Gipity entries in Claude Code settings.')}`);
     }
-    // 5. Wipe ~/.gipity/.
+    // 4b. Uninstall the Gipity plugin from Grok Build and remove the skills
+    //     the CLI copied into the cross-agent ~/.agents/skills dir for Codex.
+    //     Both best-effort: neither existing is the common case.
+    if (grokInstallState().exists) {
+        spawnSyncCommand(resolveCommand('grok'), ['plugin', 'uninstall', 'gipity', '--confirm'], {
+            stdio: 'ignore',
+            timeout: 60_000,
+        });
+        console.log(`${success('Gipity plugin removed from Grok.')}`);
+    }
+    const agentSkills = agentSkillsState();
+    if (agentSkills.skills.length) {
+        for (const name of agentSkills.skills) {
+            // Only names our manifest recorded - never someone else's skills.
+            try {
+                rmSync(join(AGENTS_SKILLS_DIR, name), { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        console.log(`${success(`Removed ${agentSkills.skills.length} Gipity skills from ~/.agents/skills.`)}`);
+    }
+    // 5. Wipe ~/.gipity/ (this also removes the agent-hooks scripts and the
+    //    agent-skills manifest, which live under it).
     if (existsSync(gipityDir)) {
         try {
             rmSync(gipityDir, { recursive: true, force: true });

package/dist/hooks/capture-runner.js

@@ -1,31 +1,36 @@
 #!/usr/bin/env node
 /**
- * Internal hook runner - invoked by Claude Code's lifecycle hooks
+ * Internal hook runner - invoked by the coding agent's lifecycle hooks
  * (SessionStart, Stop, SubagentStop, SessionEnd, and a throttled
- * 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.
+ * PostToolUse for mid-run flushing) to mirror a terminal agent session
+ * into the Gipity server so the web CLI can display it read-only.
+ *
+ * Works for every supported agent: Claude Code and Grok Build fire it
+ * through the Gipity plugin's hooks (Grok runs Claude-format plugin hooks
+ * natively; capture.cjs rewrites the source to 'grok' when it sees
+ * GROK_HOOK_EVENT), Codex through the project's .codex/hooks.json. Each
+ * source has its own transcript parser under cli/src/capture/sources/.
  *
  * Not a user-facing `gipity` subcommand by design: users never invoke
- * this directly. The Gipity Claude Code plugin's capture hook script
- * (skills repo hooks/scripts/capture.cjs) resolves this file inside the
- * installed CLI at fire time and runs it - so the capture logic versions
- * with the CLI, not the plugin.
+ * this directly. The hook scripts (skills repo hooks/scripts/capture.cjs)
+ * resolve this file inside the installed CLI at fire time and run it - so
+ * the capture logic versions with the CLI, not the plugin.
  *
  * Usage:
  *   node capture-runner.js <source> <event>
- *   source: 'claude-code' (today) | future: 'codex', …
+ *   source: 'claude-code' | 'codex' | 'grok'
  *   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.
+ *   1. GIPITY_CONVERSATION_GUID env var - set by `gipity build`, which
+ *      created/reused the conversation before spawning the agent.
  *   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.
+ *   3. Self-arm: the session was launched WITHOUT `gipity build` (bare
+ *      `claude` / `codex` / `grok` 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 agent sessions record.
  *
  * Graceful no-ops (exit 0 silently):
  *   - GIPITY_CAPTURE=off - the relay daemon owns capture for this run
@@ -36,16 +41,43 @@
  *   - Anything unexpected (parse error, network error, etc.). We must
  *     not break the user's interactive session.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, openSync, closeSync, statSync, utimesSync, createReadStream, } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, openSync, closeSync, statSync, utimesSync, createReadStream, } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { getDevice } from '../relay/state.js';
 import { deviceFetch } from '../relay/device-http.js';
 import { ImageBlockRewriter } from '../relay/media-upload.js';
 import { getConfig } from '../config.js';
-import { parseTranscript, } from '../capture/sources/claude-code.js';
+import { parseTranscript as parseClaudeTranscript, } from '../capture/sources/claude-code.js';
+import { parseTranscript as parseCodexTranscript } from '../capture/sources/codex.js';
+import { parseTranscript as parseGrokTranscript } from '../capture/sources/grok.js';
 const CAPTURE_DIR = join(homedir(), '.gipity', 'capture-state');
 const INGEST_BATCH_MAX = 100; // server caps at 200; stay comfortably under
+export const CAPTURE_SOURCES = {
+    'claude-code': {
+        serverSource: 'claude_code',
+        displayName: 'Claude Code',
+        parse: (content, afterUuid) => parseClaudeTranscript(content, afterUuid),
+    },
+    codex: {
+        serverSource: 'codex',
+        displayName: 'Codex',
+        // Codex hook payloads always carry transcript_path (the rollout file).
+        parse: (content, afterUuid) => parseCodexTranscript(content, afterUuid),
+    },
+    grok: {
+        serverSource: 'grok',
+        displayName: 'Grok',
+        parse: (content, afterUuid, hook) => parseGrokTranscript(content, afterUuid, { sessionId: hook.session_id }),
+        // Grok's session dir is derivable: ~/.grok/sessions/<urlencoded-cwd>/<sid>/
+        resolveTranscriptPath: (hook) => {
+            if (!hook.session_id)
+                return null;
+            const cwd = hook.cwd ?? process.cwd();
+            return join(homedir(), '.grok', 'sessions', encodeURIComponent(cwd), hook.session_id, 'chat_history.jsonl');
+        },
+    },
+};
 // PostToolUse fires after every tool call. We flush on it so a session that is
 // killed/crashes mid-run (e.g. a long headless `gipity claude -p` build that
 // hits a timeout) still has its transcript in the DB - Stop/SessionEnd only
@@ -212,13 +244,14 @@ function deleteSessionMap(sessionId) {
  *  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) {
+async function resolveFromServer(projectGuid, hook, serverSource) {
     let res;
     try {
         res = await deviceFetch('POST', '/remote-sessions/resolve', {
             project_guid: projectGuid,
             session_id: hook.session_id,
             cwd: hook.cwd,
+            source: serverSource,
         }, 15_000);
     }
     catch {
@@ -240,7 +273,7 @@ async function resolveFromServer(projectGuid, hook) {
  *  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))) {
+export async function resolveConvGuid(hook, serverSource = 'claude_code', sleep = (ms) => new Promise(r => setTimeout(r, ms))) {
     const fromEnv = process.env.GIPITY_CONVERSATION_GUID;
     if (fromEnv)
         return fromEnv;
@@ -276,7 +309,7 @@ export async function resolveConvGuid(hook, sleep = (ms) => new Promise(r => set
         const raced = readSessionMap(sessionId);
         if (raced)
             return raced;
-        const conv = await resolveFromServer(config.projectGuid, hook);
+        const conv = await resolveFromServer(config.projectGuid, hook, serverSource);
         if (conv)
             writeSessionMap(sessionId, conv);
         return conv;
@@ -338,7 +371,7 @@ async function handleSessionStart(convGuid, hook) {
         }];
     await postEntries(convGuid, entries);
 }
-async function handleStopFamily(convGuid, hook, isSubagent, minIntervalMs = 0) {
+async function handleStopFamily(convGuid, src, hook, isSubagent, minIntervalMs = 0) {
     void isSubagent;
     if (!hook.transcript_path || !existsSync(hook.transcript_path))
         return;
@@ -355,11 +388,11 @@ async function handleStopFamily(convGuid, hook, isSubagent, minIntervalMs = 0) {
     try {
         const state = readState(convGuid) ?? { last_uuid: null };
         const content = await readWholeFile(hook.transcript_path);
-        let result = parseTranscript(content, state.last_uuid);
+        let result = src.parse(content, state.last_uuid, hook);
         if (!result.foundWatermark && state.last_uuid !== null) {
             // Transcript rotated (/clear or compact) - watermark isn't present.
             // Replay from top; server dedupes via the source_uuid unique index.
-            result = parseTranscript(content, null);
+            result = src.parse(content, null, hook);
         }
         // Base64 image blocks (Read-of-image tool results) upload to VFS and
         // become image_ref blocks — same no-inline-base64 chokepoint as the
@@ -379,18 +412,17 @@ async function handleStopFamily(convGuid, hook, isSubagent, minIntervalMs = 0) {
         release();
     }
 }
-async function handleSessionEnd(convGuid, hook, source) {
+async function handleSessionEnd(convGuid, src, hook) {
     // Flush any tail lines one last time - SessionEnd fires after the final
     // Stop, so there's usually nothing new, but a race between Stop and
     // SessionEnd could leave lines behind.
     if (hook.transcript_path && existsSync(hook.transcript_path)) {
-        await handleStopFamily(convGuid, hook, false);
+        await handleStopFamily(convGuid, src, hook, false);
     }
     const sessionId = hook.session_id ?? 'unknown';
-    const finishedLabel = displayName(source);
     const entries = [{
             kind: 'system',
-            content: `${finishedLabel} finished`,
+            content: `${src.displayName} finished`,
             source_uuid: `${sessionId}-end`,
         }];
     await postEntries(convGuid, entries);
@@ -398,10 +430,54 @@ async function handleSessionEnd(convGuid, hook, source) {
     if (hook.session_id)
         deleteSessionMap(hook.session_id);
 }
-function displayName(source) {
-    if (source === 'claude-code')
-        return 'Claude Code';
-    return source;
+// Codex has no SessionEnd hook, so its capture-state/session-map files are
+// never cleaned by handleSessionEnd. Sweep anything stale on the way through
+// - the files are tiny, so a generous TTL is fine; a live session's state is
+// rewritten on every flush and never gets this old.
+const STATE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+function sweepStaleState() {
+    let names;
+    try {
+        names = readdirSync(CAPTURE_DIR);
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - STATE_TTL_MS;
+    for (const name of names) {
+        const p = join(CAPTURE_DIR, name);
+        try {
+            if (statSync(p).mtimeMs < cutoff)
+                unlinkSync(p);
+        }
+        catch { /* raced or unreadable - leave it */ }
+    }
+}
+/** Normalize a raw hook payload to snake_case HookInput. Claude Code and
+ *  Codex deliver snake_case (`session_id`, `transcript_path`, `cwd`); Grok
+ *  Build delivers camelCase (`sessionId`, `hookEventName`, …). Accept both
+ *  so one runner serves every harness. */
+export function normalizeHookInput(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const pick = (...keys) => {
+        for (const k of keys) {
+            const v = raw[k];
+            if (typeof v === 'string' && v)
+                return v;
+        }
+        return undefined;
+    };
+    const hook = {
+        session_id: pick('session_id', 'sessionId'),
+        transcript_path: pick('transcript_path', 'transcriptPath'),
+        cwd: pick('cwd', 'workingDirectory'),
+        hook_event_name: pick('hook_event_name', 'hookEventName'),
+    };
+    // Preserve extras the handlers peek at (e.g. pre-compact's `trigger`).
+    if (typeof raw.trigger === 'string')
+        hook.trigger = raw.trigger;
+    return hook;
 }
 async function main() {
     // Explicit capture opt-out. Set by the relay daemon's dispatch spawns
@@ -415,15 +491,28 @@ async function main() {
     const [source, event] = process.argv.slice(2);
     if (!source || !event)
         return;
+    const src = CAPTURE_SOURCES[source];
+    if (!src)
+        return; // unknown agent - silent no-op
     const stdin = await readStdin();
     let hook = {};
     if (stdin.trim()) {
         try {
-            hook = JSON.parse(stdin);
+            hook = normalizeHookInput(JSON.parse(stdin));
         }
         catch { /* ignore - event may not require transcript */ }
     }
-    const convGuid = await resolveConvGuid(hook);
+    // Agents whose hook payloads omit the transcript path (Grok) get it
+    // derived from the session id + cwd.
+    if (!hook.transcript_path && src.resolveTranscriptPath) {
+        const derived = src.resolveTranscriptPath(hook);
+        if (derived)
+            hook.transcript_path = derived;
+    }
+    // Opportunistic hygiene: Codex never fires session-end, so its state
+    // files are TTL-swept instead of deleted at end-of-session.
+    sweepStaleState();
+    const convGuid = await resolveConvGuid(hook, src.serverSource);
     if (!convGuid)
         return; // not a Gipity-bound session - nothing to capture
     try {
@@ -432,24 +521,24 @@ async function main() {
                 await handleSessionStart(convGuid, hook);
                 break;
             case 'stop':
-                await handleStopFamily(convGuid, hook, false);
+                await handleStopFamily(convGuid, src, hook, false);
                 break;
             case 'subagent-stop':
-                await handleStopFamily(convGuid, hook, true);
+                await handleStopFamily(convGuid, src, hook, true);
                 break;
             case 'post-tool-use':
                 // Incremental mid-run flush so an interrupted session keeps its
                 // transcript (Stop/SessionEnd only fire on clean exit). Throttled.
-                await handleStopFamily(convGuid, hook, false, POST_TOOL_FLUSH_MS);
+                await handleStopFamily(convGuid, src, hook, false, POST_TOOL_FLUSH_MS);
                 break;
             case 'session-end':
-                await handleSessionEnd(convGuid, hook, source);
+                await handleSessionEnd(convGuid, src, hook);
                 break;
             case 'pre-compact': {
                 // Flush the transcript tail BEFORE compaction rewrites it (the
                 // watermark replay after a rewrite relies on server dedup, but
                 // flushing first keeps ordering clean), then record the boundary.
-                await handleStopFamily(convGuid, hook, false);
+                await handleStopFamily(convGuid, src, hook, false);
                 const trigger = typeof hook.trigger === 'string' ? hook.trigger : 'auto';
                 await postEntries(convGuid, [{
                         kind: 'compact',