@turns/dev 0.0.9 → 0.0.11

package/README.md

@@ -73,10 +73,17 @@ bounds a deliberately broad matcher: prose that merely looks like a path
 resolves to nothing and is never mentioned to the server, and no directory is
 ever scanned.
 
-An explicit file browse may upload up to 199 MB to the same private R2 prefix.
+An explicit file browse may upload up to 2 GiB to the same private R2 prefix.
+Files over 100 MiB use retryable 32 MiB multipart requests and report upload
+progress to the requesting browser over the control WebSocket.
 The daemon streams the file from disk and the Worker hands that request stream
 straight to R2, so neither process retains the complete file in memory.
 
+Range-based viewers can bypass that upload. A capable daemon advertises live
+file ranges, validates the path through the same allowlist, and streams a
+bounded window as ordered 32 KiB WebSocket chunks. The browser hex view pages
+64 KiB viewport windows, including arbitrary offset jumps.
+
 The systemd unit uses `KillMode=process`, and the macOS LaunchAgent uses
 `AbandonProcessGroup`: restarting the uploader leaves its detached agent-anchor
 processes running so in-flight harness turns continue.

package/dist/file-browsing.js

@@ -17,10 +17,19 @@ import { uploadFileStream } from "./path-resolution.js";
  */
 /** Kept in step with `MAX_DIRECTORY_ENTRIES` in the Worker's shared listing. */
 export const MAX_DIRECTORY_ENTRIES = 2_000;
-/** One MB below the Worker request-body ceiling, matching the R2 endpoint. */
-export const MAX_BROWSE_FILE_BYTES = 199 * 1024 * 1024;
+/** Kept in step with `MAX_FILE_BYTES` on the server. Multipart transport keeps
+ * each individual Worker request below the platform request-body ceiling. */
+export const MAX_BROWSE_FILE_BYTES = 2 * 1024 * 1024 * 1024;
 /** The derived label used in reader-facing errors. */
-export const BROWSE_FILE_LIMIT_LABEL = `${Math.round(MAX_BROWSE_FILE_BYTES / (1024 * 1024))} MB`;
+export const BROWSE_FILE_LIMIT_LABEL = `${MAX_BROWSE_FILE_BYTES / (1024 * 1024 * 1024)} GB`;
+/** Frequent filesystem chunks are useful for accurate accounting but noisy on
+ * a control socket. Four frames per second plus phase boundaries stays smooth. */
+export const BROWSE_PROGRESS_INTERVAL_MS = 250;
+/** One browser range request is deliberately small enough to remain cheap to
+ * retry or abandon when a reader scrolls quickly through a large file. */
+export const MAX_BROWSE_RANGE_BYTES = 256 * 1024;
+/** Raw bytes per WebSocket payload. Base64 expands this to roughly 43 KiB. */
+export const BROWSE_RANGE_CHUNK_BYTES = 32 * 1024;
 /** Enough data to distinguish source and prose from arbitrary binary bytes
  * without reading a large artifact into the daemon's memory. */
 export const FILE_TYPE_SAMPLE_BYTES = 64 * 1024;
@@ -173,7 +182,50 @@ export function readDirectory(directory) {
     // clock inside the body would make every read produce different bytes.
     return { path: directory, entries, truncated: names.length > MAX_DIRECTORY_ENTRIES };
 }
