@turns/dev 0.0.25 → 0.0.27

package/dist/local-session-sources.js

@@ -294,6 +294,36 @@ function fileDescriptor(harness, file) {
         createdAt: (stat.birthtimeMs > 0 ? stat.birthtime : stat.mtime).toISOString(),
     };
 }
+/** Resolve only ordinary transcript files from their authoritative store.
+ * Database projections require discovery; never interpret their source IDs as
+ * paths or allow a server-provided path outside the selected harness store. */
+export function nativeDescriptorForSource(harness, sourcePath) {
+    const store = Object.hasOwn(EXTRA_FILE_STORES, harness) ? EXTRA_FILE_STORES[harness] : null;
+    if (!store || !sourcePath || sourcePath.includes('\0'))
+        return null;
+    const file = sourcePath.startsWith('~/') ? path.join(HOME, sourcePath.slice(2)) : sourcePath;
+    if (!path.isAbsolute(file))
+        return null;
+    const relative = path.relative(store.root, file);
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    if (!store.include(file))
+        return null;
+    // Discovery does not traverse symlinked entries. Keep this direct lookup
+    // from admitting a transcript that an inventory walk would never discover.
+    try {
+        let candidate = store.root;
+        for (const part of relative.split(path.sep)) {
+            candidate = path.join(candidate, part);
+            if (fs.lstatSync(candidate).isSymbolicLink())
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return harness === 'fx' ? fxDescriptor(file) : fileDescriptor(harness, file);
+}
 /** Fx's ledger path identifies the session; its adjacent projections provide
  * the workspace and display title without requiring a conversation scan. */
 function fxDescriptor(file) {
@@ -934,6 +964,45 @@ function firstRecords(descriptor, limit = 32, maxBytes = 1024 * 1024) {
         return [];
     }
 }
+/** Claude copies a backgrounded session into a new transcript and ends the
+ * old one with `{"type":"continued-in","continuedInSessionId":...}`, followed
+ * only by small bookkeeping rows. Read just the file's tail for that marker. */
+function claudeContinuedInSessionId(file) {
+    let handle;
+    try {
+        const stat = fs.statSync(file);
+        const bytesToRead = Math.min(stat.size, 16 * 1024);
+        handle = fs.openSync(file, 'r');
+        const buffer = Buffer.alloc(bytesToRead);
+        const bytesRead = fs.readSync(handle, buffer, 0, buffer.length, stat.size - bytesToRead);
+        const text = buffer.subarray(0, bytesRead).toString('utf8');
+        if (!text.includes('"continued-in"'))
+            return '';
+        let continuedIn = '';
+        for (const line of text.split('\n')) {
+            if (!line.includes('"continued-in"'))
+                continue;
+            try {
+                const record = jsonObject(JSON.parse(line));
+                const id = String(record?.continuedInSessionId || '').trim();
+                if (record?.type === 'continued-in' && /^[0-9a-f-]{8,64}$/iu.test(id))
+                    continuedIn = id;
+            }
+            catch { }
+        }
+        return continuedIn;
+    }
+    catch {
+        return '';
+    }
+    finally {
+        try {
+            if (handle !== undefined)
+                fs.closeSync(handle);
+        }
+        catch { }
+    }
+}
 /** Native identity and parentage carried by a bounded transcript prefix. */
 export function nativeDescriptorLineage(descriptor) {
     const sourcePath = String(descriptor?.sourcePath || descriptor?.file || '').replaceAll('\\', '/');
@@ -1012,10 +1081,14 @@ export function nativeDescriptorLineage(descriptor) {
     }
     if (parentNativeSessionId)
         isSubagent = true;
+    const continuedInNativeSessionId = descriptor?.harness === 'claude' && !isSubagent && descriptor?.file
+        ? claudeContinuedInSessionId(String(descriptor.file))
+        : '';
     const value = {
         nativeSessionId,
         parentNativeSessionId,
         isSubagent,
+        ...(continuedInNativeSessionId ? { continuedInNativeSessionId } : {}),
         ...(structural?.uploadable === false ? { uploadable: false } : {}),
         ...(parentSourcePath ? { parentSourcePath } : {}),
         ...(claudeMetadata?.description ? { nativeTitle: claudeMetadata.description } : {}),

package/dist/native-inventory-worker.js

@@ -0,0 +1,58 @@
+import { isMainThread, parentPort, Worker, workerData } from 'node:worker_threads';
+import { discoverLocalSessions } from "./local-session-sources.js";
+// Keep the synchronous store scans and their caches off the control socket's
+// event loop. One worker serves all scans, including periodic rediscovery.
+if (!isMainThread && workerData === 'turns-native-inventory') {
+    parentPort.on('message', ({ id, only }) => {
+        try {
+            parentPort.postMessage({ id, sessions: discoverLocalSessions(only) });
+        }
+        catch (error) {
+            parentPort.postMessage({ id, error: String(error?.stack || error) });
+        }
+    });
+}
+export class NativeInventoryWorker {
+    worker;
+    nextId = 0;
+    pending = new Map();
+    failure = null;
+    constructor(entry = new URL(import.meta.url)) {
+        this.worker = new Worker(entry, { workerData: 'turns-native-inventory' });
+        this.worker.on('message', ({ id, sessions, error }) => {
+            const request = this.pending.get(id);
+            if (!request)
+                return;
+            this.pending.delete(id);
+            if (error)
+                request.reject(new Error(error));
+            else
+                request.resolve(sessions);
+            if (!this.pending.size)
+                this.worker.unref();
+        });
+        this.worker.on('error', (error) => this.fail(error));
+        this.worker.on('exit', (code) => this.fail(new Error(`Native inventory worker exited (${code}).`)));
+        this.worker.unref();
+    }
+    fail(error) {
+        this.failure = error;
+        for (const request of this.pending.values())
+            request.reject(error);
+        this.pending.clear();
+    }
+    scan(only = '') {
+        if (this.failure)
+            return Promise.reject(this.failure);
+        const id = ++this.nextId;
+        this.worker.ref();
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.worker.postMessage({ id, only });
+        });
+    }
+    close() {
+        this.fail(new Error('Native inventory stopped.'));
+        return this.worker.terminate();
+    }
+}

package/dist/queue-lifecycle.js

@@ -0,0 +1,66 @@
+export const QUEUE_RESTART_MESSAGE = 'The local daemon restarted before your message was sent. Retrying automatically.';
+/** The synchronous stopping/dispatch gates serialize shutdown against local
+ * delivery. Once delivery is uncertain, only anchor recovery may reconcile it. */
+export class QueueDispatchLifecycle {
+    stopping = false;
+    acquiring = new Set();
+    handoffs = new Set();
+    claims = new Map();
+    stopped = null;
+    assertRunning() {
+        if (this.stopping)
+            throw new Error('The local daemon is restarting.');
+    }
+    async acquire(request, release) {
+        this.assertRunning();
+        const pending = request().then((response) => {
+            if (response.claim)
+                this.claims.set(response.claim, { started: false, release: () => release(response.claim) });
+            return response;
+        });
+        this.acquiring.add(pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.acquiring.delete(pending);
+        }
+    }
+    async dispatch(claim, send) {
+        this.assertRunning();
+        const held = this.claims.get(claim);
+        if (!held)
+            throw new Error('Queue dispatch has no tracked claim.');
+        held.started = true;
+        const pending = send();
+        this.handoffs.add(pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.handoffs.delete(pending);
+        }
+    }
+    forget(claim) {
+        this.claims.delete(claim);
+    }
+    stop() {
+        if (this.stopped)
+            return this.stopped;
+        this.stopping = true;
+        this.stopped = (async () => {
+            // A claim response can arrive after SIGTERM. Include it before releasing
+            // unsent work; new acquire/dispatch calls are already blocked above.
+            const releaseUnsent = () => [...this.claims.values()]
+                .filter((claim) => !claim.started)
+                .map((claim) => {
+                claim.releasing ||= Promise.resolve().then(claim.release);
+                return claim.releasing;
+            });
+            // Do not let one stalled claim response delay release of known claims.
+            await Promise.allSettled([...releaseUnsent(), ...this.acquiring]);
+            await Promise.allSettled([...releaseUnsent(), ...this.handoffs]);
+        })();
+        return this.stopped;
+    }
+}

package/dist/queue-worker.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { logError } from "./logging.js";
+import { QueueDispatchLifecycle, QUEUE_RESTART_MESSAGE } from "./queue-lifecycle.js";
 import { anchorId, connectExistingAgentAnchors, launchAgentAnchor, waitForAgentTurn } from "./agent-anchor-client.js";
 import { createCodexUpdateManager } from "./codex-update.js";
 import { isAsyncQuestionId } from "./codex-async-question-recovery.js";
@@ -352,7 +353,7 @@ export async function actualHarnessStatus(entry) {
     entry.snapshot = snapshot;
     return snapshot.status === 'running' ? 'running' : 'idle';
 }
-export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors, stableSessionId, redactor = DEFAULT_REDACTOR, }) {
+export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors, resolveDescriptor = async (_session) => null, descriptorsReady = Promise.resolve(), lifecycle = new QueueDispatchLifecycle(), stableSessionId, redactor = DEFAULT_REDACTOR, }) {
     const workerId = `${machine}:turns-queue-worker`;
     const workerInstanceId = crypto.randomUUID();
     const baseUrl = httpBaseUrl(options.url);
@@ -628,6 +629,8 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
     const runClaim = async (sessionId, claim, recovery = null) => {
         if (claims.has(sessionId))
             return;
+        if (!recovery)
+            lifecycle.assertRunning();
         // Publish the optimistic user turn before native-session lookup, attachment
         // download, or a cold anchor launch. The stable event key makes recovery
         // idempotent, and the outbound protocol frame will replace this placeholder.
@@ -640,9 +643,71 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
         let creating = false;
         let cwd = '';
         let entry = recovery?.entry;
+        const queued = {
+            ...claim,
+            entry,
+            renewTimer: null,
+            // Recovery only observes turns that an anchor already accepted. Treat
+            // an uncertain recovery failure conservatively for the same reason as a
+            // failed live turn: the prompt may already have produced side effects.
+            promptStarted: Boolean(recovery),
+        };
+        claims.set(sessionId, queued);
+        const renewClaim = () => request({
+            type: 'queue.renew',
+            sessionId,
+            promptId: claim.prompt.id,
+            claimToken: claim.claimToken,
+        });
+        const beginRenewal = () => {
+            if (queued.renewTimer)
+                return;
+            queued.renewTimer = setInterval(() => {
+                if (lifecycle.stopping) {
+                    stopClaimRenewal(queued);
+                    return;
+                }
+                if (entry?.connection.closed) {
+                    stopClaimRenewal(queued);
+                    void reportHarness(sessionId, 'stopped', entry).catch(() => { });
+                    return;
+                }
+                void renewClaim().catch((error) => logError(`Queue lease renewal failed: ${error?.message || error}\n`));
+                // Never renew lifecycle state from an old in-memory snapshot. The
+                // anchor may have disconnected since the claim began, which would
+                // otherwise resurrect a canonical stopped edge as running.
+                if (!entry)
+                    return;
+                void reportActualHarness(sessionId, entry).catch(async () => {
+                    if (lifecycle.stopping) {
+                        stopClaimRenewal(queued);
+                        return;
+                    }
+                    if (entry.connection.closed) {
+                        stopClaimRenewal(queued);
+                        await reportHarness(sessionId, 'stopped', entry).catch(() => { });
+                    }
+                });
+            }, CLAIM_RENEW_MS);
+            queued.renewTimer.unref?.();
+        };
+        beginRenewal();
+        // Verify and extend the inherited lease before waiting on a recovered
+        // anchor. If the server has already replaced it, normal claiming plus the
+        // anchor's prompt idempotency will reconcile the surviving turn instead.
+        if (recovery)
+            await renewClaim();
         if (!recovery) {
-            const descriptorMap = descriptors();
-            let discovered = descriptorMap.get(sessionId);
+            let descriptorMap = descriptors();
+            let discovered = descriptorMap.get(sessionId) || (await resolveDescriptor(claim.session));
+            if (!discovered && claim.session?.sourcePath) {
+                await descriptorsReady;
+                lifecycle.assertRunning();
+                descriptorMap = descriptors();
+                discovered =
+                    descriptorMap.get(sessionId) ||
+                        [...descriptorMap.values()].find((candidate) => candidate.harness === claim.session.harness && candidate.sourcePath === claim.session.sourcePath);
+            }
             const claimedAgentSessionId = String(claim.session?.agentSessionId || '');
             if (!discovered && claimedAgentSessionId) {
                 for (const candidate of descriptorMap.values()) {
@@ -689,54 +754,12 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             // Codex installation leaves a recoverable unsent prompt in the queue.
             if (descriptor.harness === 'codex')
                 resolveHarnessCommand('codex');
+            lifecycle.assertRunning();
             entry = await usableAnchor(sessionId, descriptor.harness, agentSessionId, Boolean(claim.session?.modelSettings));
         }
         if (!entry)
             throw new Error(`No surviving agent anchor exists for ${sessionId}.`);
-        const queued = {
-            ...claim,
-            entry,
-            renewTimer: null,
-            // Recovery only observes turns that an anchor already accepted. Treat
-            // an uncertain recovery failure conservatively for the same reason as a
-            // failed live turn: the prompt may already have produced side effects.
-            promptStarted: Boolean(recovery),
-        };
-        claims.set(sessionId, queued);
-        const renewClaim = () => request({
-            type: 'queue.renew',
-            sessionId,
-            promptId: claim.prompt.id,
-            claimToken: claim.claimToken,
-        });
-        const beginRenewal = () => {
-            if (queued.renewTimer)
-                return;
-            queued.renewTimer = setInterval(() => {
-                if (entry.connection.closed) {
-                    stopClaimRenewal(queued);
-                    void reportHarness(sessionId, 'stopped', entry).catch(() => { });
-                    return;
-                }
-                void renewClaim().catch((error) => logError(`Queue lease renewal failed: ${error?.message || error}\n`));
-                // Never renew lifecycle state from an old in-memory snapshot. The
-                // anchor may have disconnected since the claim began, which would
-                // otherwise resurrect a canonical stopped edge as running.
-                void reportActualHarness(sessionId, entry).catch(async () => {
-                    if (entry.connection.closed) {
-                        stopClaimRenewal(queued);
-                        await reportHarness(sessionId, 'stopped', entry).catch(() => { });
-                    }
-                });
-            }, CLAIM_RENEW_MS);
-            queued.renewTimer.unref?.();
-        };
-        beginRenewal();
-        // Verify and extend the inherited lease before waiting on a recovered
-        // anchor. If the server has already replaced it, normal claiming plus the
-        // anchor's prompt idempotency will reconcile the surviving turn instead.
-        if (recovery)
-            await renewClaim();
+        queued.entry = entry;
         const prompt = recovery?.prompt ||
             (await preparePrompt({
                 prompt: claim.prompt,
@@ -761,33 +784,35 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             const eventCursor = entry.connection.eventCursor();
             // Persist before local delivery: either acknowledgement can be lost
             // after acceptance. Uncertain delivery must never trigger automatic replay.
-            queued.promptStarted = true;
-            await request({
-                type: 'queue.renew',
-                sessionId,
-                promptId: claim.prompt.id,
-                claimToken: claim.claimToken,
-                dispatchStarted: true,
+            await lifecycle.dispatch(claim, async () => {
+                queued.promptStarted = true;
+                await request({
+                    type: 'queue.renew',
+                    sessionId,
+                    promptId: claim.prompt.id,
+                    claimToken: claim.claimToken,
+                    dispatchStarted: true,
+                });
+                await entry.connection.request('send_message', {
+                    source: descriptor.harness,
+                    sessionId,
+                    agentSessionId,
+                    cwd,
+                    transcriptPath: descriptor.file,
+                    workerId,
+                    messageId: claim.prompt.id,
+                    claimToken: claim.claimToken,
+                    prompt,
+                    expectedText: claim.prompt.text,
+                    createSession: creating,
+                    permissionMode: String(claim.session?.permissionMode || 'bypassPermissions'),
+                    model: String(claim.session?.model || ''),
+                    thinkingLevel: String(claim.session?.modelEffort || ''),
+                    codexHistoryMode: String(claim.session?.codexHistoryMode || ''),
+                    timeoutMs: QUEUE_TURN_TIMEOUT_MS,
+                    idleTimeoutMs: QUEUE_WARM_MS,
+                }, 30_000);
             });
-            await entry.connection.request('send_message', {
-                source: descriptor.harness,
-                sessionId,
-                agentSessionId,
-                cwd,
-                transcriptPath: descriptor.file,
-                workerId,
-                messageId: claim.prompt.id,
-                claimToken: claim.claimToken,
-                prompt,
-                expectedText: claim.prompt.text,
-                createSession: creating,
-                permissionMode: String(claim.session?.permissionMode || 'bypassPermissions'),
-                model: String(claim.session?.model || ''),
-                thinkingLevel: String(claim.session?.modelEffort || ''),
-                codexHistoryMode: String(claim.session?.codexHistoryMode || ''),
-                timeoutMs: QUEUE_TURN_TIMEOUT_MS,
-                idleTimeoutMs: QUEUE_WARM_MS,
-            }, 30_000);
             entry.snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => entry.snapshot);
             // Registration after acceptance is safe: the connection retains recent
             // events and the snapshot carries a turn that completed immediately.
@@ -804,12 +829,19 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
         await finishClaim(sessionId, queued, entry, result);
     };
     const tryClaim = async (sessionId) => {
-        if (claims.has(sessionId) || claimStarts.has(sessionId))
+        if (lifecycle.stopping || claims.has(sessionId) || claimStarts.has(sessionId))
             return;
         claimStarts.add(sessionId);
         let claim;
         try {
-            const response = await request({ type: 'queue.claim', sessionId, dispatchTracking: true });
+            const response = await lifecycle.acquire(() => request({ type: 'queue.claim', sessionId, dispatchTracking: true }), (held) => request({
+                type: 'queue.fail',
+                sessionId,
+                promptId: held.prompt.id,
+                claimToken: held.claimToken,
+                error: QUEUE_RESTART_MESSAGE,
+                retryable: true,
+            }, 2_000));
             claim = response.claim;
             if (!claim)
                 return;
@@ -833,7 +865,7 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             else if (held?.entry) {
                 await reportHarness(sessionId, 'stopped', held.entry).catch(() => { });
             }
-            if (claim) {
+            if (claim && !lifecycle.stopping) {
                 await request({
                     type: 'queue.fail',
                     sessionId,
@@ -846,6 +878,8 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             claims.delete(sessionId);
         }
         finally {
+            if (claim && !lifecycle.stopping)
+                lifecycle.forget(claim);
             claimStarts.delete(sessionId);
         }
     };
@@ -1359,6 +1393,8 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
         return fileEditChain;
     };
     const heartbeat = setInterval(() => {
+        if (lifecycle.stopping)
+            return;
         for (const [sessionId, entry] of anchors) {
             if (entry.connection.closed)
                 continue;
@@ -1367,6 +1403,8 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
     }, HARNESS_HEARTBEAT_MS);
     heartbeat.unref?.();
     rpc.onEvent((message) => {
+        if (lifecycle.stopping)
+            return;
         if (message.type === 'queue.ready')
             void tryClaim(message.sessionId);
         if (message.type === 'session.steer')
@@ -1395,7 +1433,7 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
     const registered = new WeakSet();
     const registering = new WeakSet();
     const registerControl = async (control) => {
-        if (registered.has(control) || registering.has(control))
+        if (lifecycle.stopping || registered.has(control) || registering.has(control))
             return;
         registering.add(control);
         try {
@@ -1431,8 +1469,10 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
         void registerControl(control);
     });
     await registerControl(await rpc.current());
-    for (;;) {
+    while (!lifecycle.stopping) {
         await backgroundWait(MACHINE_HEARTBEAT_MS);
+        if (lifecycle.stopping)
+            break;
         try {
             await registerControl(await rpc.current());
             const status = await request({ type: 'machine.heartbeat' }, MACHINE_HEARTBEAT_TIMEOUT_MS);

package/dist/upload-sessions.js

@@ -7,10 +7,12 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import WebSocket from 'ws';
 import { logError, logInfo } from "./logging.js";
+import { NativeInventoryWorker } from "./native-inventory-worker.js";
+import { QueueDispatchLifecycle } from "./queue-lifecycle.js";
 import { streamDeepseekTrajectoryLines } from "./deepseek-trajectories.js";
 import { normalizeAllowedDirectories, workingDirectoryIsAllowed } from "./directory-policy.js";
 import { discoverGitAssociation } from "./git-association.js";
-import { discoverLocalSessions, externallyManagedNativeDescriptorKeys, grokSpawnedSubagentIds, nativeDescriptorAgentSessionId, nativeDescriptorLineage, nativeDescriptorWorkingDirectory, nativeSessionShallowWatchRoots, nativeSessionWatchRoots, } from "./local-session-sources.js";
+import { discoverLocalSessions, externallyManagedNativeDescriptorKeys, grokSpawnedSubagentIds, nativeDescriptorAgentSessionId, nativeDescriptorForSource, nativeDescriptorLineage, nativeDescriptorWorkingDirectory, nativeSessionShallowWatchRoots, nativeSessionWatchRoots, } from "./local-session-sources.js";
 import { compactNativeRaw } from "./native-record-compaction.js";
 import { createPathResolver, pathCandidates } from "./path-resolution.js";
 import { httpBaseUrl, watchQueuedPrompts } from "./queue-worker.js";
@@ -315,6 +317,19 @@ export function linkNativeSessionParents(machine, descriptors) {
         candidates.push(record.descriptor);
         byNativeId.set(key, candidates);
     }
+    // A continued transcript names its successor; key it by the successor's
+    // store directory so equal native IDs in other projects never match.
+    const nativeDirectory = (descriptor) => path.posix.dirname(String(descriptor?.sourcePath || '').replaceAll('\\', '/'));
+    const predecessorsBySuccessor = new Map();
+    for (const record of records) {
+        const successorId = record.lineage.continuedInNativeSessionId;
+        if (!successorId || successorId === record.lineage.nativeSessionId)
+            continue;
+        const key = `${record.descriptor.harness}\0${nativeDirectory(record.descriptor)}\0${successorId}`;
+        const candidates = predecessorsBySuccessor.get(key) || [];
+        candidates.push(record.descriptor);
+        predecessorsBySuccessor.set(key, candidates);
+    }
     const grokParentsByChildId = new Map();
     for (const record of records) {
         if (record.descriptor.harness !== 'grok')
@@ -365,6 +380,10 @@ export function linkNativeSessionParents(machine, descriptors) {
         // native upload until its store exposes enough lineage to nest it safely.
         if (isSubagent && !parentSourcePath)
             return [];
+        const predecessors = !isSubagent && lineage.nativeSessionId
+            ? predecessorsBySuccessor.get(`${descriptor.harness}\0${nativeDirectory(descriptor)}\0${lineage.nativeSessionId}`) || []
+            : [];
+        const predecessor = predecessors.length === 1 ? predecessors[0] : null;
         return [
             {
                 ...descriptor,
@@ -377,6 +396,9 @@ export function linkNativeSessionParents(machine, descriptors) {
                         parentSessionId: stableNativeSessionId(machine, descriptor.harness, parentSourcePath),
                     }
                     : {}),
+                ...(predecessor
+                    ? { supersedesSessionId: stableNativeSessionId(machine, descriptor.harness, predecessor.sourcePath) }
+                    : {}),
             },
         ];
     });
@@ -389,6 +411,8 @@ export function nativeDescriptorFingerprint(descriptor) {
         String(descriptor.parentSessionId || ''),
         NATIVE_DESCRIPTOR_VERSION,
         nativeDescriptorMetadataFingerprint(descriptor),
+        // Appended only when present so unrelated sessions keep their fingerprint.
+        ...(descriptor.supersedesSessionId ? [String(descriptor.supersedesSessionId)] : []),
     ]);
 }
 function nativeDescriptorMetadataFingerprint(descriptor) {
@@ -992,6 +1016,7 @@ export async function uploadNativeSession(rpc, machine, descriptor, cursor = {},
             ...(descriptor.readOnly === true ? { readOnly: true } : {}),
             ...(agentSessionId ? { agentSessionId } : {}),
             ...(descriptor.parentSessionId ? { parentSessionId: descriptor.parentSessionId } : {}),
+            ...(descriptor.supersedesSessionId ? { supersedesSessionId: descriptor.supersedesSessionId } : {}),
         },
     });
     if (opened.type === 'session_tombstoned') {
@@ -1355,8 +1380,8 @@ export async function filterNativeSessionsByDirectories(sessions, allowedDirecto
 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));
+async function nativeInventory(options, machine, discover = async (only) => discoverLocalSessions(only)) {
+    let sessions = linkNativeSessionParents(machine, await discover(options.rewriteSession ? '' : options.only));
     sessions = await filterNativeSessionsByOnlyDirectory(sessions, options.onlyDirectory);
     sessions = await filterNativeSessionsByDirectories(sessions, options.allowedDirectories);
     if (!options.rewriteSession)
@@ -1452,8 +1477,98 @@ export function nativeUploadProgressSnapshot({ machine, descriptors, seen, finge
     };
 }
 async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
-    let initialSessions = await nativeInventory(options, machine);
-    const descriptorRegistry = { sessions: initialSessions };
+    const descriptorRegistry = { sessions: [] };
+    const lifecycle = new QueueDispatchLifecycle();
+    const inventory = options.watch && !options.dryRun ? new NativeInventoryWorker() : null;
+    const scanInventory = () => nativeInventory(options, machine, inventory ? (only) => inventory.scan(only) : undefined);
+    let state;
+    let nativeMonitor = null;
+    // Queue registration and anchor recovery must not wait for historical stores.
+    // The shared transport still owns the sole machine-presence connection.
+    let rpc = options.dryRun
+        ? null
+        : options.watch
+            ? new SharedUploaderConnection(options, machine)
+            : await connectUploader(options, machine);
+    let resolveDescriptors;
+    const descriptorsReady = new Promise((resolve) => {
+        resolveDescriptors = resolve;
+    });
+    if (options.watch && !options.dryRun) {
+        let shuttingDown = false;
+        const shutdown = async () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            // stop() closes the dispatch gate synchronously, before any awaited work.
+            const stopped = lifecycle.stop();
+            void inventory?.close();
+            const deadline = setTimeout(() => process.exit(0), 5_000);
+            try {
+                await stopped;
+            }
+            finally {
+                state?.close();
+                nativeMonitor?.close();
+                rpc.close();
+                clearTimeout(deadline);
+                process.exit(0);
+            }
+        };
+        process.once('SIGTERM', () => {
+            void shutdown();
+        });
+        process.once('SIGINT', () => {
+            void shutdown();
+        });
+        void watchQueuedPrompts({
+            rpc,
+            options,
+            machine,
+            getDescriptors: () => descriptorRegistry.sessions,
+            descriptorsReady,
+            resolveDescriptor: async (session) => {
+                const descriptor = nativeDescriptorForSource(String(session?.harness || ''), String(session?.sourcePath || ''));
+                if (!descriptor)
+                    return null;
+                const only = String(options.only || '').toLowerCase();
+                if (only &&
+                    !descriptor.harness.toLowerCase().includes(only) &&
+                    !descriptor.sourcePath.toLowerCase().includes(only))
+                    return null;
+                if (options.rewriteSession &&
+                    stableNativeSessionId(machine, descriptor.harness, descriptor.sourcePath) !== options.rewriteSession)
+                    return null;
+                // Apply the same workspace policy as discovery before using the fast path.
+                const exact = await filterNativeSessionsByOnlyDirectory([descriptor], options.onlyDirectory);
+                return (await filterNativeSessionsByDirectories(exact, options.allowedDirectories))[0] || null;
+            },
+            lifecycle,
+            stableSessionId: stableNativeSessionId,
+            redactor,
+        }).catch((error) => {
+            if (!lifecycle.stopping)
+                logError(`Queue worker stopped unexpectedly: ${error?.stack || error}\n`);
+        });
+    }
+    let initialSessions;
+    try {
+        initialSessions = await scanInventory();
+    }
+    catch (error) {
+        if (lifecycle.stopping)
+            return;
+        // A failed initial inventory cannot leave the control worker alive with an
+        // unresolved descriptor barrier and an uploader that has already failed.
+        void lifecycle.stop();
+        rpc?.close();
+        void inventory?.close();
+        throw error;
+    }
+    if (lifecycle.stopping)
+        return;
+    descriptorRegistry.sessions = initialSessions;
+    resolveDescriptors();
     const byHarness = new Map();
     for (const session of initialSessions)
         byHarness.set(session.harness, (byHarness.get(session.harness) || 0) + 1);
@@ -1462,7 +1577,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
         logInfo(`  ${harness}: ${count}\n`);
     if (options.dryRun)
         return;
-    const state = createNativeUploadState(options.nativeStateFile, machine);
+    state = createNativeUploadState(options.nativeStateFile, machine);
     const seen = new Map();
     const cursors = new Map();
     const fingerprints = new Map();
@@ -1473,7 +1588,6 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
     const redactionStarted = new Set();
     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);
@@ -1541,14 +1655,6 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
         nativeMonitor?.addFiles(sessions.map((descriptor) => descriptor.file));
     };
     rememberInventory(initialSessions);
-    // A single request-id-multiplexed transport carries ingestion, ownership,
-    // queue control, and live rows. These tasks remain concurrent without
-    // duplicating authentication or machine-presence sockets.
-    let rpc = options.watch ? new SharedUploaderConnection(options, machine) : await connectUploader(options, machine);
-    // Only the shared connection has a `current()` handle, and only the watch path builds one.
-    // Only the shared connection has a `current()` handle, and only the watch path builds one.
-    if (options.watch)
-        await rpc.current();
     if (options.watch)
         void watchExternalManagement(rpc, machine, () => descriptorRegistry.sessions);
     // Paths an agent wrote about are resolved from the rows themselves and
@@ -1578,18 +1684,6 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
             }
         },
     });
-    if (options.watch) {
-        void watchQueuedPrompts({
-            rpc,
-            options,
-            machine,
-            getDescriptors: () => descriptorRegistry.sessions,
-            stableSessionId: stableNativeSessionId,
-            redactor,
-        }).catch((error) => {
-            logError(`Queue worker stopped unexpectedly: ${error?.stack || error}\n`);
-        });
-    }
     const totals = { current: 0, uploaded: 0, rows: 0, empty: 0, failed: 0 };
     const failures = new Map();
     const rewritePending = new Set(options.rewriteSession ? [options.rewriteSession] : []);
@@ -1797,7 +1891,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
                 break;
             settlePass += 1;
             if (settlePass >= MAX_NATIVE_SETTLE_PASSES) {
-                const sessions = await nativeInventory(options, machine);
+                const sessions = await scanInventory();
                 rememberInventory(sessions);
                 const unsettled = changedSessions();
                 if (unsettled.length) {
@@ -1806,7 +1900,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
                 break;
             }
             await wait(250);
-            const sessions = await nativeInventory(options, machine);
+            const sessions = await scanInventory();
             rememberInventory(sessions);
         }
         state.close();
@@ -1949,20 +2043,6 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
         requestSweep();
     }, NATIVE_DISCOVERY_INTERVAL_MS);
     discoveryTimer.unref?.();
-    const shutdown = () => {
-        state.close();
-        nativeMonitor.close();
-        clearInterval(pollTimer);
-        clearInterval(discoveryTimer);
-    };
-    process.once('SIGTERM', () => {
-        shutdown();
-        process.exit(0);
-    });
-    process.once('SIGINT', () => {
-        shutdown();
-        process.exit(0);
-    });
     logInfo(`Watching ${initialSessions.length} native sessions via ${nativeMonitor.count} directories; ` +
         `polling known files every ${NATIVE_POLL_INTERVAL_MS / 1000}s and auditing every ` +
         `${NATIVE_DISCOVERY_INTERVAL_MS / 1000}s…\n`);
@@ -1973,7 +2053,7 @@ async function uploadNative(options, machine, redactor = DEFAULT_REDACTOR) {
         if (discoveryPending) {
             discoveryPending = false;
             try {
-                initialSessions = await nativeInventory(options, machine);
+                initialSessions = await scanInventory();
                 const forceMetadataDirectories = new Set(pendingMetadataDirectories);
                 pendingMetadataDirectories.clear();
                 rememberInventory(initialSessions, true, forceMetadataDirectories);

package/package.json

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