handmux 0.23.0 → 0.25.0

package/dist/src/transcriptParse.js

@@ -0,0 +1,261 @@
+// Pure: a Claude Code jsonl session log (array of lines) → normalized chat messages. No I/O.
+// Only user/assistant turns become bubbles; every other top-level `type` (attachment, system, last-prompt,
+// mode, permission-mode, ai-title, file-history-snapshot, queue-operation, …) is skipped. tool_use and its
+// later tool_result are folded into ONE tool message (paired by tool_use_id); an unmatched tool_result is
+// dropped (its tool_use is in an earlier, not-yet-loaded chunk). Bad/blank lines are skipped, never thrown.
+//
+// Meta scaffolding is DROPPED so the 对话 lens shows only real turns; the reliable signal is the top-level
+// boolean flags — `isMeta` (skill/workflow injections, "Base directory for this skill…", caveats) and
+// `isCompactSummary` (the "session is being continued…" wall) — NOT text matching.
+//
+// Slash commands (`/compact`, `/model`, `/clear`, …) are NOT dropped — they surface as a quiet 'slash'
+// marker (a centered system row), because a command the user ran IS part of the conversation and hiding it
+// leaves the phone with no feedback. Claude Code logs each as a `<command-name>/x</command-name>` USER turn
+// (the canonical form; the bare "/x" input is a separate queue-operation / plain user line we still drop, to
+// avoid a double). The command's `<local-command-stdout>` echo is folded onto the preceding marker as its
+// `.result` (ANSI-stripped, capped) — and its PRESENCE means the command COMPLETED. An interactive picker
+// (bare `/model`, `/plugin`, …) still open in the terminal has written no result yet, which is exactly how
+// the UI tells a finished command from one that needs the user to drop to the terminal lens and pick.
+// Matching is a tag prefix ANCHORED at the start of a USER turn's text: an assistant reply that merely
+// mentions `<command-name>` in prose (e.g. discussing this very code) must NOT be caught.
+const KEEP = new Set(['user', 'assistant']);
+const SCAFFOLD_RE = /^\s*<(?:command-name|command-message|command-args|local-command-stdout|local-command-caveat|bash-input|bash-stdout|bash-stderr)>/;
+// Besides the <command-name> scaffold form, Claude Code ALSO logs the raw slash-command input as a plain,
+// flagless user turn (content exactly "/compact", "/model sonnet", …) — redundant with the scaffold marker,
+// and after a /compact it's the LAST turn, so leaving it in would make the 对话 lens read a trailing user
+// bubble and light the "reply coming" typing wave forever. Drop it — anchored to a single leading /command
+// token followed by whitespace/EOL, so a path-like message ("/Users/demo/foo.js …") or prose is NOT eaten.
+const SLASH_CMD_RE = /^\s*\/[a-z][\w-]*(?:\s|$)/i;
+// The canonical scaffold form of a slash command: capture the name and any args, so the marker can tell a
+// bare `/model` (may open a picker) from `/model sonnet` (applies directly). The stdout echo is a separate
+// user turn right after; its inner text (closing tag stripped, ANSI stripped, capped) becomes the result.
+const CMD_NAME_RE = /^\s*<command-name>\s*\/?([\w-]+)\s*<\/command-name>/i;
+const CMD_ARGS_RE = /<command-args>([\s\S]*?)<\/command-args>/i;
+const STDOUT_RE = /^\s*<local-command-stdout>([\s\S]*)$/i;
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const SLASH_RESULT_CAP = 140;
+const stripAnsi = (value) => typeof value === 'string' ? value.replace(ANSI_RE, '') : '';
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : null);
+// A file-edit diff from a jsonl line's top-level `toolUseResult`, or null if the tool didn't edit a file.
+// Non-empty structuredPatch → count +/- lines and keep the hunks (for the expandable coloured view). Empty
+// patch but a create → every content line is an addition. Anything else (Bash/Read/…) → null.
+function extractDiff(value) {
+    const r = record(value);
+    if (!r)
+        return null;
+    const patch = Array.isArray(r.structuredPatch) ? r.structuredPatch : null;
+    if (patch && patch.length) {
+        let added = 0, removed = 0;
+        const hunks = [];
+        for (const rawHunk of patch) {
+            const h = record(rawHunk) || {};
+            const lines = Array.isArray(h.lines) ? h.lines.filter((line) => typeof line === 'string') : [];
+            for (const ln of lines) {
+                const c = typeof ln === 'string' ? ln[0] : '';
+                if (c === '+')
+                    added++;
+                else if (c === '-')
+                    removed++;
+            }
+            hunks.push({ oldStart: h.oldStart, newStart: h.newStart, lines });
+        }
+        return { added, removed, hunks };
+    }
+    if (r.type === 'create' && typeof r.content === 'string') {
+        return { added: r.content ? r.content.split('\n').length : 0, removed: 0, hunks: null, created: true };
+    }
+    return null;
+}
+function resultText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.map((item) => {
+            const c = record(item);
+            return c?.type === 'text' && typeof c.text === 'string' ? c.text : '';
+        }).join('');
+    return '';
+}
+const MAX_COMPACTION_SUMMARY_BYTES = 240 * 1024;
+function compactionSummary(content) {
+    const value = resultText(content);
+    if (!value)
+        return null;
+    const originalBytes = Buffer.byteLength(value);
+    if (originalBytes <= MAX_COMPACTION_SUMMARY_BYTES) {
+        return { text: value, truncated: false, originalBytes };
+    }
+    let text = Buffer.from(value).subarray(0, MAX_COMPACTION_SUMMARY_BYTES).toString('utf8');
+    while (Buffer.byteLength(text) > MAX_COMPACTION_SUMMARY_BYTES)
+        text = text.slice(0, -1);
+    return { text, truncated: true, originalBytes };
+}
+// Leading text of a message's content (string as-is, or the first text item of an array) — used only to
+// probe for a scaffolding tag at the very start. tool_result-only user turns yield '' and are never matched.
+function leadingText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const t = content.map(record).find((item) => item?.type === 'text');
+        return t && typeof t.text === 'string' ? t.text : '';
+    }
+    return '';
+}
+// Stateful form used by the transcript route's append-only file cache. `push()` may be called with
+// successive complete JSONL batches: tool results and slash-command stdout in a later batch can still
+// update the tool/slash message created by an earlier batch. The one-shot `parseTranscript()` wrapper
+// below preserves the public pure-function API used everywhere else.
+export function createTranscriptParser() {
+    const msgs = [];
+    const byToolId = new Map(); // tool_use_id → the tool message awaiting its result
+    let i = 0;
+    function push(lines) {
+        for (const raw of lines) {
+            const s = typeof raw === 'string' ? raw.trim() : '';
+            if (!s) {
+                i++;
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(s);
+            }
+            catch {
+                i++;
+                continue;
+            }
+            const o = record(parsed);
+            const m = record(o?.message);
+            if (!o || !KEEP.has(typeof o.type === 'string' ? o.type : '') || !m) {
+                i++;
+                continue;
+            }
+            if (o.isMeta === true) {
+                i++;
+                continue;
+            }
+            // A compaction wall (isCompactSummary): don't render the (huge) summary text as a bubble, but DO leave a
+            // quiet divider marker where it happened, so the 对话 lens shows "上下文已压缩" between the old and new
+            // context instead of the conversation silently jumping. (A no-op /compact writes no such entry → no
+            // divider, correctly.) Rendered centered like the interrupt marker.
+            if (o.isCompactSummary === true) {
+                const summary = compactionSummary(m.content);
+                msgs.push({
+                    i, type: 'compact', ts: typeof o.timestamp === 'string' ? o.timestamp : undefined,
+                    ...(summary ? { summary: summary.text } : {}),
+                    ...(summary?.truncated ? {
+                        summaryTruncated: true, summaryOriginalBytes: summary.originalBytes,
+                    } : {}),
+                });
+                i++;
+                continue;
+            }
+            // The jsonl line's wall-clock (ISO string) — carried onto each message so the 对话 lens can show a
+            // time separator between turns. Absent on some lines (older logs) → undefined; the UI shows nothing
+            // rather than a fabricated time ("有地方取就要，没有就不要").
+            const ts = typeof o.timestamp === 'string' ? o.timestamp : undefined;
+            const role = m.role === 'user' ? 'user' : 'assistant';
+            if (role === 'user') {
+                const lead = leadingText(m.content);
+                // A slash command → a quiet centered 'slash' marker (see the header note). Name + optional args.
+                const nameM = CMD_NAME_RE.exec(lead);
+                if (nameM) {
+                    const argsM = CMD_ARGS_RE.exec(lead);
+                    const args = argsM?.[1]?.trim() || '';
+                    const name = nameM[1];
+                    if (!name) {
+                        i++;
+                        continue;
+                    }
+                    const mk = { i, type: 'slash', name: `/${name}`, ts };
+                    if (args)
+                        mk.args = args;
+                    msgs.push(mk);
+                    i++;
+                    continue;
+                }
+                // Its stdout echo → fold onto the marker just pushed as `.result` (presence ⇒ the command completed).
+                const outM = STDOUT_RE.exec(lead);
+                if (outM) {
+                    const last = msgs[msgs.length - 1];
+                    if (last && last.type === 'slash' && last.result === undefined) {
+                        const txt = stripAnsi((outM[1] || '').replace(/<\/local-command-stdout>\s*$/i, '')).trim();
+                        if (txt)
+                            last.result = txt.length > SLASH_RESULT_CAP ? txt.slice(0, SLASH_RESULT_CAP) + '…' : txt;
+                    }
+                    i++;
+                    continue;
+                }
+                // Other scaffolding (<command-message>, caveat, bash-*) and the bare "/x" input line: still dropped.
+                if (SCAFFOLD_RE.test(lead) || SLASH_CMD_RE.test(lead)) {
+                    i++;
+                    continue;
+                }
+            }
+            // ESC-interrupt: Claude Code appends a standalone user line carrying a top-level `interruptedMessageId`
+            // (content is just "[Request interrupted by user…]"). It's NOT something the user typed — surface it as a
+            // quiet 'interrupt' marker (rendered as a small centered hint), never as a prominent user bubble. Detect
+            // by the structural field, falling back to the marker text for older logs.
+            if (typeof o.interruptedMessageId === 'string' || (role === 'user' && /^\[Request interrupted by user/.test(leadingText(m.content)))) {
+                msgs.push({ i, type: 'interrupt', ts });
+                i++;
+                continue;
+            }
+            const items = typeof m.content === 'string'
+                ? [{ type: 'text', text: m.content }]
+                : Array.isArray(m.content) ? m.content : [];
+            for (const rawItem of items) {
+                const it = record(rawItem);
+                if (!it)
+                    continue;
+                // .trim() here is a truthiness guard only (dropping whitespace-only text items to avoid empty
+                // bubbles) — the pushed `it.text` below is the untrimmed original, so real text's internal/
+                // leading/trailing whitespace is preserved verbatim.
+                if (it.type === 'text' && typeof it.text === 'string' && it.text.trim()) {
+                    msgs.push({ i, role, type: 'text', text: it.text, ts });
+                }
+                else if (it.type === 'thinking' && typeof it.thinking === 'string' && it.thinking) {
+                    msgs.push({ i, role: 'assistant', type: 'thinking', text: it.thinking, ts });
+                }
+                else if (it.type === 'tool_use') {
+                    const tm = {
+                        i,
+                        role: 'assistant',
+                        type: 'tool',
+                        ts,
+                        tool: {
+                            name: typeof it.name === 'string' ? it.name : '',
+                            input: it.input || {},
+                            result: null,
+                            isError: false,
+                        },
+                    };
+                    if (typeof it.id === 'string' && it.id)
+                        byToolId.set(it.id, tm);
+                    msgs.push(tm);
+                }
+                else if (it.type === 'tool_result') {
+                    const tm = typeof it.tool_use_id === 'string' ? byToolId.get(it.tool_use_id) : undefined;
+                    if (tm) {
+                        tm.tool.result = resultText(it.content);
+                        tm.tool.isError = !!it.is_error;
+                        // Claude Code stores a real per-hunk diff for file edits on the SAME line's top-level
+                        // `toolUseResult.structuredPatch` (hunks of {oldStart,newStart,lines[]}, each line prefixed
+                        // +/-/space) — the exact data the CLI renders. Fold it into the tool message so the 对话 chip
+                        // can show +A/−B and open the coloured diff, instead of the bland "…updated successfully" string.
+                        // A file CREATE has an empty patch but `type:'create'` + `content` → treat every line as added.
+                        tm.tool.diff = extractDiff(o.toolUseResult);
+                    }
+                }
+            }
+            i++;
+        }
+        return msgs;
+    }
+    return { push, messages: msgs };
+}
+export function parseTranscript(lines) {
+    return createTranscriptParser().push(lines);
+}

package/dist/src/transcriptReader.js

@@ -0,0 +1,209 @@
+import { createReadStream, promises as fsp } from 'node:fs';
+import { setImmediate as yieldImmediate } from 'node:timers/promises';
+import { createTranscriptParser } from './transcriptParse.js';
+// Append-aware JSONL reader for chat transcripts. A live Claude session is append-only, so after the
+// first asynchronous scan we read and parse only newly completed lines. Replacement/truncation resets
+// the parser; a small LRU bounds server memory across panes. Parsing yields periodically so the initial
+// scan of a long session cannot monopolize the Node event loop.
+export function createTranscriptReader({ maxEntries = 8, yieldEvery = 500 } = {}) {
+    const cache = new Map();
+    const inflight = new Map();
+    let generation = 0;
+    async function readCompleteLines(file, start, endExclusive) {
+        const lines = [];
+        let pending = Buffer.alloc(0);
+        let consumed = 0;
+        let bytesRead = 0;
+        if (endExclusive !== undefined && endExclusive <= start) {
+            return { lines, offset: start, size: start };
+        }
+        const options = endExclusive === undefined
+            ? { start }
+            : { start, end: endExclusive - 1 };
+        for await (const rawChunk of createReadStream(file, options)) {
+            const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+            bytesRead += chunk.length;
+            const data = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+            let pos = 0;
+            for (;;) {
+                const nl = data.indexOf(0x0a, pos);
+                if (nl === -1)
+                    break;
+                lines.push(data.subarray(pos, nl).toString('utf8'));
+                consumed += nl - pos + 1;
+                pos = nl + 1;
+            }
+            pending = data.subarray(pos);
+        }
+        return { lines, offset: start + consumed, size: start + bytesRead };
+    }
+    async function applyLines(parser, lines) {
+        for (let i = 0; i < lines.length; i += yieldEvery) {
+            parser.push(lines.slice(i, i + yieldEvery));
+            if (i + yieldEvery < lines.length)
+                await yieldImmediate();
+        }
+    }
+    function trim() {
+        if (cache.size <= maxEntries)
+            return;
+        const oldest = Array.from(cache.entries()).sort((a, b) => a[1].usedAt - b[1].usedAt);
+        for (const [file] of oldest) {
+            if (cache.size <= maxEntries)
+                break;
+            if (!inflight.has(file))
+                cache.delete(file);
+        }
+    }
+    async function load(file, createParser) {
+        let st;
+        try {
+            st = await fsp.stat(file);
+        }
+        catch {
+            cache.delete(file);
+            return [];
+        }
+        if (!st.isFile()) {
+            cache.delete(file);
+            return [];
+        }
+        let entry = cache.get(file);
+        const sameFile = Boolean(entry
+            && entry.createParser === createParser
+            && entry.dev === st.dev
+            && entry.ino === st.ino);
+        if (entry && sameFile && entry.size === st.size && entry.mtimeMs === st.mtimeMs) {
+            entry.usedAt = Date.now();
+            return entry.parser.messages;
+        }
+        // A larger file with the same inode is the normal append path. Anything else (truncate, atomic
+        // replace, or an in-place rewrite with unchanged size) gets a clean parser so stale messages cannot
+        // leak across /clear or log rotation.
+        const append = Boolean(sameFile && entry && st.size > entry.size);
+        if (!append || !entry) {
+            entry = {
+                parser: createParser(), createParser, offset: 0, dev: st.dev, ino: st.ino,
+                size: 0, mtimeMs: 0, usedAt: 0, generation: ++generation,
+            };
+        }
+        const { lines, offset, size } = await readCompleteLines(file, entry.offset);
+        await applyLines(entry.parser, lines);
+        // Re-stat after reading: the writer may have appended while the stream was open. Metadata reflects
+        // the latest observed file; any bytes not consumed as complete lines are deliberately retried later.
+        let end = st;
+        try {
+            end = await fsp.stat(file);
+        }
+        catch { /* return the last complete snapshot */ }
+        entry.offset = offset;
+        // Only adopt the post-read metadata if it describes exactly the bytes the stream consumed. If the
+        // file grew or was replaced in the race window, retaining the pre-read identity/observed size forces
+        // the next poll down the append/reset path instead of accidentally declaring unread bytes unchanged.
+        const caughtUp = end.dev === st.dev && end.ino === st.ino && end.size === size;
+        entry.dev = caughtUp ? end.dev : st.dev;
+        entry.ino = caughtUp ? end.ino : st.ino;
+        entry.size = size;
+        entry.mtimeMs = caughtUp ? end.mtimeMs : st.mtimeMs;
+        entry.usedAt = Date.now();
+        cache.set(file, entry);
+        trim();
+        return entry.parser.messages;
+    }
+    async function read(file, createParser = createTranscriptParser) {
+        const active = inflight.get(file);
+        if (active)
+            return active;
+        const run = load(file, createParser).finally(() => inflight.delete(file));
+        inflight.set(file, run);
+        return run;
+    }
+    async function readPrefix(file, endExclusive, createParser) {
+        if (!Number.isSafeInteger(endExclusive) || endExclusive < 0) {
+            throw new TypeError('Transcript prefix boundary must be a non-negative safe integer');
+        }
+        const parser = createParser();
+        if (endExclusive === 0)
+            return parser.messages;
+        const { lines } = await readCompleteLines(file, 0, endExclusive);
+        await applyLines(parser, lines);
+        return parser.messages;
+    }
+    async function readSnapshot(file, createParser) {
+        const messages = await read(file, createParser);
+        const entry = cache.get(file);
+        // `offset` advances only after complete JSONL records were parsed. Metadata distinguishes an in-place
+        // rewrite/replace that happens to end at the same byte boundary. Consumers can therefore skip all
+        // projection and hashing work when this token is unchanged.
+        const version = entry
+            ? `${entry.dev}:${entry.ino}:${entry.offset}:${entry.size}:${entry.mtimeMs}`
+            : 'missing';
+        return {
+            messages,
+            version,
+            changedFrom: entry
+                ? entry.parser.takeChangedFrom ? entry.parser.takeChangedFrom() : 0
+                : null,
+            ...(entry ? { generation: entry.generation } : {}),
+        };
+    }
+    async function readPrefixSnapshot(file, endExclusive, createParser) {
+        if (!Number.isSafeInteger(endExclusive) || endExclusive < 0) {
+            throw new TypeError('Transcript prefix boundary must be a non-negative safe integer');
+        }
+        // A normal read may already be advancing this parser. Wait for that mutation before deciding whether
+        // its append state can satisfy the immutable opening boundary.
+        await inflight.get(file)?.catch(() => { });
+        let st;
+        try {
+            st = await fsp.stat(file);
+        }
+        catch {
+            return { messages: [], version: 'missing', changedFrom: null };
+        }
+        if (!st.isFile() || endExclusive > st.size) {
+            return { messages: [], version: 'missing', changedFrom: null };
+        }
+        let entry = cache.get(file);
+        const reusable = Boolean(entry
+            && entry.createParser === createParser
+            && entry.dev === st.dev
+            && entry.ino === st.ino
+            && entry.offset <= endExclusive
+            && entry.size <= endExclusive);
+        if (!reusable || !entry) {
+            // A cached parser beyond the cutoff cannot be rewound. Build this rare historical prefix in
+            // isolation and leave the newer append cache intact.
+            const parser = createParser();
+            const { lines, offset, size } = await readCompleteLines(file, 0, endExclusive);
+            await applyLines(parser, lines);
+            return {
+                messages: parser.messages,
+                version: `${st.dev}:${st.ino}:${offset}:${size}:${st.mtimeMs}`,
+                changedFrom: parser.takeChangedFrom ? parser.takeChangedFrom() : 0,
+                generation: ++generation,
+            };
+        }
+        if (entry.size < endExclusive || entry.offset < endExclusive) {
+            const { lines, offset, size } = await readCompleteLines(file, entry.offset, endExclusive);
+            await applyLines(entry.parser, lines);
+            entry.offset = offset;
+            entry.size = size;
+            entry.mtimeMs = st.mtimeMs;
+            entry.usedAt = Date.now();
+            cache.set(file, entry);
+            trim();
+        }
+        return {
+            messages: entry.parser.messages,
+            version: `${entry.dev}:${entry.ino}:${entry.offset}:${entry.size}:${entry.mtimeMs}`,
+            changedFrom: entry.parser.takeChangedFrom ? entry.parser.takeChangedFrom() : 0,
+            generation: entry.generation,
+        };
+    }
+    return {
+        read, readPrefix, readSnapshot, readPrefixSnapshot,
+        clear: () => cache.clear(), size: () => cache.size,
+    };
+}
+export const transcriptReader = createTranscriptReader();

package/{src → dist/src}/trimCapture.js

@@ -12,17 +12,17 @@
 // ambiguous blank rows before this step, so genuinely shaded padding carries its explicit SGR while
 // a default-background blank may be trimmed normally.
 export const MAX_TRAILING_BLANK = 3;
-
 const isBlank = (row) => row === '' || (/^[ \t]*$/.test(row) && !row.includes('\x1b'));
-
 export function capTrailingBlankRows(ansi, max = MAX_TRAILING_BLANK) {
-  // capture-pane terminates every row with \n (including a trailing one). Peel that off so split
-  // gives exactly the rows, then restore it so the output keeps capture-pane's shape (prepareSeed
-  // drops a single trailing newline downstream).
-  const hadNL = ansi.endsWith('\n');
-  const rows = (hadNL ? ansi.slice(0, -1) : ansi).split('\n');
-  let end = rows.length;
-  while (end > 0 && isBlank(rows[end - 1])) end -= 1;
-  if (rows.length - end > max) rows.length = end + max;
-  return rows.join('\n') + (hadNL ? '\n' : '');
+    // capture-pane terminates every row with \n (including a trailing one). Peel that off so split
+    // gives exactly the rows, then restore it so the output keeps capture-pane's shape (prepareSeed
+    // drops a single trailing newline downstream).
+    const hadNL = ansi.endsWith('\n');
+    const rows = (hadNL ? ansi.slice(0, -1) : ansi).split('\n');
+    let end = rows.length;
+    while (end > 0 && isBlank(rows[end - 1] ?? ''))
+        end -= 1;
+    if (rows.length - end > max)
+        rows.length = end + max;
+    return rows.join('\n') + (hadNL ? '\n' : '');
 }

package/dist/src/uploadTypes.js

@@ -0,0 +1,31 @@
+// Extension allow-list for uploads. By extension only (not magic bytes) — this is a "be tidy"
+// guard, not a trust boundary (a token holder can write anything from the terminal anyway; see spec
+// threat model). Override the whole set with HANDMUX_UPLOAD_EXTS (comma-separated).
+export const DEFAULT_UPLOAD_EXTS = new Set([
+    // images
+    'jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp', 'heic', 'heif', 'avif', 'ico', 'tiff',
+    // video
+    'mp4', 'm4v', 'mov', 'webm', 'mkv', 'avi', 'wmv', 'flv', '3gp', 'ogv', 'mpeg', 'mpg',
+    // text / code
+    'txt', 'md', 'markdown', 'rst', 'log', 'csv', 'tsv', 'json', 'yaml', 'yml', 'toml', 'ini',
+    'conf', 'xml', 'html', 'htm', 'css', 'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'py', 'rb', 'go',
+    'rs', 'java', 'c', 'h', 'cpp', 'sh',
+    // documents / office
+    'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'odt', 'ods', 'odp', 'rtf',
+    // archives
+    'zip',
+]);
+// Read HANDMUX_UPLOAD_EXTS (comma-separated) → a Set, normalising leading dots/case/whitespace.
+// Blank/absent → the default set (returned by reference so callers can `=== DEFAULT_UPLOAD_EXTS`).
+export function loadUploadExts(env = process.env) {
+    const raw = env.HANDMUX_UPLOAD_EXTS;
+    if (!raw || !raw.trim())
+        return DEFAULT_UPLOAD_EXTS;
+    const exts = raw.split(',').map((s) => s.trim().replace(/^\.+/, '').toLowerCase()).filter(Boolean);
+    return new Set(exts);
+}
+// True if `name`'s final extension is in `exts`. No extension → false.
+export function isAllowedUploadExt(name, exts) {
+    const m = /\.([A-Za-z0-9]+)$/.exec(name || '');
+    return m?.[1] ? exts.has(m[1].toLowerCase()) : false;
+}

package/dist/src/urlPolicy.js

@@ -0,0 +1,18 @@
+// Notification links are user-supplied by `handmux push --url`. Keep relative in-app links, but reject
+// executable/non-web schemes (javascript:, data:, file:, …) before they reach storage or an <a href>.
+export function sanitizeNotificationUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const raw = value.trim();
+    if (!raw)
+        return null;
+    try {
+        const parsed = new URL(raw, 'https://handmux.invalid/');
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/usagePaths.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { pocketHome } from './cli/state.js';
+export function claudeUsagePath(home = homedir()) {
+    return path.join(pocketHome(home), 'claude-usage.json');
+}
+export function claudeContextDir(home = homedir()) {
+    return path.join(pocketHome(home), 'context');
+}
+export function codexUsagePath(home = homedir()) {
+    return path.join(pocketHome(home), 'codex-usage.json');
+}
+export function codexSessionsDir(home = homedir()) {
+    return path.join(home, '.codex', 'sessions');
+}