@turns/dev 0.0.1 → 0.0.3

package/README.md

@@ -14,8 +14,9 @@ npm install --global @turns/dev
 ## Commands
 
 ```text
-turns                         upload sessions for the current directory once
-turns upload [directory]      watch one directory
+turns                         watch and stream sessions for the current directory
+turns upload [directory]      watch and stream sessions for one directory
+turns --once [directory]      upload that directory's sessions once and exit
 turns install                 install the all-directory user daemon
 turns status                  report daemon state
 turns uninstall               remove the daemon
@@ -23,6 +24,20 @@ turns login                   replace saved credentials through the browser
 turns logout                  remove saved credentials
 ```
 
+`turns` and `turns upload DIRECTORY` are the daemon scoped to one directory
+tree: they keep watching, stream live rows as the harness writes them, and
+serve prompts queued from the web until interrupted. That directory is the
+allowlist, so sessions in its subdirectories are followed and agent launches
+cannot start outside it. Run `turns install` instead for an unattended
+all-directory daemon; while that daemon is active a foreground run declines to
+start a second uploader, since both would write the same upload-cursor file.
+
+`--once` sweeps the same directory tree and exits as soon as its sessions are
+current, for scripts and CI steps that need an upload to finish rather than a
+process to stay resident. A run narrowed to a directory — watching or `--once` —
+never prunes saved upload cursors, so it cannot make the sessions it filtered
+out replay from their first byte the next time the daemon starts.
+
 The server is selected with `--server URL` or `TURNS_ORIGIN`. Its normalized
 origin is saved in `~/.config/turns/credentials.json` and reused by later
 invocations and daemon starts. On Linux the other persistent files are:
@@ -42,7 +57,7 @@ Rows are scanned on their way out for substrings that look like file paths —
 filesystem confirms is recorded on the session's own log as a resolution: the
 substring, the absolute path, the size, and whether the contents were sent.
 Paths resolve against the session's working directory and are canonicalised
-before the `--allow-directory` prefixes are enforced, so a symlink out of an
+before the `--directory` prefixes are enforced, so a symlink out of an
 allowed tree is not a way to read the disk.
 
 Only images under 10 MB are uploaded, to `PUT /api/file/{machine}/{path}`. Everything else is recorded as a name, so
@@ -59,16 +74,16 @@ straight to R2, so neither process retains the complete file in memory.
 The systemd unit uses `KillMode=process`: restarting the uploader leaves its
 detached agent-anchor processes running so in-flight harness turns continue.
 For a foreground daemon restricted to one or more directory trees, repeat
-`--allow-directory`. Both transcript discovery and agent launches enforce the
+`--directory`. Both transcript discovery and agent launches enforce the
 canonical prefix, including protection against symlinks that escape it:
 
 ```sh
-turns daemon run --server https://turns.example --allow-directory /srv/agents
+turns daemon run --server https://turns.example --directory /srv/agents
 ```
 
 Against local Wrangler development, use the configured `DEV_USER` directly:
 
 ```sh
 turns daemon run --server http://127.0.0.1:8787 \
-  --dev-user antimatter15 --allow-directory /tmp/turns-driver-workspaces
+  --dev-user antimatter15 --directory /tmp/turns-driver-workspaces
 ```

package/dist/agent-anchor.js

@@ -682,8 +682,13 @@ class AcpTransport extends LineTransport {
             await this.request('session/set_mode', { sessionId: this.sessionId, modeId: this.profile.mode }, 30_000);
         }
         const model = this.anchor.model && this.anchor.model !== 'auto' ? this.anchor.model : this.profile.model;
