tokenmaw 0.3.0 → 0.4.1

package/dist/responses.js

@@ -66,7 +66,13 @@ export async function* responsesStream(config, instructions, messages, tools, si
                     throw new Error(event.response?.error?.message ?? event.message ?? event.response?.incomplete_details?.reason ?? `Responses: ${event.type}`);
                 }
                 if (event.type === 'response.completed') {
-                    yield { content: null, done: true };
+                    const usage = event.response?.usage;
+                    yield { content: null, done: true, usage: usage ? {
+                            inputTokens: usage.input_tokens,
+                            outputTokens: usage.output_tokens,
+                            cachedInputTokens: usage.input_tokens_details?.cached_tokens,
+                            reasoningTokens: usage.output_tokens_details?.reasoning_tokens,
+                        } : undefined };
                     return;
                 }
             }

package/dist/runtime/agent-registry.js

@@ -1,6 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { relative, resolve, sep } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 function unquote(value) {
     const trimmed = value.trim();
     if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
@@ -86,6 +86,25 @@ async function markdownFiles(root) {
 function specId(root, file) {
     return relative(root, file).split(sep).join('/').replace(/\.md$/i, '');
 }
+/** Names checked in order when loading project context. The lowercase form
+ * covers case-insensitive filesystems; the capitalized forms follow the
+ * agents.md convention used by other coding agents. */
+const WORKSPACE_CONTEXT_FILENAMES = ['AGENTS.md', 'AGENT.md', 'agents.md'];
+/** Loads an optional AGENTS.md-style project context document from the
+ * workspace root. Plain Markdown with no frontmatter; a missing, empty, or
+ * unreadable file is not an error — the convention is opt-in per workspace. */
+export async function loadWorkspaceContext(root) {
+    for (const name of WORKSPACE_CONTEXT_FILENAMES) {
+        try {
+            const content = (await readFile(join(root, name), 'utf8')).replace(/^\uFEFF/, '').trim();
+            if (content)
+                return content;
+            // An empty file counts as absent; keep looking at the remaining names.
+        }
+        catch { /* try the next candidate name */ }
+    }
+    return undefined;
+}
 function matchesSelector(id, selector) {
     if (selector === '*')
         return true;
@@ -96,15 +115,26 @@ function matchesSelector(id, selector) {
 export class AgentRegistry {
     specs = new Map();
     roots;
+    builtinDir;
+    userDir;
+    projectDir;
     constructor(options = {}) {
         const workspaceRoot = resolve(options.workspaceRoot ?? process.cwd());
-        const builtinDir = resolve(options.builtinDir ?? resolve(import.meta.dirname, '..', '..', 'agents'));
+        this.builtinDir = resolve(options.builtinDir ?? resolve(import.meta.dirname, '..', '..', 'agents'));
+        this.userDir = resolve(options.userDir ?? resolve(homedir(), '.coder', 'agents'));
+        this.projectDir = options.projectDir ? resolve(options.projectDir) : undefined;
         this.roots = [
-            { path: builtinDir, scope: 'builtin' },
-            { path: resolve(options.userDir ?? resolve(homedir(), '.coder', 'agents')), scope: 'user' },
-            { path: resolve(options.projectDir ?? resolve(workspaceRoot, '.coder', 'agents')), scope: 'project' },
+            { path: this.builtinDir, scope: 'builtin' },
+            { path: this.userDir, scope: 'user' },
+            { path: this.projectDir ?? resolve(workspaceRoot, '.coder', 'agents'), scope: 'project' },
         ];
     }
+    /** Point the project-scope spec root at another workspace (<root>/.coder/agents).
+     * Takes effect on the next load(); used by /cd when switching workspaces. */
+    setProjectDir(workspaceRoot) {
+        this.projectDir = resolve(workspaceRoot, '.coder', 'agents');
+        this.roots[this.roots.length - 1] = { path: this.projectDir, scope: 'project' };
+    }
     async load() {
         this.specs.clear();
         for (const root of this.roots) {

package/dist/runtime/agent-runtime.js

@@ -1,14 +1,33 @@
-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 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 +122,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 +137,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 +204,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 +332,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 +392,36 @@ 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.goal = undefined;
         session.updatedAt = now();
         const main = this.instances.get(session.mainInstanceId);
         if (main) {
@@ -255,6 +437,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,11 +457,51 @@ export class AgentRuntime {
         await this.persistSession(sessionId);
         this.notifyIdleWaiters();
     }
+    /** 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();
@@ -309,8 +533,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 +696,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 +799,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 +820,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 +1018,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 +1029,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 +1049,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 +1064,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 +1095,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 +1131,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 +1222,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 +1265,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),