gipity 1.0.409 → 1.0.411

package/dist/relay/ingest-queue.js

@@ -0,0 +1,148 @@
+const DEFAULTS = {
+    maxEntries: 2000,
+    maxBytes: 8 * 1024 * 1024,
+    batchMax: 200,
+    backoffMs: [2000, 5000, 15000, 60000],
+};
+function entryBytes(e) {
+    try {
+        return JSON.stringify(e).length;
+    }
+    catch {
+        return 1024;
+    }
+}
+export class IngestQueue {
+    post;
+    queue = [];
+    bytes = 0;
+    draining = false;
+    closed = false;
+    closeDeadline = 0;
+    drainDone = Promise.resolve();
+    droppedTotal = 0;
+    markedDrop = false;
+    opts;
+    constructor(post, opts = {}) {
+        this.post = post;
+        this.opts = { ...DEFAULTS, ...opts };
+    }
+    get dropped() {
+        return this.droppedTotal;
+    }
+    /** Enqueue entries in order and kick the drainer. Sync and non-blocking. */
+    push(...entries) {
+        if (this.closed) {
+            this.opts.onWarn?.('ingest queue push after close - dropped', { count: entries.length });
+            this.droppedTotal += entries.length;
+            return;
+        }
+        for (const entry of entries) {
+            const bytes = entryBytes(entry);
+            this.queue.push({ entry, bytes });
+            this.bytes += bytes;
+        }
+        this.enforceBounds();
+        this.kick();
+    }
+    /** Stop accepting entries and drain what's left, giving up at the
+     *  deadline. Returns whether everything flushed. */
+    async close(deadlineMs = 30_000) {
+        this.closed = true;
+        this.closeDeadline = Date.now() + deadlineMs;
+        this.kick();
+        // Await until the drainer has fully settled. The re-kick in `kick`'s
+        // finally is gated on `!closed`, so once we're here no NEW drain can
+        // start - a single settled await is sufficient, but loop defensively
+        // in case a kick was mid-settle when `closed` flipped.
+        while (this.draining)
+            await this.drainDone;
+        await this.drainDone;
+        const flushed = this.queue.length === 0;
+        if (!flushed) {
+            this.droppedTotal += this.queue.length;
+            this.opts.onWarn?.('ingest queue close deadline hit - entries lost', { remaining: this.queue.length });
+            this.queue = [];
+            this.bytes = 0;
+        }
+        return { flushed, dropped: this.droppedTotal };
+    }
+    enforceBounds() {
+        let droppedNow = 0;
+        while (this.queue.length > this.opts.maxEntries || this.bytes > this.opts.maxBytes) {
+            const victim = this.queue.shift();
+            if (!victim)
+                break;
+            this.bytes -= victim.bytes;
+            droppedNow++;
+        }
+        if (droppedNow > 0) {
+            this.droppedTotal += droppedNow;
+            this.opts.onWarn?.('ingest queue overflow - oldest entries dropped', { droppedNow, droppedTotal: this.droppedTotal });
+            if (!this.markedDrop) {
+                this.markedDrop = true;
+                // Visible gap marker, placed at the head so it lands before the
+                // surviving (newer) entries.
+                const marker = { kind: 'system', content: 'Some session output could not be uploaded (upload backlog overflowed).' };
+                this.queue.unshift({ entry: marker, bytes: entryBytes(marker) });
+                this.bytes += entryBytes(marker);
+            }
+        }
+    }
+    kick() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        this.drainDone = this.drain().finally(() => {
+            this.draining = false;
+            // Entries may have arrived while the final await of drain() settled.
+            // Never re-kick once closed: close() owns the last drain, and a
+            // re-kick here would POST a batch AFTER close() returned (the
+            // zombie-drain bug - post-after-ack + corrupted byte accounting).
+            if (this.queue.length && !this.closed)
+                this.kick();
+        });
+    }
+    async drain() {
+        const sleep = this.opts.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+        let attempt = 0;
+        while (this.queue.length) {
+            // Remove the batch from the queue BEFORE awaiting the POST. A push
+            // that overflows the bounds during the await runs `enforceBounds`,
+            // which shifts the queue head - if the in-flight batch were still
+            // at the head, a later splice-by-index would remove the wrong
+            // entries and drift `bytes`. Holding the batch out of the queue
+            // makes overflow touch only not-in-flight entries.
+            const batch = this.queue.splice(0, this.opts.batchMax);
+            const batchBytes = batch.reduce((n, b) => n + b.bytes, 0);
+            this.bytes -= batchBytes;
+            const result = await this.post(batch.map(b => b.entry));
+            if (result.ok) {
+                attempt = 0;
+                continue;
+            }
+            // Definitive rejection (4xx: schema or auth) - a replay can never
+            // succeed, and retrying would stall the queue behind a poisoned
+            // batch. Drop it (counted + warned) and move on.
+            if (result.retryable === false) {
+                attempt = 0;
+                this.droppedTotal += batch.length;
+                this.opts.onWarn?.('ingest batch rejected by server - dropped', { count: batch.length });
+                continue;
+            }
+            // Transient failure: put the batch back at the head and retry after
+            // backoff (order preserved; source_uuid dedup makes a partial
+            // server-side success safe).
+            this.queue.unshift(...batch);
+            this.bytes += batchBytes;
+            const backoff = this.opts.backoffMs[Math.min(attempt, this.opts.backoffMs.length - 1)];
+            attempt++;
+            if (this.closed && Date.now() + backoff > this.closeDeadline)
+                return;
+            await sleep(backoff);
+            if (this.closed && Date.now() > this.closeDeadline)
+                return;
+        }
+    }
+}
+//# sourceMappingURL=ingest-queue.js.map