-        if (model)
-            await this.request('session/set_model', { sessionId: this.sessionId, modelId: model }, 30_000).catch(() => { });
+        if (model) {
+            const method = this.profile.modelOption ? 'session/set_config_option' : 'session/set_model';
+            const params = this.profile.modelOption
+                ? { sessionId: this.sessionId, configId: 'model', value: model }
+                : { sessionId: this.sessionId, modelId: model };
+            await this.request(method, params, 30_000).catch(() => { });
+        }
         this.ready = true;
     }
     prompt(text, timeoutMs) {

package/dist/file-browsing.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -7,16 +8,14 @@ import { uploadFileBytes, uploadFileStream } from "./path-resolution.js";
  * Answering "what is in that directory?" from the machine that knows.
  *
  * A reader's browser cannot reach this machine, and this machine will not open
- * a port to let it try. So a browse is served the way an embedded image already
- * is: the daemon reads the path, puts what it found in the account's own
- * prefix, and the server hands the reader a signed URL for that object. Regular
- * files stream from disk to that object; nothing stays open once the one browse
- * upload finishes.
+ * a port to let it try. Directories are small structured answers, so the daemon
+ * sends their listing on the control socket immediately and stores the same
+ * bytes in the background for offline browsing. Regular files still stream to
+ * object storage; nothing stays open once the one browse upload finishes.
  *
- * A directory has no bytes, so what is uploaded for one is a listing of it,
- * stored at `_index.json` beneath the directory. Every path is canonicalised
- * before the allowlist is consulted, so a symlink pointing out of an allowed
- * tree is not a way to read the rest of the disk.
+ * A directory's fallback is stored at `_index.json` beneath it. Every path is
+ * canonicalised before the allowlist is consulted, so a symlink pointing out
+ * of an allowed tree is not a way to read the rest of the disk.
  */
 /** Kept in step with `MAX_DIRECTORY_ENTRIES` in the Worker's shared listing. */
 export const MAX_DIRECTORY_ENTRIES = 2_000;
@@ -26,62 +25,9 @@ export const DIRECTORY_INDEX_NAME = '_index.json';
 export const MAX_BROWSE_FILE_BYTES = 199 * 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`;
-/** Extensions a reader can be shown as text, whatever produced them. */
-const TEXT_EXTENSIONS = new Set([
-    '.bash',
-    '.c',
-    '.cc',
-    '.cfg',
-    '.conf',
-    '.cpp',
-    '.cs',
-    '.css',
-    '.csv',
-    '.diff',
-    '.env',
-    '.go',
-    '.gradle',
-    '.h',
-    '.hpp',
-    '.htm',
-    '.html',
-    '.ini',
-    '.java',
-    '.jsonl',
-    '.jsx',
-    '.kt',
-    '.less',
-    '.lock',
-    '.log',
-    '.lua',
-    '.m',
-    '.md',
-    '.mjs',
-    '.cjs',
-    '.mts',
-    '.patch',
-    '.php',
-    '.pl',
-    '.properties',
-    '.py',
-    '.r',
-    '.rb',
-    '.rs',
-    '.scss',
-    '.sh',
-    '.sql',
-    '.swift',
-    '.tf',
-    '.toml',
-    '.ts',
-    '.tsx',
-    '.txt',
-    '.vue',
-    '.xml',
-    '.yaml',
-    '.yml',
-    '.zsh',
-]);
+/** 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;
 /** Extensions carrying their own type, where guessing text would be wrong. */
 const BINARY_CONTENT_TYPES = new Map([
     ['.apng', 'image/apng'],
@@ -104,23 +50,55 @@ const BINARY_CONTENT_TYPES = new Map([
     ['.zip', 'application/zip'],
 ]);
 /**
- * How one browsed file should be served back.
- *
- * A name with no extension at all — `README`, `Makefile`, `Dockerfile` — is
- * nearly always text, and is the one guess worth making. Everything unrecognised
- * is served as bytes: the Worker sends it with `nosniff` under a sandboxing
- * policy, so an unhelpful type is only ever unhelpful.
+ * Whether a bounded sample can safely be decoded in the browser's text editor.
+ * NUL and uncommon ASCII control bytes are strong binary signals; strict UTF-8
+ * keeps arbitrary binary from being rendered as replacement-character noise.
+ * An incomplete final code point is allowed only when the sample is a prefix.
  */
-export function browseContentType(file) {
+export function fileSampleIsText(sample, complete) {
+    let controls = 0;
+    for (const byte of sample) {
+        if (byte === 0)
+            return false;
+        if (byte < 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0c && byte !== 0x0d && byte !== 0x1b) {
+            controls += 1;
+        }
+    }
+    if (controls / Math.max(1, sample.byteLength) > 0.01)
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(sample, { stream: !complete });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** How one browsed file should be served back. Explicit media containers keep
+ * their MIME type; source, prose, and unknown extensions are decided by bytes.
+ * The extension only refines textual JSON after the sample has passed. */
+export function browseContentType(file, sample, complete) {
     const extension = path.extname(file).toLowerCase();
     const known = BINARY_CONTENT_TYPES.get(extension);
     if (known)
         return known;
-    if (extension === '.json')
-        return 'application/json';
-    if (!extension || TEXT_EXTENSIONS.has(extension))
-        return 'text/plain; charset=utf-8';
-    return 'application/octet-stream';
+    if (!fileSampleIsText(sample, complete))
+        return 'application/octet-stream';
+    return extension === '.json' ? 'application/json' : 'text/plain; charset=utf-8';
+}
+function readFileTypeSample(file, bytes) {
+    const length = Math.min(bytes, FILE_TYPE_SAMPLE_BYTES);
+    if (!length)
+        return new Uint8Array();
+    const sample = Buffer.allocUnsafe(length);
+    const handle = fs.openSync(file, 'r');
+    try {
+        const read = fs.readSync(handle, sample, 0, length, 0);
+        return sample.subarray(0, read);
+    }
+    finally {
+        fs.closeSync(handle);
+    }
 }
 function isoTime(value) {
     return Number.isFinite(value) ? new Date(value).toISOString() : '';
@@ -193,39 +171,42 @@ export function readDirectory(directory) {
 export function directoryIndexPath(directory) {
     return `${String(directory || '').replace(/\/+$/u, '')}/${DIRECTORY_INDEX_NAME}`;
 }
-/**
- * Store one path for a reader, and say what was stored.
- *
- * An empty file is a legitimate thing to open and has no bytes to upload, so it
- * is reported rather than sent — the reader is told the file is empty instead of
- * being handed a URL for an object that was never written. A file past the
- * upload ceiling is refused here, where the size is known, rather than by the
- * Worker after the bytes have crossed the network.
- */
 export async function browseMachinePath({ requested, machine, baseUrl, options, workingDirectory = '', fetchImpl = fetch, }) {
     const resolved = resolveBrowsePath(requested, {
         workingDirectory,
         allowedDirectories: options.allowedDirectories || [],
     });
     if (resolved.stat.isDirectory()) {
-        const body = new TextEncoder().encode(JSON.stringify(readDirectory(resolved.path)));
+        const listing = readDirectory(resolved.path);
+        const body = new TextEncoder().encode(JSON.stringify(listing));
         if (body.byteLength > MAX_BROWSE_FILE_BYTES)
             throw new Error(`Directory listing is too large: ${resolved.path}`);
-        await uploadFileBytes({
+        const etag = crypto.createHash('sha256').update(body).digest('hex');
+        const cache = uploadFileBytes({
             baseUrl,
             options,
             machine,
             absolutePath: directoryIndexPath(resolved.path),
             contentType: 'application/json',
+            contentEtag: etag,
             body,
             fetchImpl,
         });
-        return { path: resolved.path, kind: 'directory', bytes: body.byteLength, contentType: 'application/json' };
+        return {
+            path: resolved.path,
+            kind: 'directory',
+            bytes: body.byteLength,
+            contentType: 'application/json',
+            listing,
+            etag,
+            cache,
+        };
     }
-    const contentType = browseContentType(resolved.path);
     if (resolved.stat.size > MAX_BROWSE_FILE_BYTES) {
         throw new Error(`File is larger than the ${BROWSE_FILE_LIMIT_LABEL} browse limit.`);
     }
+    const sample = readFileTypeSample(resolved.path, resolved.stat.size);
+    const contentType = browseContentType(resolved.path, sample, sample.byteLength === resolved.stat.size);
     if (resolved.stat.size === 0)
         return { path: resolved.path, kind: 'file', bytes: 0, contentType };
     await uploadFileStream({

package/dist/harness-registry.js

@@ -144,6 +144,17 @@ export const ACP_PROFILES = {
         mcp: true,
     },
     vibe: { command: 'vibe-acp', args: [], mcp: true },
+    fx: {
+        command: 'fx',
+        args: ['acp'],
+        // Fx reads the process-wide policy when the ACP server starts. Setting a
+        // session mode afterwards would replace `yolo` with code mode's `auto`, so
+        // bypass deliberately has no session/set_mode call.
+        env: (permissionMode) => ({ FX_PERMISSION_MODE: permissionMode === 'bypassPermissions' ? 'yolo' : 'ask' }),
+        mode: (permissionMode) => (permissionMode === 'bypassPermissions' ? undefined : 'ask'),
+        modelOption: true,
+        mcp: true,
+    },
 };
 // These harnesses keep one bidirectional process attached to the anchor. They
 // are listed separately from process harnesses so queued turns cannot

package/dist/index.js

@@ -62,8 +62,9 @@ function help() {
     return `Turns ${pkg.version}
 
 Usage:
-  turns                         Upload sessions for the current directory once
-  turns upload [directory]      Watch sessions belonging to one directory
+  turns                         Watch and stream sessions for the current directory
+  turns upload [directory]      Watch and stream sessions for one directory
+  turns --once [directory]      Upload the directory's sessions once and exit
   turns install                 Install and start the all-directory daemon
   turns status                  Show daemon status
   turns uninstall               Stop and uninstall the background daemon
@@ -73,7 +74,8 @@ Usage:
 
 Options:
   --server URL                  Use a Turns server (saved with credentials)
-  --allow-directory PATH        Restrict daemon uploads/launches to this prefix (repeatable)
+  --once                        Upload once and exit instead of watching
+  --directory PATH              Restrict daemon uploads/launches to this prefix (repeatable)
   --dev-user LOGIN              Authenticate to a local Wrangler DEV_USER server
   --no-browser                  Print the authentication URL without opening it
 
@@ -86,6 +88,7 @@ function parseGlobalArguments(argv) {
     const remaining = [];
     let origin = process.env.TURNS_ORIGIN || process.env.TURNS_SERVER || '';
     let devUser = '';
+    let once = false;
     const allowedDirectories = [];
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
@@ -95,7 +98,7 @@ function parseGlobalArguments(argv) {
                 throw new Error(`${argument} requires a URL.`);
             origin = value;
         }
-        else if (argument === '--allow-directory') {
+        else if (argument === '--directory') {
             const value = argv[++index];
             if (!value)
                 throw new Error(`${argument} requires a path.`);
@@ -107,6 +110,9 @@ function parseGlobalArguments(argv) {
                 throw new Error(`${argument} requires a login.`);
             devUser = value.trim().toLowerCase();
         }
+        else if (argument === '--once') {
+            once = true;
+        }
         else if (argument === '--no-browser') {
             process.env.TURNS_NO_BROWSER = '1';
         }
@@ -114,7 +120,24 @@ function parseGlobalArguments(argv) {
             remaining.push(argument);
         }
     }
-    return { argv: remaining, origin: origin || undefined, devUser, allowedDirectories };
+    return { argv: remaining, origin: origin || undefined, devUser, once, allowedDirectories };
+}
+/** A foreground run is the daemon scoped to one directory: it keeps watching,
+ * streams live rows, and serves queued prompts. The directory becomes the
+ * allowlist rather than an upload filter, so sessions in its subdirectories are
+ * followed too and launches arriving from the server cannot escape it. */
+export function scopedWatchOptions(directory, { once = false } = {}) {
+    const resolved = path.resolve(directory || process.cwd());
+    let allowedDirectories;
+    try {
+        allowedDirectories = normalizeAllowedDirectories([resolved]);
+    }
+    catch {
+        throw new Error(`Not a directory: ${resolved}`);
+    }
+    // `--once` keeps the same tree, so a single sweep covers subdirectories the
+    // way the watch does; it only stops the process from staying resident.
+    return { directory: resolved, watch: !once, allowedDirectories };
 }
 function credentialProvider(initial, { paths, interactive }) {
     let credentials = initial;
@@ -166,14 +189,18 @@ function credentialProvider(initial, { paths, interactive }) {
  * @param {object} credentials
  * @param {object} [options]
  * @param {import('./auth.ts').AuthPaths} [options.paths]
- * @param {string} [options.directory]
  * @param {boolean} [options.watch]
  * @param {boolean} [options.all]
  * @param {boolean} [options.interactive]
  * @param {string} [options.devUser]
  * @param {string[]} [options.allowedDirectories]
  */
-async function runUpload(credentials, { paths, directory = '', watch = false, all = false, interactive = true, devUser = '', allowedDirectories = [], } = {}) {
+async function runUpload(credentials, { paths, watch = false, all = false, interactive = true, devUser = '', allowedDirectories = [], } = {}) {
+    if (!all && !allowedDirectories.length) {
+        // Every caller either sweeps all directories or names the prefixes it may
+        // touch. An unscoped run would also accept launches anywhere on the machine.
+        throw new Error('runUpload requires either all directories or an explicit allowlist.');
+    }
     migrateLegacyUploaderState(paths);
     const provider = devUser ? null : credentialProvider(credentials, { paths, interactive });
     const { runUploader } = await import("./upload-sessions.js");
@@ -186,9 +213,9 @@ async function runUpload(credentials, { paths, directory = '', watch = false, al
         '--machine-id-file',
         paths.machineId,
         ...(devUser ? ['--dev-user', devUser] : []),
-        ...allowedDirectories.flatMap((directory) => ['--allow-directory', directory]),
+        ...allowedDirectories.flatMap((directory) => ['--directory', directory]),
         ...(watch ? ['--watch'] : []),
-        ...(all ? ['--all'] : allowedDirectories.length ? [] : ['--directory', path.resolve(directory || process.cwd())]),
+        ...(all ? ['--all'] : []),
     ];
     try {
         await runUploader(arguments_, { credentialProvider: provider });
@@ -242,6 +269,8 @@ async function main(rawArguments = process.argv.slice(2)) {
         if (argv[1] !== 'run')
             throw new Error(`Unknown daemon command: ${argv[1] || ''}\n\n${help()}`);
         const allowedDirectories = normalizeAllowedDirectories(parsed.allowedDirectories);
+        if (parsed.once)
+            throw new Error('--once cannot be combined with `turns daemon run`.');
         if (parsed.devUser && !parsed.origin)
             throw new Error('--dev-user requires an explicit --server URL.');
         let credentials;
@@ -266,24 +295,31 @@ async function main(rawArguments = process.argv.slice(2)) {
         return;
     }
     if (parsed.devUser || parsed.allowedDirectories.length) {
-        throw new Error('--dev-user and --allow-directory are supported only by `turns daemon run`.');
+        throw new Error('--dev-user and --directory are supported only by `turns daemon run`.');
     }
     if (command && command !== 'upload')
         throw new Error(`Unknown command: ${command}\n\n${help()}`);
     const runningDaemon = daemonStatus();
+    // Including `--once`: the daemon holds the same upload-cursor file, and a
+    // second writer would persist its own load-time copy over the daemon's
+    // concurrent progress. The daemon already keeps this directory current.
     if (runningDaemon.active) {
         process.stdout.write('The Turns daemon is already syncing this directory as part of the all-directory watch.\n');
         return;
     }
     await migrateLegacyCredentials(paths, parsed.origin);
     const credentials = await authenticate({ origin: parsed.origin, paths });
-    const selectedDirectory = path.resolve(command === 'upload' ? argv[1] || process.cwd() : process.cwd());
-    process.stdout.write(`${command === 'upload' ? 'Watching' : 'Uploading'} sessions in ${selectedDirectory} as @${credentials.user.login}.\n`);
+    const selected = scopedWatchOptions(command === 'upload' ? argv[1] || process.cwd() : process.cwd(), {
+        once: parsed.once,
+    });
+    process.stdout.write(selected.watch
+        ? `Watching sessions in ${selected.directory} as @${credentials.user.login}. Press Ctrl-C to stop.\n`
+        : `Uploading sessions in ${selected.directory} as @${credentials.user.login}.\n`);
     await runUpload(credentials, {
         paths,
-        directory: selectedDirectory,
-        watch: command === 'upload',
+        watch: selected.watch,
         interactive: true,
+        allowedDirectories: selected.allowedDirectories,
     });
 }
 export { credentialProvider, help, main, parseGlobalArguments, runUpload };

package/dist/local-session-sources.js

@@ -87,6 +87,10 @@ const EXTRA_FILE_STORES = {
         root: path.join(HOME, '.local', 'state', 'poolside', 'trajectories'),
         include: (file) => /^trajectory-[^/]+\.ndjson$/i.test(path.basename(file)),
     },
+    fx: {
+        root: path.join(HOME, '.fx', 'sessions'),
+        include: (file) => path.basename(file) === 'events.jsonl',
+    },
 };
 function safeStat(file) {
     try {
@@ -248,6 +252,7 @@ function nativeSessionIdFromPath(harness, sourcePath) {
         qwen: /\/chats\/([^/]+)\.jsonl$/iu,
         cline: /\/([^/]+)\.messages\.json$/iu,
         poolside: /trajectory-(?:standalone_)?([0-9a-f-]{20,})\.ndjson$/iu,
+        fx: /\/sessions\/([^/]+)\/events\.jsonl$/iu,
     };
     return patterns[harness]?.exec(normalized)?.[1] || '';
 }
@@ -269,6 +274,28 @@ function fileDescriptor(harness, file) {
         createdAt: (stat.birthtimeMs > 0 ? stat.birthtime : stat.mtime).toISOString(),
     };
 }
+/** Fx's ledger path identifies the session; its adjacent projections provide
+ * the workspace and display title without requiring a conversation scan. */
+function fxDescriptor(file) {
+    const descriptor = fileDescriptor('fx', file);
+    if (!descriptor)
+        return null;
+    const directory = path.dirname(file);
+    const session = jsonFile(path.join(directory, 'session.json'));
+    const display = jsonFile(path.join(directory, 'display.json'));
+    const createdAtMs = Number(session?.created_at_ms);
+    const createdAt = Number.isFinite(createdAtMs) ? new Date(createdAtMs).toISOString() : descriptor.createdAt;
+    const title = typeof display?.title === 'string' ? display.title.trim() : '';
+    return {
+        ...descriptor,
+        createdAt,
+        nativeSessionId: String(session?.id || path.basename(directory)).trim(),
+        ...(absolutePathCandidate([session?.workspace_root, session?.origin_workspace_root])
+            ? { workingDirectory: absolutePathCandidate([session?.workspace_root, session?.origin_workspace_root]) }
+            : {}),
+        ...(title ? { nativeTitle: title } : {}),
+    };
+}
 /** Discover top-level and subagent DeepSeek trajectories with header metadata. */
 export function deepseekTrajectoryDescriptors(root = DEEPSEEK_SESSIONS_ROOT) {
     const descriptors = [];
@@ -1070,6 +1097,10 @@ export function nativeDescriptorWorkingDirectory(descriptor) {
         cursor: cursorMetadataWorkingDirectory,
         gemini: geminiMetadataWorkingDirectory,
         kimi: kimiMetadataWorkingDirectory,
+        fx: (candidate) => absolutePathCandidate([
+            sidecarJson(candidate, 'session.json')?.workspace_root,
+            sidecarJson(candidate, 'session.json')?.origin_workspace_root,
+        ]),
     };
     const metadataCandidate = metadataResolvers[descriptor.harness]?.(descriptor) || '';
     if (metadataCandidate)
@@ -1287,6 +1318,7 @@ const HARNESS_PROCESS_NAMES = {
     prime: ['prime', 'prime-agent'],
     qwen: ['qwen'],
     vibe: ['vibe', 'vibe-acp'],
+    fx: ['fx'],
 };
 const SCRIPT_RUNTIMES = new Set(['node', 'nodejs', 'bun', 'deno', 'python', 'python3']);
 function executableStem(value) {
@@ -1392,7 +1424,7 @@ function discoverLocalSessionInventory(only = '') {
         walk(store.root, (file) => {
             if (!store.include(file))
                 return;
-            const descriptor = fileDescriptor(harness, file);
+            const descriptor = harness === 'fx' ? fxDescriptor(file) : fileDescriptor(harness, file);
             if (descriptor)
                 descriptors.push(descriptor);
         });

package/dist/path-resolution.js

@@ -173,7 +173,7 @@ function uploadHeaders(options) {
  * addressed by machine and path alone — the session that happened to prompt the
  * upload is not part of what was stored, and nothing records it.
  */
-export async function uploadFileBytes({ baseUrl, options, machine, absolutePath, contentType, body, fetchImpl = fetch, }) {
+export async function uploadFileBytes({ baseUrl, options, machine, absolutePath, contentType, contentEtag, body, fetchImpl = fetch, }) {
     const url = new URL(`/api/file/${encodeURIComponent(machine)}/${encodeURIComponent(absolutePath)}`, String(baseUrl));
     const response = await fetchImpl(url, {
         method: 'PUT',
@@ -181,6 +181,7 @@ export async function uploadFileBytes({ baseUrl, options, machine, absolutePath,
             ...uploadHeaders(options),
             'content-type': contentType,
             'content-length': String(body.byteLength),
+            ...(contentEtag ? { 'x-turns-content-etag': contentEtag } : {}),
         },
         body,
     });

package/dist/queue-worker.js

@@ -952,22 +952,24 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
         return recorded || path.dirname(descriptor.file);
     };
     /**
-     * Store one path this machine holds, so a reader can open it.
+     * Read one path this machine holds, so a reader can open it.
      *
      * Unlike the rest of these handlers this touches no harness: browsing is a
      * property of the machine, so it answers for a stopped session as readily as
-     * for a running one.
+     * for a running one. Directory bytes answer directly; their offline copy is
+     * stored behind that reply.
      */
     const handleFileBrowse = async (message, replyRpc) => {
         const sessionId = String(message.sessionId || '');
         try {
-            const stored = await browseMachinePath({
+            const browsed = await browseMachinePath({
                 requested: String(message.path || ''),
                 machine,
                 baseUrl,
                 options,
                 workingDirectory: await browseWorkingDirectory(sessionId),
             });
+            const { cache, ...stored } = browsed.kind === 'directory' ? browsed : { ...browsed, cache: undefined };
             replyRpc.notify({
                 type: 'session.file.browse.result',
                 requestId: message.requestId,
@@ -975,6 +977,11 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
                 ok: true,
                 ...stored,
             });
+            // The direct listing is already useful. Its R2 copy is only the fallback
+            // for a later offline browse, so storage latency must not hold this reply.
+            void cache?.catch((error) => {
+                console.warn(`Directory browse fallback upload failed: ${redactor.redactText(error?.message || String(error))}`);
+            });
         }
         catch (error) {
             replyRpc.notify({

package/dist/upload-sessions.js

@@ -53,6 +53,7 @@ const TIME_FIELDS = [
     'time_created',
     'recorded_at',
     'occurred_at_ms',
+    'timestamp_ms',
 ];
 const TIME_CONTAINERS = ['data', 'payload', 'message', 'chat_message', 'node'];
 function epochToIso(value) {
@@ -149,7 +150,7 @@ function argumentsFrom(argv, { allowMissingToken = false } = {}) {
         rewriteSession: '',
         nativeStateFile: process.env.TURNS_NATIVE_STATE_FILE || path.join(HERE, '.native-upload-state.json'),
         machineIdFile: process.env.TURNS_MACHINE_ID_FILE || path.join(HERE, '.machine-id'),
-        directory: '',
+        onlyDirectory: '',
         all: false,
         devUser: '',
         allowedDirectories: [],
@@ -180,13 +181,13 @@ function argumentsFrom(argv, { allowMissingToken = false } = {}) {
             options.nativeStateFile = path.resolve(next());
         else if (argument === '--machine-id-file')
             options.machineIdFile = path.resolve(next());
-        else if (argument === '--directory')
-            options.directory = path.resolve(next());
+        else if (argument === '--only-directory')
+            options.onlyDirectory = path.resolve(next());
         else if (argument === '--all')
             options.all = true;
         else if (argument === '--dev-user')
             options.devUser = next().trim().toLowerCase();
-        else if (argument === '--allow-directory')
+        else if (argument === '--directory')
             options.allowedDirectories.push(next());
         else if (argument === '--watch')
             options.watch = true;
@@ -198,9 +199,9 @@ function argumentsFrom(argv, { allowMissingToken = false } = {}) {
                 `  --dry-run            inventory native sessions without uploading\n` +
                 `  --runs PATH          capture root (default: ${DEFAULT_RUNS})\n` +
                 `  --only TEXT          upload paths containing TEXT\n` +
-                `  --directory PATH     upload sessions whose working directory is PATH\n` +
+                `  --directory PATH     upload/launch only inside directory prefix PATH (repeatable)\n` +
+                `  --only-directory PATH upload only sessions whose working directory is exactly PATH\n` +
                 `  --all                upload sessions across all working directories\n` +
-                `  --allow-directory P  upload/launch only inside directory prefix P (repeatable)\n` +
                 `  --dev-user LOGIN     authenticate as a local Wrangler DEV_USER uploader\n` +
                 `  --url WS_URL         websocket endpoint\n` +
                 `  --token TOKEN        internal/test bearer token override\n` +
@@ -214,10 +215,10 @@ function argumentsFrom(argv, { allowMissingToken = false } = {}) {
     if (options.rewriteSession && !options.native) {
         throw new Error('--rewrite-session requires --native.');
     }
-    if (options.directory && options.all)
-        throw new Error('--directory cannot be combined with --all.');
-    if (options.allowedDirectories.length && (options.directory || options.all)) {
-        throw new Error('--allow-directory cannot be combined with --directory or --all.');
+    if (options.onlyDirectory && options.all)
+        throw new Error('--only-directory cannot be combined with --all.');
+    if (options.allowedDirectories.length && (options.onlyDirectory || options.all)) {
+        throw new Error('--directory cannot be combined with --only-directory or --all.');
     }
     options.allowedDirectories = normalizeAllowedDirectories(options.allowedDirectories);
     if (!options.dryRun && !options.token && !options.devUser && !allowMissingToken) {
@@ -845,9 +846,11 @@ async function uploadFile(rpc, machine, root, capture, redactor = DEFAULT_REDACT
     if (opened.type === 'session_tombstoned')
         return { rows: 0, sent: 0, skipped: true, tombstoned: true };
     let nextRow = Number(opened.nextRow) || 0;
+    let initialUpload = nextRow === 0;
     if (Number(opened.redactionVersion || 0) !== REDACTION_VERSION) {
         await rpc.request({ type: 'session.reset', sessionId, redactionVersion: REDACTION_VERSION });
         nextRow = 0;
+        initialUpload = true;
     }
     if (nextRow > rows.length)
         throw new Error(`${capture.relative}: remote has ${nextRow} rows, local file has ${rows.length}`);
@@ -857,7 +860,12 @@ async function uploadFile(rpc, machine, root, capture, redactor = DEFAULT_REDACT
     for (const batch of batches(rows, raw, nextRow, redactor)) {
         let acknowledgement;
         try {
-            acknowledgement = await rpc.request({ type: 'ingest', sessionId, ...batch });
+            acknowledgement = await rpc.request({
+                type: 'ingest',
+                sessionId,
+                ...batch,
+                ...(initialUpload ? { deferReduction: true } : {}),
+            });
         }
         catch (error) {
             const offset = /^ROW_OFFSET:(\d+)$/u.exec(String(error.code || ''));
@@ -946,12 +954,16 @@ 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) {
         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;
     }
+    if (initialUpload)
+        cursor.initialUpload = true;
     const resumable = canResumeNativeCursor(descriptor, cursor, nextRow);
     const scanCursor = resumable
         ? { offset: Number(cursor.offset), rowCount: Number(cursor.rowCount), lineNumber: Number(cursor.lineNumber) || 0 }
@@ -981,6 +993,7 @@ export async function uploadNativeSession(rpc, machine, descriptor, cursor = {},
             sessionId: uploadSessionId,
             startRow: rows[0].index,
             rows,
+            ...(initialUpload ? { deferReduction: true } : {}),
         });
         nextRow = Number(acknowledgement.nextRow);
         sent += rows.length;
@@ -1072,8 +1085,10 @@ export async function uploadNativeSession(rpc, machine, descriptor, cursor = {},
         });
     }
     if (!sawRows && scanCursor.rowCount === 0) {
+        delete cursor.initialUpload;
         return { rows: 0, sent: 0, skipped: true, empty: true };
     }
+    delete cursor.initialUpload;
     return { rows: scanCursor.rowCount, sent, skipped: sent === 0 };
 }
 export function nativeFailureRetryDelay(attempts) {
@@ -1245,7 +1260,7 @@ export function watchNativeSessionDirectories({ roots, shallowRoots = [], files
     };
 }
 const nativeWorkingDirectoryCache = new Map();
-export async function filterNativeSessionsByDirectory(sessions, directory, resolveWorkingDirectory = nativeDescriptorWorkingDirectory) {
+export async function filterNativeSessionsByOnlyDirectory(sessions, directory, resolveWorkingDirectory = nativeDescriptorWorkingDirectory) {
     if (!directory)
         return sessions;
     const selected = path.resolve(directory);
@@ -1263,7 +1278,7 @@ export async function filterNativeSessionsByDirectory(sessions, directory, resol
     }
     return scoped;
 }
-export async function filterNativeSessionsByAllowedDirectories(sessions, allowedDirectories, resolveWorkingDirectory = nativeDescriptorWorkingDirectory) {
+export async function filterNativeSessionsByDirectories(sessions, allowedDirectories, resolveWorkingDirectory = nativeDescriptorWorkingDirectory) {
     if (!allowedDirectories?.length)
         return sessions;
     const scoped = [];
@@ -1280,10 +1295,18 @@ export async function filterNativeSessionsByAllowedDirectories(sessions, allowed
     }
     return scoped;
 }
+/** Whether this run's inventory speaks for the whole machine. A run narrowed by
+ * `--only`, `--rewrite-session`, `--only-directory`, or `--directory` sees a
+ * subset, so it must not prune upload cursors for the sessions it filtered out:
+ * the next unscoped run would find no cursor and replay those transcripts from
+ * their first byte. */
+export function inventoryIsAuthoritative(options) {
+    return !(options.only || options.rewriteSession || options.onlyDirectory || options.allowedDirectories?.length);
+}
 async function nativeInventory(options, machine) {
     let sessions = linkNativeSessionParents(machine, discoverLocalSessions(options.rewriteSession ? '' : options.only));
-    sessions = await filterNativeSessionsByDirectory(sessions, options.directory);
-    sessions = await filterNativeSessionsByAllowedDirectories(sessions, options.allowedDirectories);
+    sessions = await filterNativeSessionsByOnlyDirectory(sessions, options.onlyDirectory);
+    sessions = await filterNativeSessionsByDirectories(sessions, options.allowedDirectories);
     if (!options.rewriteSession)
         return sessions;
     const exact = sessions.filter((descriptor) => stableNativeSessionId(machine, descriptor.harness, descriptor.sourcePath) === options.rewriteSession);
@@ -1399,6 +1422,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
     const livePriority = new Set();
     const tombstoned = new Set();
     let nativeMonitor = null;
+    const authoritativeInventory = inventoryIsAuthoritative(options);
     const rememberInventory = (sessions, retainState = false, forceMetadataDirectories = new Set()) => {
         const previousFingerprints = new Map(fingerprints);
         descriptorBySession.clear();
@@ -1459,7 +1483,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
                 redactionStarted.add(sessionId);
             }
         }
-        if (retainState && !options.only && !options.rewriteSession)
+        if (retainState && authoritativeInventory)
             state.retain(descriptorBySession.keys());
         descriptorRegistry.sessions = sessions;
         nativeMonitor?.addFiles(sessions.map((descriptor) => descriptor.file));
@@ -1725,7 +1749,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
                 rememberInventory(sessions);
                 const unsettled = changedSessions();
                 if (unsettled.length) {
-                    process.stderr.write(`${unsettled.length} native sessions kept changing; use --watch to follow them continuously.\n`);
+                    process.stderr.write(`${unsettled.length} native sessions kept changing; run \`turns\` without --once to follow them continuously.\n`);
                 }
                 break;
             }

package/package.json

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