tokenmaw 0.3.0 → 0.4.0

package/dist/runtime/agent-runtime.js

@@ -1,14 +1,36 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { resolve } from 'node:path';
 import { chatStream } from '../backend.js';
 import { executeTool, getToolPolicy, toolRegistry } from '../infra/tools.js';
-import { AgentRegistry, matchesAgentSelector } from './agent-registry.js';
+import { AgentRegistry, loadWorkspaceContext, matchesAgentSelector } from './agent-registry.js';
 import { AgentRuntimeStore } from './agent-store.js';
+import { CrossProcessLockManager, LockConflictError } from './file-lock.js';
 import { FileLockManager } from './locks.js';
 import { recordTimeline } from './session-timeline.js';
+const WORKSPACE_CONTEXT_LABEL = 'AGENTS.md';
 function now() {
     return new Date().toISOString();
 }
+function mergeUsage(previous, next) {
+    const result = { ...(previous ?? {}) };
+    for (const key of ['inputTokens', 'outputTokens', 'reasoningTokens', 'cachedInputTokens', 'cacheCreationInputTokens']) {
+        if (next[key] !== undefined)
+            result[key] = (result[key] ?? 0) + next[key];
+    }
+    return result;
+}
+function asidePrefix() {
+    return 'Additional context noted earlier (aside):';
+}
+function mergeAgentUsage(previous, usage, firstTokenMs, durationMs, requests = 1) {
+    const merged = mergeUsage(previous, usage ?? {});
+    return { ...merged, requests: (previous?.requests ?? 0) + requests, turns: (previous?.turns ?? 0) + 1, firstTokenMs, lastTurnMs: durationMs };
+}
+function sessionChildren(instances, parentId) {
+    return [...instances.values()].filter((instance) => instance.parentInstanceId === parentId);
+}
+/** Tools whose success constitutes real progress (state changed on disk). */
+const PROGRESS_TOOLS = new Set(['edit_file', 'write_file']);
 // ── Context compaction ───────────────────────────────────────────────────────
 const COMPACT_SYSTEM_PROMPT = 'You are a context compaction assistant. Produce a faithful, information-dense digest of the archived conversation so a coding agent can continue the work without the original messages. Never invent facts; keep file paths, ids, decisions, and pending work exact.';
 const DEFAULT_COMPACT_KEEP_RECENT = 12;
