@namzu/sdk 36.0.0 → 38.0.0

package/src/runtime/query/tool-call-budget.ts

@@ -0,0 +1,115 @@
+import type { RunId } from '../../types/ids/index.js'
+import type { RunEvent } from '../../types/run/index.js'
+
+export function assertMaxToolCalls(limit: number | undefined): void {
+	if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {
+		throw new RangeError('maxToolCalls must be a nonnegative safe integer.')
+	}
+}
+
+/** A run-owned admission ledger; durability belongs to the run's event store. */
+export class ToolCallBudget {
+	private used = 0
+	private initialized?: Promise<void>
+	private chain: Promise<void> = Promise.resolve()
+	private failed: unknown
+
+	constructor(
+		private readonly limit: number,
+		private readonly runId: RunId,
+		private readonly emit: (event: RunEvent) => Promise<void>,
+		private readonly read?: () => Promise<readonly RunEvent[]>,
+	) {
+		assertMaxToolCalls(limit)
+	}
+
+	private async initialize(): Promise<void> {
+		const events = (await this.read?.()) ?? []
+		if (events.length > 100_000) throw new Error('Tool-call budget recovery exceeds 100000 events.')
+		let initialized = false
+		let expectedSeq = 0
+		for (const event of events) {
+			// A replayed transcript must be complete and belong to this run.
+			if (event.runId !== this.runId || event.seq !== ++expectedSeq)
+				throw new Error('Tool-call budget recovery requires a complete run event log.')
+			if (event.type === 'tool_calls_admitted') {
+				if (
+					!Number.isSafeInteger(event.count) ||
+					event.count < 0 ||
+					!Number.isSafeInteger(event.used) ||
+					event.used !== this.used + event.count ||
+					!Number.isSafeInteger(event.limit) ||
+					event.limit < event.used ||
+					!['initialize', 'batch', 'nested', 'retry'].includes(event.kind) ||
+					(event.kind === 'initialize'
+						? initialized || event.count !== 0
+						: !initialized || event.count === 0)
+				)
+					throw new Error('Invalid tool-call admission ledger.')
+				initialized = true
+				this.used = event.used
+			} else if (
+				!initialized &&
+				(event.type === 'tool_executing' || event.type === 'tool_completed')
+			) {
+				throw new Error('Cannot establish tool-call usage for an earlier unbudgeted execution.')
+			}
+		}
+		if (!initialized) {
+			await this.emit({
+				type: 'tool_calls_admitted',
+				runId: this.runId,
+				kind: 'initialize',
+				count: 0,
+				used: 0,
+				limit: this.limit,
+			})
+		}
+	}
+
+	/** Reserve before work, never refund. A refused group consumes no new slots. */
+	async admit(
+		count: number,
+		kind: 'batch' | 'nested' | 'retry',
+		signal: AbortSignal,
+	): Promise<string | undefined> {
+		signal.throwIfAborted()
+		const previous = this.chain
+		let release!: () => void
+		this.chain = new Promise<void>((resolve) => {
+			release = resolve
+		})
+		try {
+			await previous
+			signal.throwIfAborted()
+			if (this.failed !== undefined) throw this.failed
+			this.initialized ??= this.initialize()
+			await this.initialized
+			signal.throwIfAborted()
+			if (count > Math.max(0, this.limit - this.used)) {
+				return `Tool-call budget exhausted: this ${kind} needs ${count} slots; ${Math.max(0, this.limit - this.used)} remain of maxToolCalls=${this.limit}. No calls in this admission were executed.`
+			}
+			if (count === 0) return undefined
+			const used = this.used + count
+			try {
+				await this.emit({
+					type: 'tool_calls_admitted',
+					runId: this.runId,
+					kind,
+					count,
+					used,
+					limit: this.limit,
+				})
+			} catch (error) {
+				// An uncertain write must not be retried as a fresh allowance.
+				this.failed = error ?? new Error('Tool-call admission persistence failed.')
+				throw this.failed
+			}
+			this.used = used
+			signal.throwIfAborted()
+			return undefined
+		} finally {
+			release()
+		}
+	}
+}

package/src/runtime/query/tooling.ts