package/dist/relay/installers.js

@@ -60,7 +60,15 @@ function launchdPlan(cliPath) {
     <string>run</string>
   </array>
   <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><true/>
+  <!-- Restart ONLY on a non-zero exit, mirroring systemd's Restart=on-failure.
+       The daemon exits 0 on a clean revoke/shutdown; a bare KeepAlive=true
+       would relaunch it anyway, and run() would then silently re-register a
+       new device - undoing the revoke. SuccessfulExit=false keeps crash
+       recovery without that re-pair loop. -->
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key><false/>
+  </dict>
   <key>StandardOutPath</key><string>${join(logDir, 'relay.out.log')}</string>
   <key>StandardErrorPath</key><string>${join(logDir, 'relay.err.log')}</string>
   <key>ProcessType</key><string>Background</string>
@@ -80,7 +88,7 @@ function launchdPlan(cliPath) {
         enableDisplay: display(enableCmds),
         disableDisplay: display(disableCmds),
         statusDisplay: statusCmd.join(' '),
-        summary: 'LaunchAgent at ~/Library/LaunchAgents/ai.gipity.relay.plist (starts at login, auto-restarts)',
+        summary: 'LaunchAgent at ~/Library/LaunchAgents/ai.gipity.relay.plist (starts at login, restarts on failure)',
     };
 }
 // ─── Linux - systemd --user unit ───────────────────────────────────────

package/dist/relay/onboarding.js

@@ -56,8 +56,11 @@ export async function maybeOfferRelayOn() {
     }
     catch (err) {
         console.error(`\n  ${clrError(`Could not create device: ${err?.message || err}`)}`);
-        console.error(`  ${dim('Skipping relay setup. Try later with `gipity relay install`.')}`);
-        state.setRelayEnabled(false);
+        console.error(`  ${dim('Skipping for now - we\'ll offer again next time. Or turn it on with `gipity relay install`.')}`);
+        // Deliberately DON'T persist relay_enabled here: the user SAID YES, and
+        // this is a transient failure (network blip, server down). Leaving the
+        // tri-state unset means onboarding re-offers on the next `gipity claude`
+        // run instead of silently opting the user out forever.
         return;
     }
     // Start the daemon for this session.

package/dist/relay/redact.js

@@ -38,15 +38,38 @@ const JWT_RE = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
  *  literal-secret list. An `sk-ant-` token in a relay transcript is always a
  *  credential, so over-redaction risk is negligible. */
 const ANTHROPIC_KEY_RE = /sk-ant-[A-Za-z0-9_-]{20,}/g;