@@ -103,6 +125,11 @@ export class AgentRuntime {
     modelStream;
     maxConcurrentTurns;
     maxAgentDepth;
+    maxChildrenPerTurn;
+    maxSteps;
+    projectContext;
+    readVersions = new Map();
+    failureCounts = new Map();
     defaultModel;
     sessions = new Map();
     instances = new Map();
@@ -113,19 +140,35 @@ export class AgentRuntime {
     running = new Set();
     controllers = new Map();
     idleWaiters = new Set();
-    fileLocks = new FileLockManager();
+    fileLocks;
+    sessionLocks;
+    sessionLockHandles = new Map();
+    sessionLockHolders = new Map();
     ready;
     shuttingDown = false;
     constructor(options) {
         this.workspaceRoot = resolve(options.workspaceRoot ?? process.cwd());
         this.registry = options.registry ?? new AgentRegistry({ workspaceRoot: this.workspaceRoot });
         this.store = options.store ?? new AgentRuntimeStore();
+        // Locks live next to session state so tests (which pass a tmp store) and
+        // alternate CODER_DATA_HOME deployments never touch the default lock dir.
+        const lockDir = resolve(this.store.runtimeDir, 'locks');
+        this.fileLocks = new FileLockManager(lockDir);
+        this.sessionLocks = new CrossProcessLockManager(lockDir);
         this.resolveModel = options.resolveModel;
         this.defaultModel = options.defaultModel;
         this.modelStream = options.modelStream ?? ((config, system, messages, tools, signal) => (chatStream(config, system, messages, tools, signal)));
         this.maxConcurrentTurns = Math.max(1, options.maxConcurrentTurns ?? Number(process.env.AGENT_MAX_CONCURRENT_TURNS ?? 4));
         this.maxAgentDepth = Math.max(1, options.maxAgentDepth ?? Number(process.env.AGENT_MAX_DEPTH ?? 4));
-        this.ready = Promise.all([this.registry.load(), this.store.init()]).then(() => this.validateSpecs());
+        this.maxChildrenPerTurn = Math.max(1, options.maxChildrenPerTurn ?? Number(process.env.AGENT_MAX_CHILDREN_PER_TURN ?? 3));
+        this.maxSteps = options.maxSteps;
+        const contextPromise = options.projectContext !== undefined
+            ? Promise.resolve(options.projectContext)
+            : loadWorkspaceContext(this.workspaceRoot);
+        this.ready = Promise.all([this.registry.load(), this.store.init(), contextPromise]).then(([, , context]) => {
+            this.projectContext = context;
+            this.validateSpecs();
+        });
     }
     whenReady() {
         return this.ready;
@@ -164,11 +207,123 @@ export class AgentRuntime {
     listAgentSpecs() {
         return this.registry.list();
     }
+    /** Absolute workspace root tools resolve relative paths against (/cd target). */
+    workspace() {
+        return this.workspaceRoot;
+    }
+    /** Switch the workspace for this runtime (/cd). Resolves `path` against the
+     * current root, revalidates it, reloads project agent specs and AGENTS.md,
+     * and re-reads project context so every following turn runs in the new root.
+     * Ongoing turns keep their already-composed prompts; the change lands on the
+     * next turn. */
+    async changeWorkspace(path, options = {}) {
+        await this.ready;
+        const previousRoot = this.workspaceRoot;
+        const target = resolve(previousRoot, path.trim());
+        let stat;
+        try {
+            stat = await import('node:fs/promises').then((fs) => fs.stat(target));
+        }
+        catch {
+            throw new Error(`cd: no such directory: ${path}`);
+        }
+        if (!stat.isDirectory())
+            throw new Error(`cd: not a directory: ${target}`);
+        if (target === previousRoot)
+            return { from: previousRoot, to: target };
+        this.workspaceRoot = target;
+        this.registry.setProjectDir(target);
+        this.projectContext = await loadWorkspaceContext(target);
+        this.readVersions.clear();
+        this.failureCounts.clear();
+        try {
+            await this.registry.load();
+            this.validateSpecs();
+        }
+        catch (error) {
+            // Roll back so the runtime never stays half-switched between roots.
+            this.workspaceRoot = previousRoot;
+            this.registry.setProjectDir(previousRoot);
+            this.projectContext = await loadWorkspaceContext(previousRoot).catch(() => undefined);
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        this.emit({ type: 'workspace_changed', sessionId: options.sessionId, workspaceRoot: target, previousRoot });
+        return { from: previousRoot, to: target };
+    }
+    // ── Cross-process session access (single writer, many read-only viewers) ───
+    sessionLockTarget(sessionId) {
+        return this.store.sessionPath(sessionId);
+    }
+    sessionLockTimeout() {
+        return Math.max(250, Number(process.env.AGENT_SESSION_LOCK_TIMEOUT_MS ?? 5_000));
+    }
+    /**
+     * Try to become the session's cross-process writer. Returns `writable: false`
+     * (instead of throwing) when another process owns the session; the caller
+     * opens the session in read-only mode.
+     */
+    async ensureSessionLock(sessionId) {
+        if (this.sessionLockHandles.has(sessionId))
+            return { writable: true };
+        try {
+            const handle = await this.sessionLocks.acquire(this.sessionLockTarget(sessionId), {
+                timeoutMs: this.sessionLockTimeout(),
+                purpose: `session:${sessionId}`,
+                session: sessionId,
+            });
+            this.sessionLockHandles.set(sessionId, handle);
+            this.sessionLockHolders.delete(sessionId);
+            return { writable: true };
+        }
+        catch (error) {
+            if (!(error instanceof LockConflictError))
+                throw error;
+            const holder = error.holder ?? await this.sessionLocks.holder(this.sessionLockTarget(sessionId));
+            if (holder)
+                this.sessionLockHolders.set(sessionId, holder);
+            return { writable: false, holder };
+        }
+    }
+    async releaseSessionLock(sessionId) {
+        const handle = this.sessionLockHandles.get(sessionId);
+        if (!handle)
+            return;
+        this.sessionLockHandles.delete(sessionId);
+        this.sessionLockHolders.delete(sessionId);
+        await handle.release();
+    }
+    /** Cross-process access state for UI status display. */
+    sessionAccess(sessionId) {
+        if (this.sessionLockHandles.has(sessionId))
+            return { writable: true };
+        if (!this.sessions.has(sessionId))
+            return { writable: true }; // never opened here; no restriction known
+        const holder = this.sessionLockHolders.get(sessionId);
+        if (!holder)
+            return { writable: false };
+        return { writable: false, holderPid: holder.pid, holderSession: holder.session };
+    }
+    /** Gate for mutating entry points. Opens the session, then self-heals a
+     * read-only state when the previous writer has since exited; otherwise
+     * fails with guidance (review or /fork). */
+    async requireSessionWrite(sessionId) {
+        await this.openSession(sessionId);
+        if (this.sessionLockHandles.has(sessionId))
+            return;
+        const access = await this.ensureSessionLock(sessionId);
+        if (access.writable)
+            return;
+        const holder = access.holder ?? this.sessionLockHolders.get(sessionId);
+        const who = holder ? `pid ${holder.pid}${holder.session ? ` (session ${holder.session})` : ''}` : 'another process';
+        throw new Error(`Session is read-only: it is currently being written by ${who}. ` +
+            'You can keep reviewing the conversation; to continue working from this point, run /fork to get your own writable copy.');
+    }
     async openSession(sessionId = `session-${Date.now()}`) {
         await this.ready;
         const current = this.sessions.get(sessionId);
         if (current)
             return cloneSession(current);
+        const access = await this.ensureSessionLock(sessionId);
         const persisted = await this.store.load(sessionId);
         if (persisted) {
             const session = persisted.session;
@@ -180,11 +335,20 @@ export class AgentRuntime {
                 }
                 this.instances.set(instance.instanceId, instance);
             }
-            for (const instance of persisted.instances.filter((item) => item.status === 'queued'))
-                this.enqueue(instance.instanceId);
+            // Read-only viewers never schedule recovered turns: the writer process
+            // that crashed owned that queue, and re-running it from here would race.
+            if (access.writable) {
+                for (const instance of persisted.instances.filter((item) => item.status === 'queued'))
+                    this.enqueue(instance.instanceId);
+            }
             this.emit({ type: 'session_opened', session: cloneSession(session) });
             return cloneSession(session);
         }
+        if (!access.writable) {
+            const holder = access.holder;
+            const who = holder ? `pid ${holder.pid}${holder.session ? ` (session ${holder.session})` : ''}` : 'another process';
+            throw new Error(`Session ${sessionId} is currently being written by ${who}. Pick a new session id, or wait for the other process to exit.`);
+        }
         if (!this.registry.get('main'))
             throw new Error('No main agent spec found');
         const createdAt = now();
@@ -231,15 +395,37 @@ export class AgentRuntime {
             this.queued.delete(id);
         }
         this.sessions.delete(sessionId);
-        await this.store.remove(sessionId);
+        await this.releaseSessionLock(sessionId);
+        // Deleting is itself a cross-process mutation: refuse when another
+        // process currently owns the session.
+        try {
+            const handle = await this.sessionLocks.acquire(this.sessionLockTarget(sessionId), {
+                timeoutMs: 2_000,
+                purpose: `session:${sessionId}:delete`,
+                session: sessionId,
+            });
+            try {
+                await this.store.remove(sessionId);
+            }
+            finally {
+                await handle.release();
+            }
+        }
+        catch (error) {
+            if (error instanceof LockConflictError) {
+                throw new Error(`Session ${sessionId} cannot be removed while another process is using it (pid ${error.holder?.pid ?? 'unknown'}).`);
+            }
+            throw error;
+        }
     }
     async clearSession(sessionId) {
-        if (!this.sessions.has(sessionId))
-            await this.openSession(sessionId);
+        await this.requireSessionWrite(sessionId);
         await this.cancelSession(sessionId);
         const session = this.sessions.get(sessionId);
         session.messages = [];
         session.timeline = [];
+        session.pendingAsides = [];
+        session.goal = undefined;
         session.updatedAt = now();
         const main = this.instances.get(session.mainInstanceId);
         if (main) {
@@ -255,6 +441,8 @@ export class AgentRuntime {
         await this.persistSession(sessionId);
     }
     async cancelSession(sessionId) {
+        if (!this.sessionLockHandles.has(sessionId))
+            await this.requireSessionWrite(sessionId);
         const session = this.sessions.get(sessionId);
         if (!session)
             return;
@@ -273,15 +461,81 @@ export class AgentRuntime {
         await this.persistSession(sessionId);
         this.notifyIdleWaiters();
     }
+    /** Queue an aside (/aside): folds into the next submitted message without starting a turn. */
+    async addAside(sessionId, content) {
+        const text = content.trim();
+        if (!text)
+            throw new Error('Aside cannot be empty');
+        await this.requireSessionWrite(sessionId);
+        const session = this.sessions.get(sessionId);
+        const hadAsides = (session.pendingAsides?.length ?? 0) > 0;
+        (session.pendingAsides ??= []).push(text);
+        session.updatedAt = now();
+        await this.persistSession(sessionId);
+        this.emit({ type: 'system_message', sessionId, message: { messageId: randomUUID(), role: 'system', content: hadAsides
+                    ? `Noted — another aside is already queued; both will be included with your next message.`
+                    : `Noted. This will be included with your next message without starting a turn.`, createdAt: now() } });
+        return { queued: true, detail: hadAsides
+                ? 'Queued behind one earlier aside; both will be included with the next message.'
+                : 'Queued. It will be included with the next message without starting a turn.' };
+    }
+    /** Set or clear the standing session goal (/goal). Injected into every agent's prompt until cleared. */
+    async setSessionGoal(sessionId, goal) {
+        const text = goal.trim();
+        await this.requireSessionWrite(sessionId);
+        const session = this.sessions.get(sessionId);
+        session.goal = text || undefined;
+        session.updatedAt = now();
+        await this.persistSession(sessionId);
+        this.emit({ type: 'system_message', sessionId, message: { messageId: randomUUID(), role: 'system',
+                content: text ? `Session goal set: ${text}` : 'Session goal cleared.', createdAt: now() } });
+        return { set: Boolean(text), detail: text ? `Goal set. It now applies to every agent in this session: ${text}` : 'Goal cleared.' };
+    }
+    /** Emit a session-scoped timeline notice that never reaches the model. */
+    async emitSystemNotice(sessionId, content) {
+        if (!this.sessions.has(sessionId))
+            await this.openSession(sessionId);
+        this.emit({ type: 'system_message', sessionId, message: { messageId: randomUUID(), role: 'system', content, createdAt: now() } });
+    }
+    /** Fork a session into a new persisted copy (used by /fork and /btw side conversations).
+     * Works from a read-only session: the copy is taken from the persisted file
+     * and the fork's lock is held while copying so a concurrent opener of the
+     * same new id either waits or loses the race cleanly. */
+    async forkSession(sessionId, newSessionId = `session-${Date.now()}`) {
+        await this.openSession(sessionId);
+        await this.persistSession(sessionId);
+        const handle = await this.sessionLocks.acquire(this.sessionLockTarget(newSessionId), {
+            timeoutMs: this.sessionLockTimeout(),
+            purpose: `session:${newSessionId}:fork`,
+            session: newSessionId,
+        });
+        try {
+            await this.store.copySession(sessionId, newSessionId);
+        }
+        finally {
+            await handle.release();
+        }
+        const detail = `Forked into ${newSessionId}. /sessions lists both; the original stays untouched.`;
+        this.emit({ type: 'system_message', sessionId, message: { messageId: randomUUID(), role: 'system', content: detail, createdAt: now() } });
+        return { sessionId: newSessionId, detail };
+    }
     async submitMessage(sessionId, content) {
         const text = content.trim();
         if (!text)
             throw new Error('Message cannot be empty');
-        await this.openSession(sessionId);
+        await this.requireSessionWrite(sessionId);
         const session = this.sessions.get(sessionId);
         const main = this.instances.get(session.mainInstanceId);
         const turnId = randomUUID();
-        const message = { messageId: randomUUID(), role: 'user', content: text, createdAt: now(), turnId };
+        const queuedAsides = session.pendingAsides ?? [];
+        session.pendingAsides = [];
+        const composed = queuedAsides.length
+            ? `${text}
+
+${asidePrefix()}
+${queuedAsides.map((aside, index) => `${index + 1}. ${aside}`).join('\n')}`
+            : text;
+        const message = { messageId: randomUUID(), role: 'user', content: composed, createdAt: now(), turnId };
         session.messages.push(message);
         session.updatedAt = message.createdAt;
         if (main.status === 'running' || main.status === 'waiting') {
@@ -289,9 +543,20 @@ export class AgentRuntime {
         }
         if (main.status === 'cancelled')
             main.status = 'idle';
-        this.deliver(main, text, undefined, turnId);
+        // The model must see the folded asides, so deliver the composed message.
+        // The TUI renders the asides as separate system entries from the emitted
+        // system_message events above, while this user message keeps them inline.
+        this.deliver(main, composed, undefined, turnId);
         await this.persistSession(sessionId);
         this.emit({ type: 'user_message', sessionId, message: { ...message } });
+        if (queuedAsides.length) {
+            // Timeline-only notices; the user message itself already carries the
+            // asides inline for the model.
+            this.emit({ type: 'system_message', sessionId, message: { messageId: randomUUID(), role: 'system', content: `Aside${queuedAsides.length > 1 ? 's' : ''} included with your message:`, createdAt: now() } });
+            for (const aside of queuedAsides) {
+                this.emit({ type: 'system_message', sessionId, message: { messageId: randomUUID(), role: 'system', content: `· ${aside}`, createdAt: now() } });
+            }
+        }
         this.enqueue(main.instanceId);
         return turnId;
     }
@@ -309,8 +574,13 @@ export class AgentRuntime {
         const ancestors = this.ancestorAgentIds(parent);
         if (ancestors.has(agentId))
             throw new Error(`Agent call cycle rejected: ${agentId} already exists in the ancestor chain`);
+        const turnId = parent.activeTurnId;
+        const childrenThisTurn = sessionChildren(this.instances, parent.instanceId).filter((child) => child.parentTurnId === turnId).length;
+        if (childrenThisTurn >= this.maxChildrenPerTurn)
+            throw new Error(`Maximum of ${this.maxChildrenPerTurn} child agents per turn reached; reuse an existing agent or continue directly.`);
         const session = this.sessions.get(parent.sessionId);
         const child = this.newInstance(parent.sessionId, agentId, parent.instanceId, parent.depth + 1);
+        child.parentTurnId = turnId;
         this.instances.set(child.instanceId, child);
         parent.childInstanceIds.push(child.instanceId);
         parent.updatedAt = now();
@@ -467,6 +737,9 @@ export class AgentRuntime {
         for (const sessionId of this.sessions.keys())
             await this.persistSession(sessionId);
         await this.store.flush();
+        for (const sessionId of [...this.sessionLockHandles.keys()]) {
+            await this.releaseSessionLock(sessionId).catch(() => undefined);
+        }
     }
     newInstance(sessionId, agentId, parentInstanceId, depth = 0, createdAt = now()) {
         if (!this.registry.get(agentId))
@@ -567,11 +840,15 @@ export class AgentRuntime {
     }
     systemPrompt(instance, spec) {
         const catalog = this.registry.allowedAgents(spec);
-        const relatedInstances = this.listInstances(instance.sessionId)
-            .filter((candidate) => candidate.instanceId !== instance.instanceId && candidate.status !== 'cancelled')
-            .map((candidate) => `- ${candidate.agentId} (${candidate.instanceId}): ${candidate.status}${candidate.lastOutput ? ` — ${candidate.lastOutput.slice(0, 180)}` : ''}`);
+        // Keep the system prefix stable between model calls. Injecting every sibling's
+        // live status here invalidates provider prompt caches and burns input tokens;
+        // child results are delivered through the mailbox and remain visible in the
+        // normal conversation context.
+        const session = this.sessions.get(instance.sessionId);
         return [
             spec.instructions,
+            ...(session?.goal ? ['', `Standing goal for this session (highest priority; stay aligned with it unless the user says otherwise):`, session.goal] : []),
+            ...(this.projectContext ? ['', `Project context (${WORKSPACE_CONTEXT_LABEL}):`, this.projectContext] : []),
             '',
             'Runtime contract:',
             `- You are agent "${spec.id}" in workspace ${this.workspaceRoot}.`,
@@ -584,9 +861,7 @@ export class AgentRuntime {
             catalog.length
                 ? `Available agents:\n${catalog.map((agent) => `- ${agent.id}: ${agent.description}`).join('\n')}`
                 : 'Available agents: none.',
-            relatedInstances.length
-                ? `Existing instances in this session:\n${relatedInstances.join('\n')}`
-                : 'Existing instances in this session: none.',
+            'Existing instances are communicated through mailbox messages. Reuse an existing related agent when possible; do not spawn duplicates.',
         ].join('\n');
     }
     toolsFor(instance, spec) {
@@ -784,6 +1059,7 @@ export class AgentRuntime {
         instance.activeTurnId = turnId;
         instance.status = 'running';
         instance.updatedAt = now();
+        this.failureCounts.delete(instance.instanceId);
         this.controllers.set(instance.instanceId, controller);
         this.absorbMailbox(instance);
         this.emit({ type: 'instance_updated', instance: cloneInstance(instance) });
@@ -794,7 +1070,12 @@ export class AgentRuntime {
                 throw new Error('No model configured. Use /provider or /model first.');
             const tools = this.toolsFor(instance, spec);
             let finalOutput = '';
-            for (let step = 0; step < 32; step += 1) {
+            const turnStartedAt = Date.now();
+            let turnUsage;
+            let firstTokenMs;
+            let requestCount = 0;
+            const stepLimit = Math.max(1, this.maxSteps ?? (instance.parentInstanceId ? 48 : 64));
+            for (let step = 0; step < stepLimit; step += 1) {
                 if (controller.signal.aborted || instance.activeTurnId !== turnId)
                     return;
                 if (instance.pendingCompact || this.shouldAutoCompact(instance.messages, config)) {
@@ -809,6 +1090,7 @@ export class AgentRuntime {
                     catch { /* Compaction is best-effort; trimMessages remains the fallback. */ }
                 }
                 const messages = this.trimMessages(instance.messages, config);
+                requestCount += 1;
                 let text = '';
                 let thinking = '';
                 const responseItems = [];
@@ -823,12 +1105,16 @@ export class AgentRuntime {
                         this.emit({ type: 'thinking_delta', sessionId: session.sessionId, instanceId: instance.instanceId, turnId, text: chunk.thinking });
                     }
                     if (chunk.content) {
+                        if (firstTokenMs === undefined)
+                            firstTokenMs = Date.now() - turnStartedAt;
                         text += chunk.content;
                         finalOutput += chunk.content;
                         if (!instance.parentInstanceId) {
                             this.emit({ type: 'assistant_delta', sessionId: session.sessionId, instanceId: instance.instanceId, turnId, text: chunk.content });
                         }
                     }
+                    if (chunk.usage)
+                        turnUsage = mergeUsage(turnUsage, chunk.usage);
                     if (chunk.toolCalls?.length)
                         calls.push(...chunk.toolCalls);
                 }
@@ -850,6 +1136,31 @@ export class AgentRuntime {
                         return;
                     instance.messages.push({ role: 'tool', content: output, tool_use_id: call.id });
                     this.emit({ type: 'tool_finished', instanceId: instance.instanceId, turnId, tool: call.function.name, output });
+                    const fingerprint = createHash('sha256')
+                        .update(call.function.name)
+                        .update('\0')
+                        .update(JSON.stringify(args))
+                        .update('\0')
+                        .update(output)
+                        .digest('hex');
+                    const failed = /^Error:/i.test(output) || /PolicyError/.test(output);
+                    if (failed) {
+                        // Progress, not recency, resets the failure chain: counts are kept
+                        // per fingerprint, so interleaved successful reads (which prove
+                        // nothing changed) cannot launder a repeating failure.
+                        const counts = this.failureCounts.get(instance.instanceId) ?? new Map();
+                        const repeats = (counts.get(fingerprint) ?? 0) + 1;
+                        counts.set(fingerprint, repeats);
+                        this.failureCounts.set(instance.instanceId, counts);
+                        if (repeats >= 3) {
+                            throw new Error(`Doom loop detected: ${call.function.name} produced the same failure ${repeats} times without progress. Change approach or inspect the diagnostic before retrying.`);
+                        }
+                    }
+                    else if (PROGRESS_TOOLS.has(call.function.name)) {
+                        // Only a state-changing success (an actual write) counts as
+                        // progress; read-only successes leave the failure chain intact.
+                        this.failureCounts.delete(instance.instanceId);
+                    }
                 }
                 if (instance.pendingCompact && !controller.signal.aborted && instance.activeTurnId === turnId) {
                     try {
@@ -861,12 +1172,15 @@ export class AgentRuntime {
                     }
                     catch { /* Compaction is best-effort. */ }
                 }
-                if (step === 31)
-                    throw new Error('Agent reached the 32-step limit. Review the activity and send a follow-up to continue.');
+                if (step === stepLimit - 1)
+                    throw new Error(`Agent reached the ${stepLimit}-step safety limit. Review the activity and send a follow-up to continue.`);
             }
             if (controller.signal.aborted || instance.activeTurnId !== turnId)
                 return;
             instance.lastOutput = finalOutput.trim() || instance.lastOutput;
+            const endedAt = now();
+            instance.usage = mergeAgentUsage(instance.usage, turnUsage, firstTokenMs, Date.now() - turnStartedAt, requestCount);
+            instance.lastTurn = { startedAt: new Date(turnStartedAt).toISOString(), endedAt, durationMs: Date.now() - turnStartedAt, usage: turnUsage };
             instance.lastError = undefined;
             instance.status = 'idle';
             instance.activeTurnId = undefined;
@@ -949,6 +1263,19 @@ export class AgentRuntime {
                 signal,
                 policy: getToolPolicy(),
                 acquireWriteLock: (path) => this.fileLocks.acquire(path),
+                requirePriorRead: true,
+                getReadVersion: (path) => this.readVersions.get(instance.instanceId)?.get(resolve(path)),
+                recordReadVersion: (path, version) => {
+                    let versions = this.readVersions.get(instance.instanceId);
+                    if (!versions) {
+                        versions = new Map();
+                        this.readVersions.set(instance.instanceId, versions);
+                    }
+                    versions.set(resolve(path), version);
+                },
+                recordWriteVersion: (path, _version) => {
+                    this.readVersions.get(instance.instanceId)?.delete(resolve(path));
+                },
             });
         }
         catch (error) {
@@ -979,6 +1306,10 @@ export class AgentRuntime {
         const session = this.sessions.get(sessionId);
         if (!session)
             return;
+        // Read-only viewers never persist: the session file belongs to the
+        // cross-process writer holding the session lock.
+        if (!this.sessionLockHandles.has(sessionId))
+            return;
         const snapshot = {
             version: 1,
             session: cloneSession(session),

package/dist/runtime/agent-store.js

@@ -31,6 +31,10 @@ export class AgentRuntimeStore {
     constructor(baseDir = process.env.CODER_DATA_HOME?.trim() || resolve(homedir(), '.coder')) {
         this.dir = resolve(baseDir, 'runtime');
     }
+    /** Root directory for runtime state (sessions, archives, locks, instances). */
+    get runtimeDir() {
+        return this.dir;
+    }
     async init() {
         await mkdir(this.dir, { recursive: true });
     }
@@ -38,6 +42,10 @@ export class AgentRuntimeStore {
         validSessionId(sessionId);
         return resolve(this.dir, `${sessionId}.json`);
     }
+    /** Absolute path of the persisted session snapshot (cross-process lock target). */
+    sessionPath(sessionId) {
+        return this.path(sessionId);
+    }
     async save(snapshot) {
         const path = this.path(snapshot.session.sessionId);
         const payload = `${JSON.stringify(snapshot, null, 2)}\n`;
@@ -75,6 +83,21 @@ export class AgentRuntimeStore {
             return undefined;
         }
     }
+    /** Duplicate one persisted session file under a new session id (used by /fork). */
+    async copySession(sourceSessionId, newSessionId) {
+        const source = await this.load(sourceSessionId);
+        if (!source)
+            throw new Error(`Session ${sourceSessionId} is not persisted yet.`);
+        const snapshot = {
+            version: 1,
+            session: { ...source.session, sessionId: newSessionId },
+            instances: source.instances.map((instance) => ({ ...instance, sessionId: newSessionId })),
+        };
+        await this.save(snapshot);
+        for (const archive of await this.loadArchives(sourceSessionId)) {
+            await this.saveArchive(newSessionId, archive.instanceId, archive.seq, archive.messages);
+        }
+    }
     async list() {
         await Promise.all([...writes.values()].map((write) => write.catch(() => undefined)));
         let files = [];