handmux 0.23.0 → 0.25.0

package/dist/src/codexUsageSnapshot.js

@@ -0,0 +1,228 @@
+// Persistent machine-wide Codex usage snapshot utilities. Kept as CommonJS so the ESM usage service can
+// load the same bounded rollout reader without adding a second package boundary.
+import fs from 'node:fs';
+import path from 'node:path';
+const CHUNK_BYTES = 64 * 1024;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const finiteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const nullableNumber = (value) => value === null || finiteNumber(value);
+const numberOrNull = (value) => finiteNumber(value) ? value : null;
+function ensurePrivateDirectory(directory) {
+    const resolved = path.resolve(directory);
+    const parsed = path.parse(resolved);
+    const parts = resolved.slice(parsed.root.length).split(path.sep).filter(Boolean);
+    const privateRoot = parts.indexOf('.handmux');
+    if (privateRoot < 0) {
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        return;
+    }
+    for (let i = privateRoot; i < parts.length; i++) {
+        const current = path.join(parsed.root, ...parts.slice(0, i + 1));
+        fs.mkdirSync(current, { recursive: true, mode: 0o700 });
+        fs.chmodSync(current, 0o700);
+    }
+}
+function windowUsage(value) {
+    if (!isRecord(value) || !finiteNumber(value.used_percent))
+        return null;
+    return {
+        usedPercent: value.used_percent,
+        windowMinutes: numberOrNull(value.window_minutes),
+        resetsAt: numberOrNull(value.resets_at),
+    };
+}
+function normalize(record) {
+    if (!isRecord(record) || !isRecord(record.payload))
+        return null;
+    const payload = record.payload;
+    if (payload.type !== 'token_count' || typeof record.timestamp !== 'string')
+        return null;
+    const updatedAt = Date.parse(record.timestamp);
+    if (!Number.isFinite(updatedAt))
+        return null;
+    const info = isRecord(payload.info) ? payload.info : {};
+    const totals = isRecord(info.total_token_usage) ? info.total_token_usage : {};
+    const rawLimits = isRecord(payload.rate_limits) ? payload.rate_limits : {};
+    // A rollout may carry a model-specific limit (for example GPT-5.3-Codex-Spark's
+    // `codex_bengalfox`) instead of the account's main Codex limit. Keep its token/context data, but never
+    // project that independent percentage as the generic Codex quota shown by HandMux.
+    const limitId = typeof rawLimits.limit_id === 'string' ? rawLimits.limit_id : null;
+    const limits = limitId === null || limitId === 'codex' ? rawLimits : {};
+    return {
+        updatedAt,
+        rateLimits: {
+            primary: windowUsage(limits.primary),
+            secondary: windowUsage(limits.secondary),
+        },
+        tokens: {
+            total: numberOrNull(totals.total_tokens),
+            input: numberOrNull(totals.input_tokens),
+            cachedInput: numberOrNull(totals.cached_input_tokens),
+            output: numberOrNull(totals.output_tokens),
+            reasoning: numberOrNull(totals.reasoning_output_tokens),
+        },
+        contextWindow: numberOrNull(info.model_context_window),
+    };
+}
+function contextUsage(record) {
+    if (!isRecord(record) || !isRecord(record.payload) || record.payload.type !== 'token_count')
+        return null;
+    const info = isRecord(record.payload.info) ? record.payload.info : null;
+    const last = isRecord(info?.last_token_usage) ? info.last_token_usage : null;
+    const usedTokens = last?.total_tokens;
+    const totalTokens = info?.model_context_window;
+    if (!finiteNumber(usedTokens) || usedTokens < 0
+        || !finiteNumber(totalTokens) || totalTokens <= 0)
+        return null;
+    return { usedTokens, totalTokens };
+}
+function parseLatest(lines, normalizeLine) {
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line || !line.includes('token_count'))
+            continue;
+        try {
+            const usage = normalizeLine(JSON.parse(line));
+            if (usage)
+                return usage;
+        }
+        catch { /* damaged/incomplete line: continue toward older complete records */ }
+    }
+    return null;
+}
+function readLatest(transcriptPath, normalizeLine) {
+    let fd;
+    try {
+        fd = fs.openSync(transcriptPath, 'r');
+        let end = fs.fstatSync(fd).size;
+        let suffix = '';
+        while (end > 0) {
+            const start = Math.max(0, end - CHUNK_BYTES);
+            const buffer = Buffer.allocUnsafe(end - start);
+            fs.readSync(fd, buffer, 0, buffer.length, start);
+            const lines = `${buffer.toString('utf8')}${suffix}`.split('\n');
+            if (start > 0)
+                suffix = lines.shift() || '';
+            const usage = parseLatest(lines, normalizeLine);
+            if (usage)
+                return usage;
+            end = start;
+        }
+        return suffix ? parseLatest([suffix], normalizeLine) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+export function readLatestUsage(transcriptPath) {
+    return readLatest(transcriptPath, normalize);
+}
+export function readLatestContextUsage(transcriptPath) {
+    return readLatest(transcriptPath, contextUsage);
+}
+function isUsageWindow(value) {
+    return isRecord(value)
+        && finiteNumber(value.usedPercent)
+        && nullableNumber(value.windowMinutes)
+        && nullableNumber(value.resetsAt);
+}
+function isCodexUsage(value) {
+    if (!isRecord(value)
+        || !finiteNumber(value.updatedAt)
+        || !isRecord(value.rateLimits)
+        || !isRecord(value.tokens)
+        || !nullableNumber(value.contextWindow))
+        return false;
+    const { primary, secondary } = value.rateLimits;
+    if (primary !== null && !isUsageWindow(primary))
+        return false;
+    if (secondary !== null && !isUsageWindow(secondary))
+        return false;
+    return nullableNumber(value.tokens.total)
+        && nullableNumber(value.tokens.input)
+        && nullableNumber(value.tokens.cachedInput)
+        && nullableNumber(value.tokens.output)
+        && nullableNumber(value.tokens.reasoning);
+}
+export function readSnapshot(snapshotPath) {
+    try {
+        ensurePrivateDirectory(path.dirname(snapshotPath));
+        fs.chmodSync(snapshotPath, 0o600);
+        const value = JSON.parse(fs.readFileSync(snapshotPath, 'utf8'));
+        if (!isRecord(value) || value.version !== 1 || !finiteNumber(value.checkedAt))
+            return null;
+        if (value.usage !== null && !isCodexUsage(value.usage))
+            return null;
+        return { version: 1, checkedAt: value.checkedAt, usage: value.usage };
+    }
+    catch {
+        return null;
+    }
+}
+function nap(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    catch {
+        const until = Date.now() + ms;
+        while (Date.now() < until) { /* spin */ }
+    }
+}
+export function writeSnapshot(snapshotPath, usage, { checkedAt } = {}) {
+    try {
+        ensurePrivateDirectory(path.dirname(snapshotPath));
+    }
+    catch {
+        return null;
+    }
+    const lock = `${snapshotPath}.lock`;
+    let held = false;
+    for (let i = 0; i < 40 && !held; i++) {
+        try {
+            fs.closeSync(fs.openSync(lock, 'wx', 0o600));
+            held = true;
+        }
+        catch {
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > 3000)
+                    fs.unlinkSync(lock);
+            }
+            catch { /* retry */ }
+            nap(5);
+        }
+    }
+    if (!held)
+        return readSnapshot(snapshotPath)?.usage || null;
+    try {
+        const previous = readSnapshot(snapshotPath);
+        const priorUsage = previous?.usage || null;
+        const nextUsage = usage && (!priorUsage || usage.updatedAt >= priorUsage.updatedAt) ? usage : priorUsage;
+        const value = {
+            version: 1,
+            checkedAt: typeof checkedAt === 'number' ? checkedAt : (previous?.checkedAt || 0),
+            usage: nextUsage,
+        };
+        const tmp = `${snapshotPath}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 });
+        fs.renameSync(tmp, snapshotPath);
+        fs.chmodSync(snapshotPath, 0o600);
+        return nextUsage;
+    }
+    catch {
+        return readSnapshot(snapshotPath)?.usage || null;
+    }
+    finally {
+        try {
+            fs.unlinkSync(lock);
+        }
+        catch { /* best effort */ }
+    }
+}

package/dist/src/config.js

@@ -0,0 +1,8 @@
+import { normalizeShortcuts } from './shortcutConfig.js';
+export function loadConfig(env = process.env) {
+    return {
+        host: env.HANDMUX_HOST || '0.0.0.0',
+        port: Number(env.HANDMUX_PORT) || 4000,
+        shortcuts: normalizeShortcuts(env.HANDMUX_SHORTCUTS === undefined ? undefined : JSON.parse(env.HANDMUX_SHORTCUTS)),
+    };
+}

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

@@ -1,48 +1,46 @@
-// Renderable doc types by extension. Exported so the web mirror (docPath.js DOC_LINK_EXTS) can be
-// parity-checked against it — the client's tappable-path detector must open exactly what we can render.
 export const EXT = {
-  '.md': 'markdown', '.markdown': 'markdown', '.html': 'html', '.htm': 'html',
-  // Plain-text files: rendered verbatim in a <pre> (no markdown parsing).
-  '.txt': 'text', '.log': 'text', '.sh': 'text',
+    '.md': 'markdown', '.markdown': 'markdown', '.html': 'html', '.htm': 'html',
+    // Plain-text files: rendered verbatim in a <pre> (no markdown parsing).
+    '.txt': 'text', '.log': 'text', '.sh': 'text',
 };
-
 // Map a filename to our renderable doc type by extension, or null. Case-insensitive.
 export function docTypeFor(name) {
-  const m = /\.[A-Za-z0-9]+$/.exec(name || '');
-  return m ? (EXT[m[0].toLowerCase()] ?? null) : null;
+    const m = /\.[A-Za-z0-9]+$/.exec(name || '');
+    return m ? (EXT[m[0].toLowerCase()] ?? null) : null;
 }
-
 // Image extensions the in-app viewer can show inline via <img> (GIF animates natively). SVG is safe
 // here because <img>-loaded SVG never runs its scripts. Returns 'image' or null. Case-insensitive.
 export const IMG_EXT = new Set(['png', 'jpg', 'jpeg', 'jfif', 'gif', 'webp', 'svg', 'bmp', 'ico', 'avif', 'apng']);
 export function imageTypeFor(name) {
-  const m = /\.([A-Za-z0-9]+)$/.exec(name || '');
-  return m && IMG_EXT.has(m[1].toLowerCase()) ? 'image' : null;
+    const m = /\.([A-Za-z0-9]+)$/.exec(name || '');
+    return m?.[1] && IMG_EXT.has(m[1].toLowerCase()) ? 'image' : null;
 }
-
 // True if `child` equals `parent` or sits inside it. Both are expected to be realpaths.
 // Guards the sibling-prefix trap: /home/ab is NOT under /home/a.
 export function isUnder(child, parent) {
-  if (child === parent) return true;
-  const p = parent.endsWith('/') ? parent : parent + '/';
-  return child.startsWith(p);
+    if (child === parent)
+        return true;
+    const p = parent.endsWith('/') ? parent : parent + '/';
+    return child.startsWith(p);
 }
-
 // Sanitize a client-supplied upload filename to a single safe path segment, or null if unsafe.
 // Takes the basename (drops any dir part, handling both / and \), then rejects empty / '.' / '..'
 // and dotfiles (no hidden files). The result never contains a path separator.
 export function safeUploadName(raw) {
-  if (typeof raw !== 'string') return null;
-  const base = raw.split('/').pop().split('\\').pop();
-  if (!base || base === '.' || base === '..' || base[0] === '.') return null;
-  return base;
+    if (typeof raw !== 'string')
+        return null;
+    const slashBase = raw.split('/').pop() ?? '';
+    const base = slashBase.split('\\').pop();
+    if (!base || base === '.' || base === '..' || base[0] === '.')
+        return null;
+    return base;
 }
-
 // True if `real` (a realpath at/under `home`) has any path segment BELOW home that starts with '.'
 // — i.e. it lives inside a hidden directory like ~/.ssh or ~/.config. `home` is the realpath of
 // $HOME. The home root itself is not hidden.
 export function hasHiddenSegment(real, home) {
-  if (real === home) return false;
-  const rel = real.startsWith(home.endsWith('/') ? home : home + '/') ? real.slice(home.length) : real;
-  return rel.split('/').filter(Boolean).some((seg) => seg.startsWith('.'));
+    if (real === home)
+        return false;
+    const rel = real.startsWith(home.endsWith('/') ? home : home + '/') ? real.slice(home.length) : real;
+    return rel.split('/').filter(Boolean).some((seg) => seg.startsWith('.'));
 }

package/dist/src/docs.js

@@ -0,0 +1,337 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { docTypeFor, imageTypeFor, isUnder, hasHiddenSegment } from './docPath.js';
+const MAX_READ_BYTES = 2 * 1024 * 1024; // 2MB cap for in-app text reads (readDoc)
+// Single source of truth for the 50MB transfer cap, shared by download (maxDownloadBytes default
+// below) and upload (httpApi.js imports this as the maxUploadBytes default). Server-side only.
+export const MAX_TRANSFER_BYTES = 50 * 1024 * 1024;
+// Decode only actual text. `Buffer.toString('utf8')` silently replaces malformed bytes, which would
+// make arbitrary binaries look previewable; fatal decoders keep that boundary honest. UTF-16 needs a
+// BOM because zero bytes are otherwise our strongest cheap binary signal.
+function decodeText(buffer) {
+    let encoding = 'utf-8';
+    let offset = 0;
+    if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+        encoding = 'utf-16le';
+        offset = 2;
+    }
+    else if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+        encoding = 'utf-16be';
+        offset = 2;
+    }
+    else if (buffer.includes(0)) {
+        return null;
+    }
+    try {
+        return new TextDecoder(encoding, { fatal: true }).decode(buffer.subarray(offset));
+    }
+    catch {
+        return null;
+    }
+}
+// Flatten an absolute cwd into ONE filesystem-safe path segment for the per-project upload space,
+// Claude-Code style: '/' → '-' (so /Users/x/proj → -Users-x-proj), and any other non-portable char
+// → '_'. A valid cwd always starts with '/', so the key always starts with '-' — it can never be
+// '..'/'.' and, having no separators, can never escape the uploads root. Empty/relative → '_default'.
+export function encodeCwdKey(cwd) {
+    if (typeof cwd !== 'string' || cwd[0] !== '/')
+        return '_default';
+    return cwd.replace(/\//g, '-').replace(/[^A-Za-z0-9._-]/g, '_') || '_default';
+}
+export function createDocs({ home, extraRoots = [], maxDownloadBytes = MAX_TRANSFER_BYTES }) {
+    // $HOME is constant at runtime — resolve once at construction, reuse the same promise everywhere.
+    const realHomeP = fs.realpath(home);
+    // Browse / read / download / upload may also reach a few EXTRA roots OUTSIDE $HOME (e.g. /tmp,
+    // $TMPDIR) so transient files an agent drops there are reachable from the phone. Resolved once:
+    // realpath'd, deduped, missing ones skipped, and any extra already inside home dropped (home
+    // covers it). `home` is always roots[0]. Session-cwd (resolveCwd) and the upload stash stay
+    // home-only on purpose. The "under one of these roots" check replaces the old single isUnder(home).
+    const rootsP = (async () => {
+        const rh = await realHomeP;
+        const out = [rh];
+        for (const r of extraRoots) {
+            if (typeof r !== 'string' || !r)
+                continue;
+            let real;
+            try {
+                real = await fs.realpath(r);
+            }
+            catch {
+                continue;
+            } // not present on this host → skip
+            if (isUnder(real, rh) || out.includes(real))
+                continue; // already covered by home / dup
+            out.push(real);
+        }
+        return out;
+    })();
+    // The allowed root that contains `real` (longest match wins should roots ever nest), or null.
+    const rootOf = (real, roots) => {
+        let best = null;
+        for (const r of roots)
+            if (isUnder(real, r) && (!best || r.length > best.length))
+                best = r;
+        return best;
+    };
+    // `knownMtime` (ms) makes this a conditional read: if the file's mtime is unchanged the body is
+    // skipped and `{ notModified: true }` comes back (no readFile), so re-visiting an unchanged doc on
+    // the phone neither transfers content nor forces a re-render. `mtimeMs` is always returned so the
+    // client can store it for the next check.
+    async function readDoc(rawPath, knownMtime = null) {
+        if (typeof rawPath !== 'string' || rawPath[0] !== '/')
+            return { error: 'not absolute', status: 400 };
+        // Markdown/HTML keep their rich renderer; every other filename gets a content-checked plain-text
+        // preview. Extension is presentation metadata, never the permission to read a file as text.
+        const type = docTypeFor(rawPath) || 'text';
+        let real;
+        try {
+            real = await fs.realpath(rawPath);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        if (!rootOf(real, await rootsP))
+            return { error: 'outside home', status: 400 };
+        let st;
+        try {
+            st = await fs.stat(real);
+        }
+        catch {
+            return { error: 'not accessible', status: 404 };
+        }
+        if (!st.isFile())
+            return { error: 'not a file', status: 400 };
+        if (st.size > MAX_READ_BYTES)
+            return { error: 'too large', status: 413 };
+        const mtimeMs = st.mtimeMs;
+        if (knownMtime != null && mtimeMs === knownMtime)
+            return { name: basename(real), type, mtimeMs, notModified: true };
+        const content = decodeText(await fs.readFile(real));
+        if (content == null)
+            return { error: 'not text', status: 415 };
+        return { name: basename(real), type, content, mtimeMs };
+    }
+    async function listDir(rawPath) {
+        const rh = await realHomeP;
+        const roots = await rootsP;
+        let real;
+        try {
+            real = await fs.realpath(rawPath ? rawPath : home);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        if (!rootOf(real, roots))
+            return { error: 'outside home', status: 400 };
+        const st = await fs.stat(real);
+        if (!st.isDirectory())
+            return { error: 'not a directory', status: 400 };
+        const dirents = await fs.readdir(real, { withFileTypes: true });
+        // withFileTypes uses lstat semantics: d.isFile() is false for symlinks, so symlinks are
+        // intentionally NOT listed (security property). Every regular file is listed now (not just
+        // docs); the extension decides whether it opens in-app as a doc ('doc'), an image viewer
+        // ('image'), or can only be downloaded ('file').
+        const dirEntries = [];
+        const fileDirents = [];
+        for (const d of dirents) {
+            if (d.isDirectory())
+                dirEntries.push({ name: d.name, type: 'dir' });
+            else if (d.isFile())
+                fileDirents.push(d);
+        }
+        // stat every file IN PARALLEL — a big dir is thousands of files, and one awaited stat each
+        // (serial) is what made listing hang for seconds. Promise.all lets the OS pipeline them.
+        const fileEntries = await Promise.all(fileDirents.map(async (d) => {
+            const type = docTypeFor(d.name) ? 'doc' : imageTypeFor(d.name) ? 'image' : 'file';
+            let size = 0;
+            try {
+                size = (await fs.stat(join(real, d.name))).size;
+            }
+            catch { /* gone mid-list → size 0 */ }
+            return { name: d.name, type, size };
+        }));
+        const entries = [...dirEntries, ...fileEntries];
+        // dirs first; files (doc+file) interleaved alphabetically
+        entries.sort((a, b) => (a.type === 'dir' ? 0 : 1) - (b.type === 'dir' ? 0 : 1) || a.name.localeCompare(b.name));
+        // "up" stops at whichever allowed root we're in (each root is a ceiling), not only at home.
+        const parent = roots.includes(real) ? null : join(real, '..');
+        return { path: real, home: rh, roots, parent, entries };
+    }
+    // Resolve a path for DOWNLOAD: any regular file under home, no extension white-list (unlike
+    // readDoc). Same realpath+isUnder boundary; symlinks escaping home resolve outside → rejected.
+    async function statForDownload(rawPath) {
+        if (typeof rawPath !== 'string' || rawPath[0] !== '/')
+            return { error: 'not absolute', status: 400 };
+        let real;
+        try {
+            real = await fs.realpath(rawPath);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        if (!rootOf(real, await rootsP))
+            return { error: 'outside home', status: 400 };
+        let st;
+        try {
+            st = await fs.stat(real);
+        }
+        catch {
+            return { error: 'not accessible', status: 404 };
+        }
+        if (!st.isFile())
+            return { error: 'not a file', status: 400 };
+        if (st.size > maxDownloadBytes)
+            return { error: 'too large', status: 413 };
+        return { real, name: basename(real), size: st.size, mtimeMs: st.mtimeMs };
+    }
+    // Resolve a path for UPLOAD TARGET: a directory under one of the allowed roots, not inside any
+    // hidden directory (relative to its own root). The $HOME root itself is off-limits (don't litter
+    // the home dir); an extra root like /tmp IS uploadable directly, since dropping files there is the
+    // whole point. Same realpath boundary as the rest.
+    async function resolveUploadDir(rawDir) {
+        if (typeof rawDir !== 'string' || rawDir[0] !== '/')
+            return { error: 'not absolute', status: 400 };
+        const rh = await realHomeP;
+        let real;
+        try {
+            real = await fs.realpath(rawDir);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        const root = rootOf(real, await rootsP);
+        if (!root)
+            return { error: 'outside home', status: 400 };
+        if (real === rh)
+            return { error: 'home root not allowed', status: 400 };
+        if (hasHiddenSegment(real, root))
+            return { error: 'hidden directory not allowed', status: 400 };
+        let st;
+        try {
+            st = await fs.stat(real);
+        }
+        catch {
+            return { error: 'not accessible', status: 404 };
+        }
+        if (!st.isDirectory())
+            return { error: 'not a directory', status: 400 };
+        return { real };
+    }
+    // Resolve the STASH upload target: a per-project folder under ~/.handmux/uploads, created on
+    // demand. Deliberately OUTSIDE the user's project trees (so uploads can never be `git add`-ed by
+    // accident) yet still under $HOME, so the absolute path the chat box pastes stays readable by an
+    // agent running anywhere. Mirrors Claude Code's per-project layout: the caller's cwd is flattened
+    // ('/'→'-') into a single path segment (see encodeCwdKey), so each working directory gets its own
+    // space; an unknown cwd falls into `_default`. Returns the realpath'd dir.
+    async function resolveStashDir(rawCwd) {
+        const rh = await realHomeP;
+        const target = join(rh, '.handmux', 'uploads', encodeCwdKey(rawCwd));
+        try {
+            await fs.mkdir(target, { recursive: true });
+        }
+        catch {
+            return { error: 'mkdir failed', status: 500 };
+        }
+        let real;
+        try {
+            real = await fs.realpath(target);
+        } // re-resolve in case a segment is a symlink
+        catch {
+            return { error: 'not accessible', status: 404 };
+        }
+        if (!isUnder(real, rh))
+            return { error: 'outside home', status: 400 };
+        return { real };
+    }
+    // Resolve a path for use as a NEW session/window CWD: any directory under home (home root IS
+    // allowed, and hidden dirs ARE allowed — the browser can navigate into them). Same realpath +
+    // isUnder boundary as the rest; symlinks escaping home resolve outside → rejected.
+    async function resolveCwd(rawDir) {
+        if (typeof rawDir !== 'string' || rawDir[0] !== '/')
+            return { error: 'not absolute', status: 400 };
+        const rh = await realHomeP;
+        let real;
+        try {
+            real = await fs.realpath(rawDir);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        if (!isUnder(real, rh))
+            return { error: 'outside home', status: 400 };
+        let st;
+        try {
+            st = await fs.stat(real);
+        }
+        catch {
+            return { error: 'not accessible', status: 404 };
+        }
+        if (!st.isDirectory())
+            return { error: 'not a directory', status: 400 };
+        return { real };
+    }
+    // Resolve a directory for BROWSE-side ops (the mkdir target): a directory under ANY allowed root
+    // (the root itself + hidden dirs allowed, like resolveCwd but multi-root). resolveCwd stays
+    // home-only — a new session's cwd should never land in a temp root by accident.
+    async function resolveBrowseDir(rawDir) {
+        if (typeof rawDir !== 'string' || rawDir[0] !== '/')
+            return { error: 'not absolute', status: 400 };
+        let real;
+        try {
+            real = await fs.realpath(rawDir);
+        }
+        catch {
+            return { error: 'not found', status: 404 };
+        }
+        if (!rootOf(real, await rootsP))
+            return { error: 'outside home', status: 400 };
+        let st;
+        try {
+            st = await fs.stat(real);
+        }
+        catch {
+            return { error: 'not accessible', status: 404 };
+        }
+        if (!st.isDirectory())
+            return { error: 'not a directory', status: 400 };
+        return { real };
+    }
+    // Create a new directory `name` inside `parentRaw`. The parent must be a directory under one of
+    // the allowed roots (root + hidden dirs allowed). `name` must be a single safe path segment.
+    async function makeDir(parentRaw, name) {
+        const nm = typeof name === 'string' ? name.trim() : '';
+        if (!nm || nm === '.' || nm === '..' || nm.includes('/') || nm.includes('\\') || nm.includes('\0')) {
+            return { error: 'bad name', status: 400 };
+        }
+        const parent = await resolveBrowseDir(parentRaw); // realpath + under-a-root + isDirectory
+        if ('error' in parent)
+            return parent;
+        const target = join(parent.real, nm);
+        try {
+            await fs.mkdir(target);
+        }
+        catch (e) {
+            if (errorCode(e) === 'EEXIST')
+                return { error: 'exists', status: 409 };
+            return { error: 'mkdir failed', status: 500 };
+        }
+        return { real: target };
+    }
+    return { readDoc, listDir, statForDownload, resolveUploadDir, resolveStashDir, resolveCwd, makeDir };
+}
+// The extra (outside-$HOME) roots the file browser may reach: the system temp dir and, if set, the
+// per-user $TMPDIR (on macOS that's /var/folders/.../T). Missing ones are skipped at resolve time.
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+export function defaultExtraRoots(env = process.env) {
+    const roots = ['/tmp'];
+    if (env.TMPDIR)
+        roots.push(env.TMPDIR);
+    return roots;
+}
+export const defaultDocs = createDocs({ home: homedir(), extraRoots: defaultExtraRoots() });