-export async function browseMachinePath({ requested, machine, baseUrl, options, workingDirectory = '', contentEtag = '', fetchImpl = fetch, }) {
+/** Stream one bounded file window without creating or updating its R2 object. */
+export async function streamMachineFileRange({ requested, offset, length, workingDirectory = '', allowedDirectories = [], onReady, onChunk, }) {
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw new Error('Invalid file range offset.');
+    if (!Number.isSafeInteger(length) || length <= 0 || length > MAX_BROWSE_RANGE_BYTES) {
+        throw new Error('Invalid file range length.');
+    }
+    const resolved = resolveBrowsePath(requested, { workingDirectory, allowedDirectories });
+    if (!resolved.stat.isFile())
+        throw new Error(`Not a readable file: ${resolved.path}`);
+    if (resolved.stat.size > MAX_BROWSE_FILE_BYTES) {
+        throw new Error(`File is larger than the ${BROWSE_FILE_LIMIT_LABEL} browse limit.`);
+    }
+    if (offset > resolved.stat.size)
+        throw new Error('File range starts beyond the end of the file.');
+    const boundedLength = Math.min(length, resolved.stat.size - offset);
+    const sample = readFileTypeSample(resolved.path, resolved.stat.size);
+    const range = {
+        path: resolved.path,
+        offset,
+        length: boundedLength,
+        totalBytes: resolved.stat.size,
+        contentType: browseContentType(resolved.path, sample, sample.byteLength === resolved.stat.size),
+        modifiedAt: isoTime(resolved.stat.mtimeMs),
+    };
+    onReady(range);
+    if (!boundedLength)
+        return range;
+    const stream = fs.createReadStream(resolved.path, {
+        start: offset,
+        end: offset + boundedLength - 1,
+        highWaterMark: BROWSE_RANGE_CHUNK_BYTES,
+    });
+    let chunkOffset = offset;
+    for await (const value of stream) {
+        const chunk = value;
+        onChunk(chunkOffset, chunk);
+        chunkOffset += chunk.byteLength;
+    }
+    if (chunkOffset !== offset + boundedLength)
+        throw new Error('The file changed while its byte range was being read.');
+    return range;
+}
+export async function browseMachinePath({ requested, machine, baseUrl, options, workingDirectory = '', contentEtag = '', onUploadProgress, fetchImpl = fetch, }) {
     const resolved = resolveBrowsePath(requested, {
         workingDirectory,
         allowedDirectories: options.allowedDirectories || [],
@@ -201,6 +253,20 @@ export async function browseMachinePath({ requested, machine, baseUrl, options,
     const modifiedAt = isoTime(resolved.stat.mtimeMs);
     if (resolved.stat.size === 0)
         return { path: resolved.path, kind: 'file', bytes: 0, contentType, modifiedAt };
+    let lastProgressAt = 0;
+    let lastUploadedBytes = -1;
+    const reportProgress = (phase, uploadedBytes, force = false) => {
+        if (!onUploadProgress)
+            return;
+        const bounded = Math.max(lastUploadedBytes, Math.min(resolved.stat.size, Math.max(0, uploadedBytes)));
+        const now = Date.now();
+        if (!force && now - lastProgressAt < BROWSE_PROGRESS_INTERVAL_MS && bounded < resolved.stat.size)
+            return;
+        lastProgressAt = now;
+        lastUploadedBytes = bounded;
+        onUploadProgress({ path: resolved.path, phase, uploadedBytes: bounded, totalBytes: resolved.stat.size });
+    };
+    reportProgress('starting', 0, true);
     await uploadFileStream({
         baseUrl,
         options,
@@ -210,6 +276,8 @@ export async function browseMachinePath({ requested, machine, baseUrl, options,
         bytes: resolved.stat.size,
         modifiedAt,
         ...(contentEtag ? { contentEtag } : {}),
+        onProgress: (uploadedBytes) => reportProgress('uploading', uploadedBytes),
+        onFinalizing: () => reportProgress('finalizing', resolved.stat.size, true),
         fetchImpl,
     });
     return { path: resolved.path, kind: 'file', bytes: resolved.stat.size, contentType, modifiedAt };

package/dist/git-status.js

@@ -0,0 +1,440 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveBrowsePath } from "./file-browsing.js";
+/**
+ * Asking this machine's git what the tree a reader is browsing looks like.
+ *
+ * The browser cannot run git, and the daemon will not hand it a shell, so the
+ * questions worth asking are enumerated here and answered with fixed argument
+ * vectors: a repository path never becomes an option, a pattern, or a shell
+ * fragment. Every invocation is bounded in time and in output, because a work
+ * tree can be arbitrarily large and a browse must not be able to pin a daemon.
+ *
+ * The base revision is picked the way a reviewer would. On the default branch
+ * there is nothing to have diverged from, so the base is `HEAD` and the answer
+ * describes uncommitted work. Anywhere else — a feature branch, or one of the
+ * linked worktrees agents are usually given — the base is the merge point with
+ * the default branch, making the answer the same range a pull request shows.
+ */
+/** A git call has to finish inside a browse, not eventually. */
+export const GIT_COMMAND_TIMEOUT_MS = 10_000;
+/**
+ * Ceilings this daemon answers within, kept in step with the Worker's shared
+ * git module rather than imported from it.
+ *
+ * This package is published on its own and builds with the CLI directory as
+ * its root, so a source file here cannot reach into the Worker's tree: an
+ * import across that boundary compiles under the repo-wide typecheck and then
+ * fails the package build, which is the build that produces what npm ships.
+ * The Worker's `MAX_GIT_STATUS_FILES`, `MAX_GIT_TEXT_BYTES`, and
+ * `MAX_GIT_UNTRACKED_COUNT_BYTES` are the same three numbers; the reader
+ * validates against its own copies, so a daemon that drifted upward would be
+ * trimmed rather than believed.
+ */
+const MAX_GIT_STATUS_FILES = 2_000;
+const MAX_GIT_TEXT_BYTES = 4 * 1024 * 1024;
+const MAX_GIT_UNTRACKED_COUNT_BYTES = 2 * 1024 * 1024;
+/** Local branches are tried before remote-tracking ones: an agent working in a
+ * linked worktree diverged from the checkout beside it, not from the server. */
+const DEFAULT_BRANCH_REFS = [
+    { ref: 'refs/heads/main', label: 'main' },
+    { ref: 'refs/heads/master', label: 'master' },
+    { ref: 'refs/remotes/origin/main', label: 'origin/main' },
+    { ref: 'refs/remotes/origin/master', label: 'origin/master' },
+];
+/**
+ * Run one git command and collect a bounded amount of its output.
+ *
+ * `stderr` is discarded rather than reported: git's diagnostics name paths and
+ * refs on someone else's machine, and every failure here has a useful meaning
+ * of its own — a directory that is not a repository, a file that did not exist
+ * at the base. A non-zero exit is returned rather than thrown so callers can
+ * treat "no such ref" as an answer.
+ */
+function runGit(args, { cwd, limit = MAX_GIT_TEXT_BYTES, timeoutMs = GIT_COMMAND_TIMEOUT_MS, }) {
+    return new Promise((resolve, reject) => {
+        // `--no-pager` and an empty config environment keep a reader's answer from
+        // depending on whatever aliases, pagers, or colour settings this machine has.
+        const child = spawn('git', ['--no-pager', ...args], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            env: { ...process.env, GIT_PAGER: 'cat', GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' },
+        });
+        const chunks = [];
+        let size = 0;
+        let truncated = false;
+        let stopped = false;
+        let killTimer;
+        const stop = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), 100);
+            killTimer.unref?.();
+        };
+        child.stdout.on('data', (chunk) => {
+            if (size >= limit)
+                return;
+            const room = limit - size;
+            chunks.push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+            size += Math.min(room, chunk.length);
+            if (size < limit)
+                return;
+            truncated = true;
+            stop();
+        });
+        child.on('error', (error) => {
+            clearTimeout(timeout);
+            clearTimeout(killTimer);
+            reject(error);
+        });
+        const timeout = setTimeout(() => {
+            truncated = true;
+            stop();
+        }, timeoutMs);
+        timeout.unref?.();
+        child.on('close', (code) => {
+            clearTimeout(timeout);
+            clearTimeout(killTimer);
+            resolve({ code: stopped ? 0 : Number(code ?? 1), stdout: Buffer.concat(chunks).toString('utf8'), truncated });
+        });
+    });
+}
+async function gitLine(args, cwd) {
+    const result = await runGit(args, { cwd, limit: 64 * 1024 });
+    return result.code === 0 ? result.stdout.trim() : '';
+}
+/** Records of a `-z` stream: NUL-terminated, with a trailing empty remainder. */
+function nulRecords(value) {
+    const records = value.split('\u0000');
+    if (records.length && records[records.length - 1] === '')
+        records.pop();
+    return records;
+}
+function absoluteGitDir(root, value) {
+    if (!value)
+        return '';
+    const resolved = path.isAbsolute(value) ? value : path.resolve(root, value);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * The work tree holding `directory`, and the revision its changes are measured
+ * from. Returns null when the directory is not inside a git work tree at all,
+ * which is an ordinary answer rather than a failure: most directories are not.
+ */
+export async function readGitBaseRevision(directory) {
+    const rootLine = await gitLine(['rev-parse', '--show-toplevel'], directory);
+    if (!rootLine)
+        return null;
+    let root = rootLine;
+    try {
+        root = fs.realpathSync(rootLine);
+    }
+    catch { }
+    const [gitDir, commonDir, head, branchLine] = await Promise.all([
+        gitLine(['rev-parse', '--git-dir'], root),
+        gitLine(['rev-parse', '--git-common-dir'], root),
+        gitLine(['rev-parse', 'HEAD'], root),
+        gitLine(['rev-parse', '--abbrev-ref', 'HEAD'], root),
+    ]);
+    // A repository with no commits has no HEAD to diff against and nothing a
+    // changes view could show, so it is reported as "not a comparable tree".
+    if (!head)
+        return null;
+    const branch = branchLine === 'HEAD' ? '' : branchLine;
+    const linkedWorkTree = Boolean(gitDir && commonDir && absoluteGitDir(root, gitDir) !== absoluteGitDir(root, commonDir));
+    // `origin/HEAD` is the remote's own statement of its default branch and is
+    // consulted only after the local branches, which is where a linked worktree
+    // actually diverged from.
+    const candidates = [...DEFAULT_BRANCH_REFS];
+    const originHead = await gitLine(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root);
+    if (originHead)
+        candidates.push({ ref: `refs/remotes/${originHead}`, label: originHead });
+    let defaultLabel = '';
+    for (const candidate of candidates) {
+        const resolved = await gitLine(['rev-parse', '--verify', '--quiet', candidate.ref], root);
+        if (!resolved)
+            continue;
+        defaultLabel = candidate.label;
+        break;
+    }
+    const defaultShortName = defaultLabel.replace(/^origin\//u, '');
+    const onDefaultBranch = Boolean(branch) && (branch === defaultLabel || branch === defaultShortName);
+    if (!defaultLabel || onDefaultBranch) {
+        return {
+            root,
+            branch,
+            head,
+            baseLabel: 'HEAD',
+            baseOid: head,
+            onDefaultBranch: true,
+            linkedWorkTree,
+        };
+    }
+    const mergeBase = await gitLine(['merge-base', 'HEAD', defaultLabel], root);
+    // Unrelated histories leave nothing to compare with; fall back to HEAD so the
+    // reader still sees their uncommitted work rather than an error.
+    if (!mergeBase) {
+        return { root, branch, head, baseLabel: 'HEAD', baseOid: head, onDefaultBranch: true, linkedWorkTree };
+    }
+    return { root, branch, head, baseLabel: defaultLabel, baseOid: mergeBase, onDefaultBranch: false, linkedWorkTree };
+}
+/** `add TAB del TAB path`, or `add TAB del TAB` followed by the two paths of a
+ * rename. Binary files report `-` for both counts. */
+function parseNumstat(value) {
+    const records = nulRecords(value);
+    const entries = [];
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        const fields = record.split('\t');
+        if (fields.length < 3)
+            continue;
+        const binary = fields[0] === '-' || fields[1] === '-';
+        const additions = binary ? 0 : Number(fields[0]) || 0;
+        const deletions = binary ? 0 : Number(fields[1]) || 0;
+        let relativePath = fields.slice(2).join('\t');
+        let oldRelativePath = '';
+        if (!relativePath) {
+            oldRelativePath = records[index + 1] || '';
+            relativePath = records[index + 2] || '';
+            index += 2;
+        }
+        if (!relativePath)
+            continue;
+        entries.push({ additions, deletions, binary, relativePath, oldRelativePath });
+    }
+    return entries;
+}
+/** `status NUL path`, or `Rnn NUL old NUL new` for a rename or copy. */
+function parseNameStatus(value) {
+    const records = nulRecords(value);
+    const statuses = new Map();
+    for (let index = 0; index < records.length; index += 1) {
+        const code = records[index] || '';
+        if (!code)
+            continue;
+        if (code.startsWith('R') || code.startsWith('C')) {
+            const target = records[index + 2] || '';
+            if (target)
+                statuses.set(target, code[0]);
+            index += 2;
+            continue;
+        }
+        const target = records[index + 1] || '';
+        if (target)
+            statuses.set(target, code[0]);
+        index += 1;
+    }
+    return statuses;
+}
+function changeStatusFromCode(code, renamed) {
+    if (renamed)
+        return 'renamed';
+    if (code === 'A')
+        return 'added';
+    if (code === 'D')
+        return 'deleted';
+    return 'modified';
+}
+/**
+ * Lines a not-yet-tracked file would add.
+ *
+ * Git has nothing to say about a file it has never seen, and running a diff
+ * per untracked path would multiply process spawns by the size of a build
+ * directory. Counting newlines here is bounded by size and stops at the first
+ * NUL, which is also how the file browser decides a file is not text.
+ */
+function untrackedFileCount(absolutePath) {
+    let stat;
+    try {
+        stat = fs.statSync(absolutePath);
+    }
+    catch {
+        return null;
+    }
+    // Git can name something that is not a regular file — a symlink to a
+    // directory, most often a linked `node_modules`. There is no diff for it and
+    // reporting it as a zero-line change would put a mark against a row nothing
+    // happened in.
+    if (!stat.isFile())
+        return null;
+    if (stat.size > MAX_GIT_UNTRACKED_COUNT_BYTES)
+        return { additions: 0, binary: true };
+    let contents;
+    try {
+        contents = fs.readFileSync(absolutePath);
+    }
+    catch {
+        return { additions: 0, binary: false };
+    }
+    if (contents.includes(0))
+        return { additions: 0, binary: true };
+    if (!contents.length)
+        return { additions: 0, binary: false };
+    let lines = 0;
+    for (const byte of contents)
+        if (byte === 0x0a)
+            lines += 1;
+    // A final line without its newline is still a line the diff would show.
+    return { additions: contents[contents.length - 1] === 0x0a ? lines : lines + 1, binary: false };
+}
+function machinePath(root, relativePath) {
+    return path.posix.join(root.split(path.sep).join('/'), relativePath);
+}
+/**
+ * Every path in one work tree that differs from its base revision.
+ *
+ * Tracked differences come from a single `git diff` against the base, which is
+ * what makes the answer a branch range rather than a working-copy status:
+ * commits made on the branch and edits not yet committed are both in it, in
+ * the same way a pull request shows both. Untracked files are added afterwards
+ * because git will not describe a file it has not been told about.
+ */
+export async function readMachineGitStatus({ requested, workingDirectory = '', allowedDirectories = [], }) {
+    const resolved = resolveBrowsePath(String(requested || ''), { workingDirectory, allowedDirectories });
+    const directory = resolved.stat.isDirectory() ? resolved.path : path.dirname(resolved.path);
+    const revision = await readGitBaseRevision(directory);
+    if (!revision)
+        return null;
+    const [numstat, nameStatus, untracked] = await Promise.all([
+        runGit(['diff', '--numstat', '-z', '--find-renames', '--no-color', revision.baseOid, '--'], { cwd: revision.root }),
+        runGit(['diff', '--name-status', '-z', '--find-renames', '--no-color', revision.baseOid, '--'], {
+            cwd: revision.root,
+        }),
+        runGit(['ls-files', '-z', '--others', '--exclude-standard'], { cwd: revision.root }),
+    ]);
+    const statuses = parseNameStatus(nameStatus.stdout);
+    const files = [];
+    for (const entry of parseNumstat(numstat.stdout)) {
+        const code = statuses.get(entry.relativePath) || 'M';
+        const status = changeStatusFromCode(code, Boolean(entry.oldRelativePath));
+        files.push({
+            path: machinePath(revision.root, entry.relativePath),
+            relativePath: entry.relativePath,
+            status,
+            additions: entry.additions,
+            deletions: entry.deletions,
+            ...(entry.binary ? { binary: true } : {}),
+            ...(entry.oldRelativePath ? { oldRelativePath: entry.oldRelativePath } : {}),
+        });
+        if (files.length >= MAX_GIT_STATUS_FILES)
+            break;
+    }
+    let truncated = numstat.truncated || nameStatus.truncated || untracked.truncated || files.length >= MAX_GIT_STATUS_FILES;
+    for (const relativePath of nulRecords(untracked.stdout)) {
+        if (!relativePath)
+            continue;
+        if (files.length >= MAX_GIT_STATUS_FILES) {
+            truncated = true;
+            break;
+        }
+        const absolute = machinePath(revision.root, relativePath);
+        const counted = untrackedFileCount(absolute);
+        if (!counted)
+            continue;
+        files.push({
+            path: absolute,
+            relativePath,
+            status: 'untracked',
+            additions: counted.additions,
+            deletions: 0,
+            ...(counted.binary ? { binary: true } : {}),
+        });
+    }
+    return {
+        root: revision.root,
+        branch: revision.branch,
+        head: revision.head,
+        baseLabel: revision.baseLabel,
+        baseOid: revision.baseOid,
+        onDefaultBranch: revision.onDefaultBranch,
+        linkedWorkTree: revision.linkedWorkTree,
+        files,
+        additions: files.reduce((total, file) => total + file.additions, 0),
+        deletions: files.reduce((total, file) => total + file.deletions, 0),
+        truncated,
+    };
+}
+/**
+ * One unified patch for the whole work tree, as a review would read it.
+ *
+ * Untracked files are appended as separate `--no-index` patches against
+ * `/dev/null`, which is the same shape git emits for a new file in an ordinary
+ * diff — so the browser's existing unified-diff parser reads both without
+ * knowing which came from where. Only as many as fit under the byte ceiling
+ * are asked for; a patch this long has already stopped being reviewable.
+ */
+export async function readMachineGitPatch({ requested, workingDirectory = '', allowedDirectories = [], }) {
+    const resolved = resolveBrowsePath(String(requested || ''), { workingDirectory, allowedDirectories });
+    const directory = resolved.stat.isDirectory() ? resolved.path : path.dirname(resolved.path);
+    const revision = await readGitBaseRevision(directory);
+    if (!revision)
+        return null;
+    const tracked = await runGit(['diff', '--patch', '--no-color', '--find-renames', '--no-ext-diff', revision.baseOid, '--'], { cwd: revision.root });
+    let patch = tracked.stdout;
+    let truncated = tracked.truncated;
+    if (!truncated) {
+        const untracked = await runGit(['ls-files', '-z', '--others', '--exclude-standard'], { cwd: revision.root });
+        truncated = untracked.truncated;
+        for (const relativePath of nulRecords(untracked.stdout)) {
+            if (!relativePath)
+                continue;
+            if (patch.length >= MAX_GIT_TEXT_BYTES) {
+                truncated = true;
+                break;
+            }
+            // `--no-index` against /dev/null exits 1 on every difference, which is
+            // the normal outcome here rather than a failure.
+            const added = await runGit(['diff', '--no-color', '--no-ext-diff', '--no-index', '--', '/dev/null', relativePath], { cwd: revision.root, limit: Math.max(0, MAX_GIT_TEXT_BYTES - patch.length) });
+            if (added.truncated)
+                truncated = true;
+            if (added.stdout)
+                patch += added.stdout;
+        }
+    }
+    return {
+        root: revision.root,
+        baseLabel: revision.baseLabel,
+        baseOid: revision.baseOid,
+        patch: patch.slice(0, MAX_GIT_TEXT_BYTES),
+        truncated: truncated || patch.length > MAX_GIT_TEXT_BYTES,
+    };
+}
+/**
+ * One file as the base revision holds it, for the viewer's inline diff.
+ *
+ * A file that did not exist at the base is a normal answer — it is what the
+ * viewer needs in order to show the whole file as added — so a missing blob
+ * reports `found: false` rather than raising. Bytes that are not decodable
+ * text are reported as binary instead of being rendered as replacement noise.
+ */
+export async function readMachineGitBaseBlob({ requested, workingDirectory = '', allowedDirectories = [], }) {
+    const resolved = resolveBrowsePath(String(requested || ''), { workingDirectory, allowedDirectories });
+    if (!resolved.stat.isFile())
+        throw new Error(`Not a file: ${resolved.path}`);
+    const revision = await readGitBaseRevision(path.dirname(resolved.path));
+    if (!revision)
+        return null;
+    const relative = path.relative(revision.root, resolved.path).split(path.sep).join('/');
+    if (!relative || relative.startsWith('..'))
+        return null;
+    const shown = await runGit(['show', `${revision.baseOid}:${relative}`], { cwd: revision.root });
+    const found = shown.code === 0;
+    const binary = found && shown.stdout.includes('\u0000');
+    return {
+        path: resolved.path,
+        baseLabel: revision.baseLabel,
+        baseOid: revision.baseOid,
+        found,
+        text: found && !binary ? shown.stdout : '',
+        truncated: found && shown.truncated,
+        binary,
+    };
+}

package/dist/path-resolution.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { Transform } from 'node:stream';
 /**
  * Turning the paths an agent writes into things a reader can open.
  *
@@ -169,6 +170,189 @@ function uploadHeaders(options) {
         ? { 'x-turns-dev-user': options.devUser, 'x-turns-dev-role': 'uploader' }
         : { authorization: `Bearer ${options.token}` };
 }
+/** Keep directory separators readable while escaping characters that would
+ * otherwise change the URL's path, query, or fragment. */
+function fileUploadUrl(baseUrl, machine, absolutePath) {
+    const encoded = absolutePath.split('/').map(encodeURIComponent).join('/');
+    const encodedPath = encoded.startsWith('//')
+        ? `%2F%2F${encoded.slice(2)}`
+        : encoded.startsWith('/')
+            ? encoded.slice(1)
+            : encoded;
+    return new URL(`/api/file/${encodeURIComponent(machine)}/${encodedPath}`, String(baseUrl));
+}
+/** Kept in step with the explicit-browse transport constants in shared/files.ts. */
+export const MAX_SINGLE_BROWSE_UPLOAD_BYTES = 100 * 1024 * 1024;
+export const BROWSE_MULTIPART_PART_BYTES = 32 * 1024 * 1024;
+export const MAX_BROWSE_MULTIPART_PARTS = 64;
+export function filePartRanges(bytes, partSize = BROWSE_MULTIPART_PART_BYTES) {
+    if (!Number.isSafeInteger(bytes) || bytes <= 0 || !Number.isSafeInteger(partSize) || partSize <= 0)
+        return [];
+    const ranges = [];
+    for (let start = 0, partNumber = 1; start < bytes; start += partSize, partNumber += 1) {
+        ranges.push({ partNumber, start, end: Math.min(bytes, start + partSize) });
+    }
+    return ranges;
+}
+function fileMultipartUrl(baseUrl, machine, absolutePath, suffix = '') {
+    const url = new URL(`/api/file-multipart/${encodeURIComponent(machine)}${suffix}`, String(baseUrl));
+    url.searchParams.set('path', absolutePath);
+    return url;
+}
+function progressStream(absolutePath, start, end, onProgress) {
+    const source = fs.createReadStream(absolutePath, { start, end: end - 1 });
+    let loaded = 0;
+    const body = new Transform({
+        transform(chunk, _encoding, callback) {
+            loaded += chunk.byteLength;
+            onProgress?.(loaded);
+            callback(null, chunk);
+        },
+    });
+    source.pipe(body);
+    return {
+        body,
+        destroy() {
+            source.destroy();
+            body.destroy();
+        },
+    };
+}
+async function uploadFailure(response, label) {
+    const detail = (await response.text().catch(() => '')).trim();
+    return new Error(`${label} (${response.status})${detail ? `: ${detail.slice(0, 500)}` : '.'}`);
+}
+function retryDelay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function uploadMultipartFile({ baseUrl, options, machine, absolutePath, contentType, bytes, modifiedAt, contentEtag, onProgress, onFinalizing, fetchImpl, }) {
+    const createUrl = fileMultipartUrl(baseUrl, machine, absolutePath);
+    const createBody = JSON.stringify({
+        size: bytes,
+        contentType,
+        ...(modifiedAt ? { modifiedAt } : {}),
+        ...(contentEtag ? { contentEtag } : {}),
+    });
+    const created = await fetchImpl(createUrl, {
+        method: 'POST',
+        headers: {
+            ...uploadHeaders(options),
+            'content-type': 'application/json',
+            'content-length': String(Buffer.byteLength(createBody)),
+        },
+        body: createBody,
+    });
+    if (!created.ok)
+        throw await uploadFailure(created, 'Multipart file upload could not start');
+    const payload = (await created.json().catch(() => ({})));
+    const uploadId = String(payload.upload?.uploadId || '');
+    const partSize = Number(payload.upload?.partSize);
+    const receiptToken = String(payload.upload?.receiptToken || '');
+    if (!uploadId ||
+        !receiptToken ||
+        !Number.isSafeInteger(partSize) ||
+        partSize <= 0 ||
+        partSize > BROWSE_MULTIPART_PART_BYTES) {
+        throw new Error('Multipart file upload returned an invalid session.');
+    }
+    const ranges = filePartRanges(bytes, partSize);
+    if (!ranges.length || ranges.length > MAX_BROWSE_MULTIPART_PARTS) {
+        throw new Error('Multipart file upload returned an invalid part size.');
+    }
+    const parts = [];
+    let completed = 0;
+    try {
+        for (const range of ranges) {
+            const length = range.end - range.start;
+            let receipt = null;
+            let greatestLoaded = 0;
+            let lastError = null;
+            for (let attempt = 0; attempt < 3 && !receipt; attempt += 1) {
+                const stream = progressStream(absolutePath, range.start, range.end, (loaded) => {
+                    greatestLoaded = Math.max(greatestLoaded, loaded);
+                    onProgress?.(Math.min(bytes, completed + greatestLoaded));
+                });
+                try {
+                    const partUrl = fileMultipartUrl(baseUrl, machine, absolutePath, `/parts/${range.partNumber}`);
+                    partUrl.searchParams.set('upload_id', uploadId);
+                    const response = await fetchImpl(partUrl, {
+                        method: 'PUT',
+                        headers: {
+                            ...uploadHeaders(options),
+                            'content-type': 'application/octet-stream',
+                            'content-length': String(length),
+                        },
+                        body: stream.body,
+                        duplex: 'half',
+                    });
+                    if (!response.ok)
+                        throw await uploadFailure(response, `Multipart file part ${range.partNumber} failed`);
+                    const answer = (await response.json().catch(() => ({})));
+                    if (answer.part?.partNumber !== range.partNumber || !answer.part.etag) {
+                        throw new Error(`Multipart file part ${range.partNumber} returned no receipt.`);
+                    }
+                    receipt = { partNumber: range.partNumber, etag: String(answer.part.etag) };
+                }
+                catch (error) {
+                    lastError = error;
+                    if (attempt < 2)
+                        await retryDelay(250 * 2 ** attempt);
+                }
+                finally {
+                    stream.destroy();
+                }
+            }
+            if (!receipt)
+                throw lastError instanceof Error ? lastError : new Error(String(lastError || 'File part failed.'));
+            parts.push(receipt);
+            completed += length;
+            onProgress?.(completed);
+        }
+        const completeUrl = fileMultipartUrl(baseUrl, machine, absolutePath, '/complete');
+        completeUrl.searchParams.set('upload_id', uploadId);
+        const completeBody = JSON.stringify({ parts, size: bytes, receiptToken });
+        onFinalizing?.();
+        let completedUpload = false;
+        let completionError = null;
+        for (let attempt = 0; attempt < 3 && !completedUpload; attempt += 1) {
+            try {
+                const response = await fetchImpl(completeUrl, {
+                    method: 'POST',
+                    headers: {
+                        ...uploadHeaders(options),
+                        'content-type': 'application/json',
+                        'content-length': String(Buffer.byteLength(completeBody)),
+                    },
+                    body: completeBody,
+                });
+                if (!response.ok) {
+                    const failure = await uploadFailure(response, 'Multipart file upload could not finish');
+                    if (response.status < 500 && response.status !== 408 && response.status !== 429)
+                        throw failure;
+                    completionError = failure;
+                }
+                else {
+                    completedUpload = true;
+                }
+            }
+            catch (error) {
+                completionError = error;
+            }
+            if (!completedUpload && attempt < 2)
+                await retryDelay(250 * 2 ** attempt);
+        }
+        if (!completedUpload) {
+            throw completionError instanceof Error ? completionError : new Error('Multipart file upload could not finish.');
+        }
+        return true;
+    }
+    catch (error) {
+        const abortUrl = fileMultipartUrl(baseUrl, machine, absolutePath);
+        abortUrl.searchParams.set('upload_id', uploadId);
+        await fetchImpl(abortUrl, { method: 'DELETE', headers: uploadHeaders(options) }).catch(() => { });
+        throw error;
+    }
+}
 /**
  * Put bytes in the account's private prefix, under the path they came from.
  *
@@ -177,7 +361,7 @@ function uploadHeaders(options) {
  * the upload is not part of what was stored.
  */
 export async function uploadFileBytes({ baseUrl, options, machine, absolutePath, contentType, modifiedAt, body, fetchImpl = fetch, }) {
-    const url = new URL(`/api/file/${encodeURIComponent(machine)}/${encodeURIComponent(absolutePath)}`, String(baseUrl));
+    const url = fileUploadUrl(baseUrl, machine, absolutePath);
     const response = await fetchImpl(url, {
         method: 'PUT',
         headers: {
@@ -193,9 +377,31 @@ export async function uploadFileBytes({ baseUrl, options, machine, absolutePath,
     return true;
 }
 /** Stream one on-disk file to R2 without retaining its body in the daemon. */
-export async function uploadFileStream({ baseUrl, options, machine, absolutePath, contentType, bytes, modifiedAt, contentEtag, fetchImpl = fetch, }) {
-    const url = new URL(`/api/file/${encodeURIComponent(machine)}/${encodeURIComponent(absolutePath)}`, String(baseUrl));
-    const body = fs.createReadStream(absolutePath);
+export async function uploadFileStream({ baseUrl, options, machine, absolutePath, contentType, bytes, modifiedAt, contentEtag, onProgress, onFinalizing, fetchImpl = fetch, }) {
+    if (bytes > MAX_SINGLE_BROWSE_UPLOAD_BYTES) {
+        return uploadMultipartFile({
+            baseUrl,
+            options,
+            machine,
+            absolutePath,
+            contentType,
+            bytes,
+            modifiedAt,
+            contentEtag,
+            onProgress,
+            onFinalizing,
+            fetchImpl,
+        });
+    }
+    const url = fileUploadUrl(baseUrl, machine, absolutePath);
+    let finalizing = false;
+    const stream = progressStream(absolutePath, 0, bytes, (uploadedBytes) => {
+        onProgress?.(uploadedBytes);
+        if (!finalizing && uploadedBytes >= bytes) {
+            finalizing = true;
+            onFinalizing?.();
+        }
+    });
     try {
         const response = await fetchImpl(url, {
             method: 'PUT',
@@ -206,7 +412,7 @@ export async function uploadFileStream({ baseUrl, options, machine, absolutePath
                 ...(modifiedAt ? { 'x-turns-file-modified-at': modifiedAt } : {}),
                 ...(contentEtag ? { 'x-turns-content-etag': contentEtag } : {}),
             },
-            body,
+            body: stream.body,
             // Node requires this opt-in for a streaming request body.
             duplex: 'half',
         });
@@ -215,7 +421,7 @@ export async function uploadFileStream({ baseUrl, options, machine, absolutePath
         return true;
     }
     finally {
-        body.destroy();
+        stream.destroy();
     }
 }
 /** Send one resolved file to the account's private prefix. */

package/dist/queue-worker.js

@@ -6,9 +6,10 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { anchorId, connectExistingAgentAnchors, launchAgentAnchor, waitForAgentTurn } from "./agent-anchor-client.js";
 import { assertAllowedWorkingDirectory, workingDirectoryIsAllowed } from "./directory-policy.js";
-import { browseMachinePath } from "./file-browsing.js";
+import { browseMachinePath, streamMachineFileRange } from "./file-browsing.js";
 import { applyFileEdit } from "./file-edits.js";
 import { searchMachinePaths } from "./file-search.js";
+import { readMachineGitBaseBlob, readMachineGitPatch, readMachineGitStatus } from "./git-status.js";
 import { nativeDescriptorAgentSessionId, nativeDescriptorWorkingDirectory } from "./local-session-sources.js";
 import { compactRuntimeValue } from "./native-record-compaction.js";
 import { createSecretRedactor } from "./secret-redaction.js";
@@ -1051,6 +1052,14 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
                 baseUrl,
                 options,
                 workingDirectory: await browseWorkingDirectory(sessionId),
+                onUploadProgress: (progress) => {
+                    replyRpc.notify({
+                        type: 'session.file.browse.progress',
+                        requestId: message.requestId,
+                        sessionId,
+                        ...progress,
+                    });
+                },
             });
             replyRpc.notify({
                 type: 'session.file.browse.result',
@@ -1070,6 +1079,57 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             });
         }
     };
+    /** Stream a small file window over the control socket. This never writes R2;
+     * range-based viewers can therefore paint before a multi-gigabyte upload. */
+    const handleFileRange = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        let canonicalPath = '';
+        try {
+            await streamMachineFileRange({
+                requested: String(message.path || ''),
+                offset: Number(message.offset),
+                length: Number(message.length),
+                workingDirectory: await browseWorkingDirectory(sessionId),
+                allowedDirectories: options.allowedDirectories || [],
+                onReady: (range) => {
+                    canonicalPath = range.path;
+                    replyRpc.notify({
+                        type: 'session.file.range.ready',
+                        requestId: message.requestId,
+                        sessionId,
+                        ...range,
+                    });
+                },
+                onChunk: (offset, bytes) => {
+                    replyRpc.notify({
+                        type: 'session.file.range.chunk',
+                        requestId: message.requestId,
+                        sessionId,
+                        path: canonicalPath,
+                        offset,
+                        data: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64'),
+                    });
+                },
+            });
+            replyRpc.notify({
+                type: 'session.file.range.result',
+                requestId: message.requestId,
+                sessionId,
+                path: canonicalPath,
+                ok: true,
+            });
+        }
+        catch (error) {
+            replyRpc.notify({
+                type: 'session.file.range.result',
+                requestId: message.requestId,
+                sessionId,
+                ...(canonicalPath ? { path: canonicalPath } : {}),
+                ok: false,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
     /** Refresh recursive path-name matches for directory typeahead.
      *
      * Like browsing, this is a machine filesystem operation rather than a
@@ -1103,6 +1163,49 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             });
         }
     };
+    /**
+     * Answer one git question about a path on this machine.
+     *
+     * Like browsing and searching, this is a property of the filesystem rather
+     * than of a harness, so a stopped session's tree remains readable. A path
+     * that is not inside a work tree answers `ok` with nothing attached: the
+     * browser needs to tell "not a repository" apart from "the machine failed",
+     * and only the first should leave its git column quietly empty.
+     */
+    const handleGitRead = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        const want = message.want === 'diff' ? 'diff' : message.want === 'base' ? 'base' : 'status';
+        try {
+            const input = {
+                requested: String(message.path || ''),
+                workingDirectory: await browseWorkingDirectory(sessionId),
+                allowedDirectories: options.allowedDirectories || [],
+            };
+            const git = want === 'diff'
+                ? await readMachineGitPatch(input).then((patch) => (patch ? { patch } : null))
+                : want === 'base'
+                    ? await readMachineGitBaseBlob(input).then((base) => (base ? { base } : null))
+                    : await readMachineGitStatus(input).then((status) => (status ? { status } : null));
+            replyRpc.notify({
+                type: 'session.git.read.result',
+                requestId: message.requestId,
+                sessionId,
+                ok: true,
+                want,
+                git,
+            });
+        }
+        catch (error) {
+            replyRpc.notify({
+                type: 'session.git.read.result',
+                requestId: message.requestId,
+                sessionId,
+                ok: false,
+                want,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
     /**
      * Apply one queued browser edit, and report how it went.
      *
@@ -1173,8 +1276,12 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             void handleInteractionAnswer(message, rpc);
         if (message.type === 'session.file.browse.request')
             void handleFileBrowse(message, rpc);
+        if (message.type === 'session.file.range.request')
+            void handleFileRange(message, rpc);
         if (message.type === 'session.file.search.request')
             void handleFileSearch(message, rpc);
+        if (message.type === 'session.git.read.request')
+            void handleGitRead(message, rpc);
         if (message.type === 'session.file.edit.request')
             void handleFileEdit(message, rpc);
     });
@@ -1189,7 +1296,7 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
                 type: 'machine.register',
                 machineId: machine,
                 machineHostname: os.hostname(),
-                capabilities: { fileSearch: true },
+                capabilities: { fileSearch: true, git: true, fileRanges: true },
                 workerId,
                 workerInstanceId,
                 anchorSessionIds: [...anchors.keys()],

package/dist/upload-sessions.js

@@ -946,8 +946,9 @@ function gitAssociationForSession(cwd, redactor) {
  * @param {number} [options.maxBatches]
  * @param {() => boolean} [options.shouldYield]
  * @param {boolean} [options.recoverRemoteAhead]
+ * @param {boolean} [options.forceReset]
  */
-export async function uploadNativeSession(rpc, machine, descriptor, cursor = {}, onProgress = () => { }, redactor = DEFAULT_REDACTOR, { maxBatches = Number.POSITIVE_INFINITY, shouldYield = () => false, recoverRemoteAhead = true, onPathCandidates = (_sessionId, _workingDirectory, _candidates) => { }, } = {}) {
+export async function uploadNativeSession(rpc, machine, descriptor, cursor = {}, onProgress = () => { }, redactor = DEFAULT_REDACTOR, { maxBatches = Number.POSITIVE_INFINITY, shouldYield = () => false, recoverRemoteAhead = true, forceReset = false, onPathCandidates = (_sessionId, _workingDirectory, _candidates) => { }, } = {}) {
     const workingDirectory = await nativeDescriptorWorkingDirectory(descriptor);
     const agentSessionId = await nativeDescriptorAgentSessionId(descriptor);
     const git = gitAssociationForSession(workingDirectory, redactor);
@@ -976,7 +977,14 @@ export async function uploadNativeSession(rpc, machine, descriptor, cursor = {},
     const uploadSessionId = String(opened.sessionId || sessionId);
     let nextRow = Number(opened.nextRow) || 0;
     let initialUpload = nextRow === 0 || cursor.initialUpload === true;
-    if (Number(opened.redactionVersion || 0) !== REDACTION_VERSION) {
+    if (forceReset && nextRow > 0) {
+        await rpc.request({ type: 'session.reset', sessionId: uploadSessionId, redactionVersion: REDACTION_VERSION });
+        nextRow = 0;
+        for (const key of Object.keys(cursor))
+            delete cursor[key];
+        initialUpload = true;
+    }
+    else if (Number(opened.redactionVersion || 0) !== REDACTION_VERSION) {
         await rpc.request({ type: 'session.reset', sessionId: uploadSessionId, redactionVersion: REDACTION_VERSION });
         nextRow = 0;
         for (const key of Object.keys(cursor))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turns/dev",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Upload local AI agent sessions to turns.dev",
   "license": "MIT",
   "type": "module",