-/** Replace every occurrence of each known secret - and any JWT- or
- *  Anthropic-key-shaped substring - in `text` with the marker. */
-function redactString(text, secrets) {
+/** Well-known third-party credential shapes. A `bypassPermissions` session can
+ *  read the host's environment and files, so a `cat .env` / `env` could echo
+ *  ANY of these into the transcript - not just the Gipity/Anthropic tokens on
+ *  the literal-secret list. Each pattern is a high-entropy, provider-specific
+ *  prefix that is effectively never a false positive in a relay transcript, so
+ *  the over-redaction risk is the same negligible trade-off already accepted
+ *  for the JWT and `sk-ant-` passes. Extend this list as new providers appear;
+ *  it is defense-in-depth, NOT a guarantee (a base64/chunked secret still
+ *  slips through - the real backstop remains an instantly-revocable
+ *  credential). */
+const THIRD_PARTY_KEY_RES = [
+    /sk-[A-Za-z0-9_-]{20,}/g, // OpenAI (sk-, sk-proj-) + any sk- key
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/g, // GitHub tokens
+    /\bgithub_pat_[A-Za-z0-9_]{60,}\b/g, // GitHub fine-grained PAT
+    /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+    /\b(?:sk|rk)_live_[A-Za-z0-9]{20,}\b/g, // Stripe live secret/restricted key
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, // Slack tokens
+    /\bAIza[A-Za-z0-9_-]{35}\b/g, // Google API key
+    /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g, // PEM private keys
+];
+/** Replace every occurrence of each known secret - plus any JWT-, Anthropic-,
+ *  or well-known-third-party-key-shaped substring - in `text` with the marker. */
+export function redactString(text, secrets) {
     let out = text;
     for (const secret of secrets) {
         if (out.includes(secret))
             out = out.split(secret).join(REDACTION_MARKER);
     }
-    return out.replace(JWT_RE, REDACTION_MARKER).replace(ANTHROPIC_KEY_RE, REDACTION_MARKER);
+    out = out.replace(JWT_RE, REDACTION_MARKER).replace(ANTHROPIC_KEY_RE, REDACTION_MARKER);
+    for (const re of THIRD_PARTY_KEY_RES)
+        out = out.replace(re, REDACTION_MARKER);
+    return out;
 }
 /** Deep-walk any JSON-ish value, redacting every string. Returns a new
  *  value; objects/arrays are cloned, primitives passed through. */

package/dist/relay/setup.js

@@ -10,7 +10,7 @@
  * the interactive prompts that live in `onboarding.ts`. No `console` output
  * and no `process.exit` in this module: callers own all UX.
  */
-import { spawn, spawnSync } from 'child_process';
+import { spawnCommand, spawnSyncCommand } from '../platform.js';
 import { hostname, platform as osPlatform } from 'os';
 import { resolve, dirname } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
@@ -87,7 +87,7 @@ export function startDaemon() {
     if (state.isDaemonRunning())
         return;
     try {
-        const child = spawn(process.execPath, [resolveCliPath(), 'relay', 'run'], {
+        const child = spawnCommand(process.execPath, [resolveCliPath(), 'relay', 'run'], {
             detached: true,
             stdio: 'ignore',
         });
@@ -118,7 +118,7 @@ export function installAutostart(opts = {}) {
     writeFileSync(plan.path, plan.content);
     let ok = true;
     for (const argv of plan.enableCmds) {
-        const r = spawnSync(argv[0], argv.slice(1), { stdio });
+        const r = spawnSyncCommand(argv[0], argv.slice(1), { stdio });
         if (r.status !== 0) {
             ok = false;
             break;
@@ -136,7 +136,7 @@ export function removeAutostart(opts = {}) {
     const plan = planFor({ cliPath: resolveCliPath() });
     let ok = true;
     for (const argv of plan.disableCmds) {
-        const r = spawnSync(argv[0], argv.slice(1), { stdio });
+        const r = spawnSyncCommand(argv[0], argv.slice(1), { stdio });
         if (r.status !== 0)
             ok = false;
     }

package/dist/relay/state.js

@@ -47,9 +47,12 @@ export function loadState() {
 }
 export function saveState(state) {
     mkdirSync(RELAY_DIR, { recursive: true });
-    writeFileSync(RELAY_FILE, JSON.stringify(state, null, 2) + '\n');
-    // Token is inside - enforce owner-only even if the file existed with
-    // looser permissions before.
+    // `mode` on write means a NEWLY-created file is owner-only from the first
+    // byte - no window where it exists at the umask default (typically 0644)
+    // before a follow-up chmod tightens it. The chmodSync still runs to fix a
+    // file that already existed with looser permissions (mode is ignored for
+    // an existing file).
+    writeFileSync(RELAY_FILE, JSON.stringify(state, null, 2) + '\n', { mode: FILE_MODE });
     try {
         chmodSync(RELAY_FILE, FILE_MODE);
     }

package/dist/relay/stream-delta.js

@@ -0,0 +1,235 @@
+/**
+ * Token-streaming delta pipeline for the relay daemon.
+ *
+ * With `--include-partial-messages`, Claude Code emits `stream_event`
+ * envelopes (content_block_start / content_block_delta / content_block_stop)
+ * carrying text, thinking, and tool-input fragments as they generate. The
+ * daemon forwards them - throttled and redacted - to
+ * `POST /remote-sessions/:convGuid/stream-delta`, which the server
+ * broadcasts to the web CLI as `dispatch:delta`. Purely ephemeral: no DB
+ * write, no retry; the persisted assistant/tool entries (whole events)
+ * remain the source of truth and replace the streamed view on the next
+ * refresh.
+ *
+ * Redaction across chunk boundaries: a secret split over two fragments
+ * would defeat a per-fragment scrub. The accumulator therefore only ever
+ * emits up to the last WHITESPACE boundary (holding back the trailing
+ * partial token until more input or block close) and scrubs each emitted
+ * span. Secrets in our threat set (host OAuth/API/device tokens, JWTs,
+ * provider keys) are contiguous non-whitespace tokens, so a held-back
+ * partial token can never leak a complete secret and a completed token is
+ * always scrubbed whole. Multi-line PEM blocks are the one shape this
+ * can't fully hold back - accepted on this ephemeral channel (the
+ * persisted path fully redacts, and the streamed text is replaced by the
+ * redacted stored message within seconds).
+ */
+import { redactString } from './redact.js';
+/** A trailing token longer than this is emitted anyway (minified code,
+ *  base64 blobs) - holding back indefinitely would stall the stream. No
+ *  credential in our threat set is this long. */
+const MAX_HOLDBACK = 4096;
+/** PEM key markers. A private key block spans multiple whitespace-
+ *  separated lines, so the whitespace-boundary holdback would emit
+ *  `BEGIN` before `END` arrives and per-span redaction would miss it.
+ *  emitUpTo holds the whole block back until END so it scrubs whole. */
+const PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+/** Emit boundary: everything up to (and including) the last whitespace.
+ *  `closing` (block stop) emits everything. */
+export function safeEmitBoundary(s, closing) {
+    if (closing)
+        return s.length;
+    const m = s.match(/\S+$/);
+    if (!m)
+        return s.length;
+    if (m[0].length > MAX_HOLDBACK)
+        return s.length;
+    return s.length - m[0].length;
+}
+/**
+ * Per-spawn accumulator: feed it raw stream_event envelopes, it returns
+ * redaction-safe StreamDeltaEvents ready to batch. Skips subagent events
+ * (parent_tool_use_id set) - those belong to the nested Task timeline,
+ * not the main stream zone.
+ */
+export class DeltaAccumulator {
+    getSecrets;
+    blocks = new Map();
+    /** The in-flight message's id, captured from `message_start` -
+     *  content_block_* events don't carry it themselves. This is what makes
+     *  the client-side finalize swap line up: persisted assistant rows are
+     *  keyed `msg_id#n` (Phase 2 source_uuid), streamed blocks `msg_id:n`. */
+    currentMessageId = 'msg';
+    constructor(getSecrets) {
+        this.getSecrets = getSecrets;
+    }
+    /** Map one parsed stream-json event to zero or more delta events. */
+    note(evt) {
+        if (evt.type !== 'stream_event')
+            return [];
+        if (evt.parent_tool_use_id)
+            return []; // subagent stream - not ours (Phase 6)
+        const inner = evt.event;
+        if (!inner || typeof inner.type !== 'string')
+            return [];
+        if (inner.type === 'message_start') {
+            if (typeof inner.message?.id === 'string' && inner.message.id) {
+                this.currentMessageId = inner.message.id;
+            }
+            return [];
+        }
+        const messageId = this.currentMessageId;
+        if (inner.type === 'content_block_start') {
+            const idx = typeof inner.index === 'number' ? inner.index : 0;
+            const cb = inner.content_block ?? {};
+            const type = cb.type === 'text' ? 'text' : cb.type === 'thinking' ? 'thinking' : cb.type === 'tool_use' ? 'tool_use' : null;
+            if (!type)
+                return [];
+            this.blocks.set(`${messageId}:${idx}`, { type, raw: '', rawEmitted: 0, outEmitted: 0, started: true });
+            const out = { message_id: messageId, block_index: idx, block_type: type, kind: 'start' };
+            if (type === 'tool_use' && typeof cb.name === 'string')
+                out.tool_name = cb.name;
+            return [out];
+        }
+        if (inner.type === 'content_block_delta') {
+            const idx = typeof inner.index === 'number' ? inner.index : 0;
+            const d = inner.delta ?? {};
+            const fragment = typeof d.text === 'string' ? d.text
+                : typeof d.thinking === 'string' ? d.thinking
+                    : typeof d.partial_json === 'string' ? d.partial_json
+                        : null;
+            if (fragment === null || fragment === '')
+                return [];
+            const key = `${messageId}:${idx}`;
+            let b = this.blocks.get(key);
+            if (!b) {
+                // Delta without a start (daemon restarted mid-message or an
+                // unknown block type at start time) - infer the type.
+                const type = typeof d.partial_json === 'string' ? 'tool_use'
+                    : typeof d.thinking === 'string' ? 'thinking' : 'text';
+                b = { type, raw: '', rawEmitted: 0, outEmitted: 0, started: false };
+                this.blocks.set(key, b);
+            }
+            b.raw += fragment;
+            return this.emitUpTo(messageId, idx, b, false);
+        }
+        if (inner.type === 'content_block_stop') {
+            const idx = typeof inner.index === 'number' ? inner.index : 0;
+            const key = `${messageId}:${idx}`;
+            const b = this.blocks.get(key);
+            if (!b)
+                return [];
+            const out = this.emitUpTo(messageId, idx, b, true);
+            out.push({ message_id: messageId, block_index: idx, block_type: b.type, kind: 'stop' });
+            this.blocks.delete(key);
+            return out;
+        }
+        return [];
+    }
+    emitUpTo(messageId, idx, b, closing) {
+        // Scan only the not-yet-emitted tail: the boundary can never precede
+        // rawEmitted (already a whitespace boundary), and running the regex
+        // over the full accumulated `raw` on every fragment is O(n²) over a
+        // long block - a big minified/base64 tool-input block would stall the
+        // daemon's event loop (which also drives the ingest queue + ticks).
+        const tail = b.raw.slice(b.rawEmitted);
+        // PEM keys are the one multi-LINE secret the whitespace-boundary
+        // holdback doesn't catch: `-----BEGIN … PRIVATE KEY-----` and its
+        // `-----END-----` land in different spans, so per-span redactString
+        // never sees them together. When an unterminated BEGIN marker is in
+        // the pending tail, hold the WHOLE tail back until END arrives (or the
+        // block closes), so redactString scrubs the complete block in one span.
+        if (!closing && PEM_BEGIN.test(tail) && !PEM_END.test(tail))
+            return [];
+        const tailBoundary = safeEmitBoundary(tail, closing);
+        if (tailBoundary <= 0)
+            return [];
+        const span = tail.slice(0, tailBoundary);
+        const boundary = b.rawEmitted + tailBoundary;
+        b.rawEmitted = boundary;
+        const scrubbed = redactString(span, this.getSecrets());
+        if (!scrubbed)
+            return [];
+        const evt = {
+            message_id: messageId,
+            block_index: idx,
+            block_type: b.type,
+            kind: 'delta',
+            text: scrubbed,
+            acc_offset: b.outEmitted,
+        };
+        b.outEmitted += scrubbed.length;
+        return [evt];
+    }
+}
+// ─── Throttled batcher ──────────────────────────────────────────────────
+const FLUSH_INTERVAL_MS = 150;
+const FLUSH_BYTES = 4096;
+/** Server-side caps (mirror the /stream-delta Zod schema). */
+const MAX_EVENTS_PER_FLUSH = 64;
+const MAX_TEXT_PER_FLUSH = 16_384;
+/**
+ * Buffers delta events and flushes them as numbered batches every 150ms
+ * or 4KB, whichever first. Fire-and-forget by design: a lost flush
+ * self-heals (the client detects the `acc_offset` gap and the next
+ * refresh replaces the stream zone with the stored message anyway).
+ */
+export class DeltaBatcher {
+    send;
+    intervalMs;
+    buffer = [];
+    bufferedText = 0;
+    seq = 0;
+    timer = null;
+    closed = false;
+    constructor(send, intervalMs = FLUSH_INTERVAL_MS) {
+        this.send = send;
+        this.intervalMs = intervalMs;
+    }
+    push(events) {
+        if (this.closed || events.length === 0)
+            return;
+        for (const e of events) {
+            this.buffer.push(e);
+            this.bufferedText += e.text?.length ?? 0;
+        }
+        if (this.bufferedText >= FLUSH_BYTES || this.buffer.length >= MAX_EVENTS_PER_FLUSH) {
+            this.flush();
+            return;
+        }
+        if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), this.intervalMs);
+            this.timer.unref?.();
+        }
+    }
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        while (this.buffer.length) {
+            // Respect both server caps per POST: event count and total text.
+            const batch = [];
+            let text = 0;
+            while (this.buffer.length && batch.length < MAX_EVENTS_PER_FLUSH) {
+                const next = this.buffer[0];
+                const nextLen = next.text?.length ?? 0;
+                if (batch.length > 0 && text + nextLen > MAX_TEXT_PER_FLUSH)
+                    break;
+                // A single oversized event gets truncated rather than wedging the queue.
+                if (nextLen > MAX_TEXT_PER_FLUSH)
+                    next.text = next.text.slice(0, MAX_TEXT_PER_FLUSH);
+                batch.push(this.buffer.shift());
+                text += next.text?.length ?? 0;
+            }
+            this.bufferedText = Math.max(0, this.bufferedText - text);
+            this.send({ seq: this.seq++, events: batch });
+        }
+        this.bufferedText = 0;
+    }
+    close() {
+        this.flush();
+        this.closed = true;
+    }
+}
+//# sourceMappingURL=stream-delta.js.map

package/dist/relay/stream-json.js

@@ -58,31 +58,61 @@ function joinAssistantText(content) {
     }
     return parts.join('\n');
 }
-/** Map a single stream-json event to zero or more ingest entries. An
- *  assistant event may yield one `assistant` entry AND one `tool_use`
- *  entry per tool_use block within it (server persists each tool call
- *  as its own `role='tool'` row, then updates it when the matching
- *  `tool_result` arrives).
- *
- *  `toolNames` (optional) is a per-dispatch `tool_use_id → tool_name`
- *  map threaded across events by the daemon: assistant events record
- *  each tool call's name, the later user event with the paired
- *  `tool_result` reads it back so the server can denormalize `tool_name`
- *  onto the tool row even when the result lands as a stub. */
-export function mapEventToEntries(evt, toolNames) {
+export function mapEventToEntries(evt, ctx) {
+    // Back-compat: older call sites (and tests) pass the bare toolNames map.
+    const c = ctx instanceof Map ? { toolNames: ctx } : (ctx ?? {});
+    const toolNames = c.toolNames;
     const out = [];
     if (evt.type === 'system' && evt.subtype === 'init') {
         const s = evt;
-        if (s.session_id)
-            out.push({ kind: 'attach', session_id: s.session_id, cwd: s.cwd, source: 'startup' });
+        if (s.session_id) {
+            out.push({
+                kind: 'attach',
+                session_id: s.session_id,
+                cwd: s.cwd,
+                source: 'startup',
+                model: typeof s.model === 'string' ? s.model : undefined,
+                tools_count: Array.isArray(s.tools) ? s.tools.length : undefined,
+                mcp_count: Array.isArray(s.mcp_servers) ? s.mcp_servers.length : undefined,
+                api_key_source: typeof s.apiKeySource === 'string' ? s.apiKeySource : undefined,
+            });
+        }
         return out;
     }
+    // Context compaction boundary - the server has a `compact` kind for this
+    // (renders as a "context compacted" marker); nothing emitted it before.
+    if (evt.type === 'system' && evt.subtype === 'compact_boundary') {
+        const trigger = evt.compact_metadata?.trigger ?? evt.trigger;
+        out.push({ kind: 'compact', trigger: typeof trigger === 'string' ? trigger : undefined });
+        return out;
+    }
+    // Subagent attribution: the envelope carries the spawning Task/Agent
+    // tool_use id on every event from that subagent's turn.
+    const parentToolUseId = typeof evt.parent_tool_use_id === 'string'
+        ? evt.parent_tool_use_id : undefined;
     if (evt.type === 'assistant') {
         const msg = evt.message ?? {};
         const content = Array.isArray(msg.content) ? msg.content : [];
         const text = joinAssistantText(content);
         if (text || content.length) {
-            out.push({ kind: 'assistant', text, blocks: content, ...usageFields(msg) });
+            const entry = { kind: 'assistant', text, blocks: content, ...usageFields(msg), parent_tool_use_id: parentToolUseId };
+            // source_uuid = `${msg.id}#${eventSeq}`. The client's stream-zone
+            // finalize-swap matches this against its block key `${msg.id}:${block_index}`,
+            // i.e. it relies on eventSeq === block_index. That holds because
+            // Claude Code (with --include-partial-messages) emits exactly ONE
+            // assistant event per content block, in index order (verified
+            // against CLI v2.1.199 in the Phase 0 spike: a thinking block and a
+            // text block arrived as two separate assistant events, seq 0 and 1,
+            // matching block indices 0 and 1). If a future CLI ever packs two
+            // blocks into one assistant event, seq lags index for later blocks
+            // and those streamed blocks aren't removed until the ack wipes the
+            // zone - a cosmetic, self-healing duplication, not data loss.
+            if (typeof msg.id === 'string' && msg.id && c.msgSeq) {
+                const n = c.msgSeq.get(msg.id) ?? 0;
+                c.msgSeq.set(msg.id, n + 1);
+                entry.source_uuid = `${msg.id}#${n}`;
+            }
+            out.push(entry);
         }
         for (const block of content) {
             if (block?.type === 'tool_use' && typeof block.id === 'string') {
@@ -93,6 +123,8 @@ export function mapEventToEntries(evt, toolNames) {
                     tool_use_id: block.id,
                     tool_name: toolName,
                     tool_input: block.input ?? null,
+                    source_uuid: block.id,
+                    parent_tool_use_id: parentToolUseId,
                 });
             }
         }
@@ -109,6 +141,7 @@ export function mapEventToEntries(evt, toolNames) {
                     tool_name: toolNames?.get(block.tool_use_id),
                     content: block.content ?? null,
                     is_error: Boolean(block.is_error),
+                    parent_tool_use_id: parentToolUseId,
                 });
             }
         }
@@ -130,6 +163,19 @@ export function mapEventToEntries(evt, toolNames) {
         }
         return out;
     }
+    // Deliberately unmapped chatter (hook lifecycle, per-chunk thinking
+    // token counts, rate-limit notices, and stream_event token deltas -
+    // the latter are handled by the separate stream-delta pipeline) -
+    // skipped without accounting so a normal session doesn't log dozens of
+    // "unmapped" entries. Everything else unknown IS accounted via
+    // onUnmapped so a new Claude Code event type shows up in the daemon
+    // log instead of vanishing silently.
+    const subtype = evt.subtype;
+    const KNOWN_NOISE = new Set(['hook_started', 'hook_response', 'thinking_tokens', 'status', 'task_started', 'task_progress', 'task_updated', 'task_notification']);
+    if (!(evt.type === 'system' && subtype && KNOWN_NOISE.has(subtype))
+        && evt.type !== 'rate_limit_event' && evt.type !== 'stream_event') {
+        c.onUnmapped?.(evt.type, subtype);
+    }
     return out;
 }
 /** Pull token usage + model + stop_reason off an assistant stream `message`.