@@ -20,6 +20,7 @@ import { ToolExecutor } from './executor.js'
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
 export interface ToolingBootstrapConfig {
+	fileReadTracker?: import('../../types/tool/index.js').FileReadTracker
 	tools: ToolRegistryContract
 	runId: RunId
 	workingDirectory: string
@@ -43,6 +44,8 @@ export interface ToolingBootstrapConfig {
 	web?: import('../../types/tool/index.js').ToolContext['web']
 	toolRetryBackoff?: Partial<BackoffPolicy>
 	maxToolConcurrency?: number
+	maxToolCalls?: number
+	readToolCallBudgetEvents?: () => Promise<readonly RunEvent[]>
 	maxToolOutputChars?: number
 	maxToolContentBytes?: number
 	toolOutputDir?: string
@@ -65,6 +68,7 @@ export class ToolingBootstrap {
 		return new ToolExecutor(
 			{
 				tools: config.tools,
+				...(config.fileReadTracker ? { fileReadTracker: config.fileReadTracker } : {}),
 				runId: config.runId,
 				workingDirectory: config.workingDirectory,
 				...(config.additionalDirectories?.length
@@ -84,6 +88,10 @@ export class ToolingBootstrap {
 				...(config.toolRetryBackoff !== undefined
 					? { toolRetryBackoff: config.toolRetryBackoff }
 					: {}),
+				...(config.maxToolCalls !== undefined ? { maxToolCalls: config.maxToolCalls } : {}),
+				...(config.readToolCallBudgetEvents
+					? { readToolCallBudgetEvents: config.readToolCallBudgetEvents }
+					: {}),
 				...(config.maxToolConcurrency !== undefined
 					? { maxToolConcurrency: config.maxToolConcurrency }
 					: {}),

package/src/sandbox/file-walk-program.ts

@@ -51,6 +51,14 @@ async function run() {
     try { canonicalRoot = await fs.realpath(plan.root); }
     catch (error) { if (missing(error)) return; throw error; }
     if (canonicalRoot !== path.resolve(plan.root)) throw new Error('File walk root follows a symbolic link; use its authorized real directory');
+    const rootInfo = await fs.lstat(plan.root);
+    if (rootInfo.isFile()) {
+      visit(++visited);
+      if (matchers.some(matcher => matcher.test(path.basename(plan.root)))) {
+        await write({type:'entry', path:plan.root, size:rootInfo.size});
+      }
+      return;
+    }
     let start = plan.root;
     for (const part of plan.prefix) {
       start = path.join(start, part);

package/src/sandbox/file-walk.ts

@@ -227,6 +227,15 @@ async function* executeWalk(
 		}
 		if (canonicalRoot !== path.resolve(plan.root))
 			throw new Error('File walk root follows a symbolic link; use its authorized real directory')
+		// A named regular file is a one-entry search, not an empty directory.
+		const rootInfo = await wait(fs.lstat(plan.root))
+		check()
+		if (rootInfo.isFile()) {
+			noteVisit()
+			if (matchers.some((matcher) => matcher.test(path.basename(plan.root))))
+				yield { path: plan.root, size: rootInfo.size }
+			return
+		}
 		let start = plan.root
 		// Never follow a static-prefix symlink to speed up a pattern: traversal
 		// and its optimized starting point must have the same link policy.

package/src/scheduler/completion-inbox.ts

@@ -464,6 +464,9 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 			`task_id: ${handle.taskId}`,
 			`agent: ${handle.agentId}`,
 			`state: ${handle.state}`,
+			...(handle.state === 'completed' && run?.stopReason && run.stopReason !== 'end_turn'
+				? ['outcome: incomplete — execution stopped; this does not establish task completion.']
+				: []),
 			...(handle.result?.stopReason ? [`stop_reason: ${handle.result.stopReason}`] : []),
 			...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
 			'',

package/src/scheduler/local.ts

@@ -111,6 +111,7 @@ export class LocalTaskScheduler implements TaskScheduler {
 		const task = await this.agentManager.sendMessage(
 			{
 				agentId: options.agentId,
+				beforeStart: options.beforeStart,
 				input: {
 					messages: [createUserMessage(options.prompt)],
 					workingDirectory: options.workingDirectory,

package/src/session/handoff/capacity.ts

@@ -62,7 +62,7 @@ export interface CapacityValidator {
 	): Promise<void>
 
 	/**
-	 * Asserts `existingDirectChildren + pendingNewChildren ≤ projectMaxWidth`
+	 * Asserts `liveDirectChildren + pendingNewChildren ≤ projectMaxWidth`
 	 * under `parentSessionId`. The width cap applies to a single spawn call —
 	 * a broadcast of N recipients passes `pendingNewChildren = N`.
 	 */
@@ -77,7 +77,7 @@ export interface CapacityValidator {
 /**
  * Default validator backed by {@link SessionStore}. Uses `getAncestry` for
  * depth (root-to-self chain length) and `getChildren` for width (count of
- * existing direct sub-sessions).
+ * pending or active direct sub-sessions). Historical edges stay queryable.
  */
 export class DefaultCapacityValidator implements CapacityValidator {
 	constructor(private readonly store: SessionStore) {}
@@ -108,7 +108,11 @@ export class DefaultCapacityValidator implements CapacityValidator {
 		tenantId: TenantId,
 	): Promise<void> {
 		const existing = await this.store.getChildren(parentSessionId, tenantId)
-		const total = existing.length + pendingNewChildren
+		const live = existing.filter(
+			(child) =>
+				child.status !== 'idle' && child.status !== 'failed' && child.status !== 'archived',
+		)
+		const total = live.length + pendingNewChildren
 		if (total > projectMaxWidth) {
 			throw new DelegationCapacityExceeded({
 				dimension: 'width',

package/src/store/memory/disk.ts

@@ -6,16 +6,24 @@ import type {
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
+	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
 	MemoryStore,
+	UpdateMemoryParams,
 } from '../../types/memory/index.js'
+import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId, isEntityId } from '../../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DiskRecordStore } from '../kv/record-store.js'
 import { defineSchema } from '../schema.js'
-import { InMemoryMemoryIndex } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
+import {
+	DEFAULT_MEMORY_LOCK_TIMEOUT_MS,
+	acquireMemoryOperationLock,
+	validateMemoryLockTimeout,
+} from './operation-lock.js'
 
 /**
  * This store's on-disk format, versioned as a unit — which is how a
@@ -32,27 +40,6 @@ interface StorageLocation {
 	readonly contentDir: string
 }
 
-const operationTails = new Map<string, Promise<void>>()
-
-/** Serialize every operation over one canonical disk projection in this process. */
-async function withMemoryOperationLock<T>(key: string, operation: () => Promise<T>): Promise<T> {
-	const previous = operationTails.get(key) ?? Promise.resolve()
-	let release = () => {}
-	const current = new Promise<void>((resolveCurrent) => {
-		release = resolveCurrent
-	})
-	const tail = previous.then(() => current)
-	operationTails.set(key, tail)
-
-	await previous
-	try {
-		return await operation()
-	} finally {
-		release()
-		if (operationTails.get(key) === tail) operationTails.delete(key)
-	}
-}
-
 function invalidIndex(
 	reason: string,
 	details: { entryIndex?: number; field?: string } = {},
@@ -163,11 +150,14 @@ function assertMemoryContent(value: unknown, expectedId: MemoryId): asserts valu
 export interface DiskMemoryStoreConfig {
 	baseDir: string
 	logger?: Logger
+	/** Maximum wait for another process's operation; default 10 seconds. Never breaks stale locks. */
+	lockTimeoutMs?: number
 }
 
 export class DiskMemoryStore implements MemoryStore {
 	private readonly baseDir: string
 	private readonly log: Logger
+	private readonly lockTimeoutMs: number
 	private readonly index = new InMemoryMemoryIndex()
 	private location?: StorageLocation
 	// Two instances of one primitive rather than two copies of its body.
@@ -180,6 +170,8 @@ export class DiskMemoryStore implements MemoryStore {
 	constructor(config: DiskMemoryStoreConfig) {
 		this.baseDir = join(config.baseDir, 'memory')
 		this.log = resolveLogger(config.logger).child({ [SCOPE_ATTRIBUTE]: 'store/memory/disk' })
+		this.lockTimeoutMs = config.lockTimeoutMs ?? DEFAULT_MEMORY_LOCK_TIMEOUT_MS
+		validateMemoryLockTimeout(this.lockTimeoutMs)
 	}
 
 	private get contentDir(): string {
@@ -235,10 +227,16 @@ export class DiskMemoryStore implements MemoryStore {
 		operation: (location: StorageLocation) => Promise<T>,
 	): Promise<T> {
 		const location = await this.storageLocation()
-		return withMemoryOperationLock(location.indexPath, async () => {
+		const release = await acquireMemoryOperationLock(
+			join(dirname(location.indexPath), 'operation.lock'),
+			this.lockTimeoutMs,
+		)
+		try {
 			await this.reloadIndex(location)
-			return operation(location)
-		})
+			return await operation(location)
+		} finally {
+			await release()
+		}
 	}
 
 	private async readContent(location: StorageLocation, id: MemoryId): Promise<MemoryContent> {
@@ -307,10 +305,17 @@ export class DiskMemoryStore implements MemoryStore {
 		})
 	}
 
-	async update(
-		id: MemoryId,
-		updates: Partial<CreateMemoryParams>,
-	): Promise<MemoryIndexEntry | undefined> {
+	async getRecord(id: MemoryId): Promise<MemoryRecord | undefined> {
+		return this.withAuthoritativeIndex(async (location) => {
+			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
+			const entry = this.index.getEntry(id)
+			if (!entry) return undefined
+			return structuredClone({ entry, content: await this.readContent(location, id) })
+		})
+	}
+
+	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
 			const existing = this.index.getEntry(id)
@@ -321,6 +326,7 @@ export class DiskMemoryStore implements MemoryStore {
 				title: updates.title ?? existing.title,
 				summary: updates.summary ?? existing.summary,
 				tags: updates.tags ? [...updates.tags] : existing.tags,
+				status: updates.status ?? existing.status,
 				updatedAt: Date.now(),
 			}
 			const updatesContent =
@@ -367,7 +373,23 @@ export class DiskMemoryStore implements MemoryStore {
 	}
 
 	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
-		return this.withAuthoritativeIndex(async () => this.index.search(params ?? {}))
+		return this.withAuthoritativeIndex(async (location) => {
+			if (!params?.query?.trim() && !params?.requiredIdentifiers?.length)
+				return this.index.search(params ?? {})
+			// Search the current bodies inside the same operation as the index
+			// snapshot. No retained cache can hide another process's update.
+			const candidates = this.index.search({
+				...params,
+				query: undefined,
+				limit: undefined,
+				requiredIdentifiers: undefined,
+			})
+			const contents = new Map<MemoryId, string>()
+			for (const entry of candidates.entries) {
+				contents.set(entry.id, (await this.readContent(location, entry.id)).content)
+			}
+			return searchMemoryEntries(candidates.entries, params, (id) => contents.get(id) ?? '')
+		})
 	}
 
 	getIndex(): InMemoryMemoryIndex {

package/src/store/memory/index.ts

@@ -6,37 +6,85 @@ import type {
 	MemorySearchResult,
 } from '../../types/memory/index.js'
 
-export class InMemoryMemoryIndex implements MemoryIndex {
-	private entries = new Map<string, MemoryIndexEntry>()
-
-	search(params: MemorySearchParams): MemorySearchResult {
-		let results = Array.from(this.entries.values())
-
-		if (params.query) {
-			const q = params.query.toLowerCase()
-			results = results.filter(
-				(e) => e.title.toLowerCase().includes(q) || e.summary.toLowerCase().includes(q),
-			)
-		}
-
-		if (params.tags && params.tags.length > 0) {
-			const requiredTags = params.tags
-			results = results.filter((e) => requiredTags.every((tag) => e.tags.includes(tag)))
-		}
+function terms(text: string): Set<string> {
+	return new Set(
+		text
+			.normalize('NFKC')
+			.toLowerCase()
+			.match(/[\p{L}\p{N}]+/gu) ?? [],
+	)
+}
 
-		if (params.status) {
-			results = results.filter((e) => e.status === params.status)
-		}
+/** Exact normalized word membership; no substring, stemming or alias inference. */
+export function matchesMemoryIdentifier(text: string, identifiers: ReadonlySet<string>): boolean {
+	for (const match of text
+		.normalize('NFKC')
+		.toLowerCase()
+		.matchAll(/[\p{L}\p{N}_]+/gu)) {
+		if (identifiers.has(match[0])) return true
+	}
+	return false
+}
 
-		results.sort((a, b) => b.updatedAt - a.updatedAt)
+/** Shared lexical ranking; a caller-owned index can omit body content. */
+export function searchMemoryEntries(
+	entries: readonly MemoryIndexEntry[],
+	params: MemorySearchParams,
+	contentOf: (id: MemoryId) => string = () => '',
+): MemorySearchResult {
+	const query = terms(params.query ?? '')
+	const identifiers = new Set(
+		params.requiredIdentifiers?.map((id) => id.normalize('NFKC').toLowerCase()),
+	)
+	if (params.query?.trim() && query.size === 0) return { entries: [], totalCount: 0 }
+	const ranked = entries
+		.filter(
+			(entry) =>
+				(!params.status || entry.status === params.status) &&
+				(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
+		)
+		.filter(
+			(entry) =>
+				!identifiers.size ||
+				[entry.id, entry.title, entry.summary, contentOf(entry.id)].some((text) =>
+					matchesMemoryIdentifier(text, identifiers),
+				),
+		)
+		.map((entry) => {
+			let coverage = 0
+			let score = 0
+			if (query.size > 0) {
+				const title = terms(entry.title)
+				const summary = terms(entry.summary)
+				const body = terms(contentOf(entry.id))
+				for (const term of query) {
+					const weight =
+						(title.has(term) ? 8 : 0) + (summary.has(term) ? 4 : 0) + (body.has(term) ? 1 : 0)
+					if (weight > 0) coverage++
+					score += weight
+				}
+			}
+			return { entry, coverage, score }
+		})
+		.filter(({ coverage }) => query.size === 0 || coverage > 0)
+		.sort(
+			(a, b) =>
+				b.coverage - a.coverage ||
+				b.score - a.score ||
+				b.entry.updatedAt - a.entry.updatedAt ||
+				(a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0),
+		)
+	return {
+		entries: ranked.slice(0, params.limit ?? ranked.length).map(({ entry }) => entry),
+		totalCount: ranked.length,
+	}
+}
 
-		const totalCount = results.length
-		const limit = params.limit ?? totalCount
+export class InMemoryMemoryIndex implements MemoryIndex {
+	private entries = new Map<string, MemoryIndexEntry>()
 
-		return {
-			entries: results.slice(0, limit),
-			totalCount,
-		}
+	search(params: MemorySearchParams): MemorySearchResult {
+		return searchMemoryEntries([...this.entries.values()], params)
 	}
 
 	getEntry(id: MemoryId): MemoryIndexEntry | undefined {

package/src/store/memory/memory.ts

@@ -3,12 +3,15 @@ import type {
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
+	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
 	MemoryStore,
+	UpdateMemoryParams,
 } from '../../types/memory/index.js'
+import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId } from '../../utils/id.js'
-import { InMemoryMemoryIndex } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
 
 export class InMemoryMemoryStore implements MemoryStore {
 	private content = new Map<string, MemoryContent>()
@@ -47,10 +50,14 @@ export class InMemoryMemoryStore implements MemoryStore {
 		return this.content.get(id)
 	}
 
-	async update(
-		id: MemoryId,
-		updates: Partial<CreateMemoryParams>,
-	): Promise<MemoryIndexEntry | undefined> {
+	async getRecord(id: MemoryId): Promise<MemoryRecord | undefined> {
+		const entry = this.index.getEntry(id)
+		const content = this.content.get(id)
+		return entry && content ? structuredClone({ entry, content }) : undefined
+	}
+
+	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		const existing = this.index.getEntry(id)
 		if (!existing) return undefined
 
@@ -61,6 +68,7 @@ export class InMemoryMemoryStore implements MemoryStore {
 			title: updates.title ?? existing.title,
 			summary: updates.summary ?? existing.summary,
 			tags: updates.tags ? [...updates.tags] : existing.tags,
+			status: updates.status ?? existing.status,
 			updatedAt: now,
 		}
 
@@ -94,7 +102,11 @@ export class InMemoryMemoryStore implements MemoryStore {
 	}
 
 	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
-		return this.index.search(params ?? {})
+		return searchMemoryEntries(
+			this.index.allEntries(),
+			params ?? {},
+			(id) => this.content.get(id)?.content ?? '',
+		)
 	}
 
 	getIndex(): InMemoryMemoryIndex {

package/src/store/memory/operation-lock.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+import { type FileHandle, lstat, open, readFile, unlink } from 'node:fs/promises'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { NamzuError } from '../../types/errors/index.js'
+
+/** Wait bound, not a lease: a slow or crashed owner is never silently replaced. */
+export const DEFAULT_MEMORY_LOCK_TIMEOUT_MS = 10_000
+
+export function validateMemoryLockTimeout(timeoutMs: number): void {
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: 'DiskMemoryStore lockTimeoutMs must be a positive safe integer.',
+			retryable: false,
+		})
+	}
+}
+
+function lockError(path: string, reason: string, timeoutMs: number): NamzuError {
+	return new NamzuError({
+		code: 'storage_error',
+		message: `Memory operation lock ${path}: ${reason}. Stop all processes using this memory store and inspect the lock owner before removing a stale lock; it is never broken automatically.`,
+		details: { lockPath: path, timeoutMs },
+		retryable: false,
+	})
+}
+
+/**
+ * Local-filesystem exclusion for cooperating processes. Atomic rename of the
+ * index alone cannot serialize the index/content read-modify-write transaction.
+ * An abandoned lock fails closed; guessing a lease expired would permit two
+ * live writers to overwrite each other again.
+ */
+export async function acquireMemoryOperationLock(
+	path: string,
+	timeoutMs: number,
+): Promise<() => Promise<void>> {
+	const deadline = performance.now() + timeoutMs
+	let attempted = false
+	for (;;) {
+		if (attempted && performance.now() >= deadline) {
+			throw lockError(path, `acquisition timed out after ${timeoutMs} ms`, timeoutMs)
+		}
+		attempted = true
+		let handle: FileHandle
+		try {
+			handle = await open(path, 'wx', 0o600)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+			const existing = await lstat(path).catch((statError: NodeJS.ErrnoException) => {
+				if (statError.code === 'ENOENT') return undefined
+				throw statError
+			})
+			if (!existing) continue
+			if (!existing.isFile() || existing.isSymbolicLink()) {
+				throw lockError(path, 'the occupied lock is not a regular file', timeoutMs)
+			}
+			if (performance.now() >= deadline) {
+				throw lockError(path, `acquisition timed out after ${timeoutMs} ms`, timeoutMs)
+			}
+			await delay(Math.min(25, Math.max(1, deadline - performance.now())))
+			continue
+		}
+
+		const owner = `${JSON.stringify({ pid: process.pid, token: randomUUID(), acquiredAt: Date.now() })}\n`
+		const identity = await handle.stat().catch(async (error: unknown) => {
+			await handle.close()
+			// Exclusive create happened, but ownership could not be established.
+			// Leave the path for explicit recovery rather than unlink an unknown inode.
+			throw error
+		})
+		try {
+			await handle.writeFile(owner, 'utf8')
+			await handle.sync()
+		} catch (error) {
+			await handle.close()
+			const current = await lstat(path).catch(() => undefined)
+			if (current?.dev === identity.dev && current.ino === identity.ino) {
+				await unlink(path).catch(() => undefined)
+			}
+			throw error
+		}
+		await handle.close()
+		return async () => {
+			const current = await lstat(path)
+			if (
+				!current.isFile() ||
+				current.isSymbolicLink() ||
+				current.dev !== identity.dev ||
+				current.ino !== identity.ino ||
+				(await readFile(path, 'utf8')) !== owner
+			) {
+				throw lockError(path, 'the lock owner changed before release', timeoutMs)
+			}
+			await unlink(path)
+		}
+	}
+}

package/src/store/run/token-budget-disk.ts

@@ -227,6 +227,9 @@ function assertSameRoot(before: TokenBudgetSnapshot, after: TokenBudgetSnapshot)
 			!current ||
 			current.accountId !== previous.accountId ||
 			current.runId !== previous.runId ||
+			(previous.unresolved === true &&
+				current.unresolved !== true &&
+				(active.has(previous.id) || current.usage === undefined)) ||
 			(reconciled && current.usage === undefined) ||
 			!usageAtLeast(current.usage, previous.usage)
 		) {