@namzu/sdk 0.4.1 → 0.4.3

package/src/bus/index.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `AgentBus` composes a `FileLockManager`, `EditOwnershipTracker`,
+ *     and `CircuitBreaker`; every event each of them emits is
+ *     broadcast to bus-level listeners.
+ *   - `on(listener)` returns an unsubscribe function; invoking it
+ *     removes the listener, and subsequent events skip it.
+ *   - Listeners receive events in the order they are emitted
+ *     (preserved by `Set` insertion-order iteration). Multi-listener
+ *     fan-out: every listener sees every event.
+ *   - A throwing listener does NOT cascade — other listeners still
+ *     receive the same event, and the bus logs the error via
+ *     `log.error`.
+ *   - No per-tenant routing — events are global to the bus instance
+ *     (design.md §2.1 aspirational per-tenant ordering does not
+ *     exist; see §2.7).
+ *   - `cleanupAgent(runId)` releases every lock + every ownership +
+ *     resets the breaker for that runId. Counts are logged; the
+ *     method does not return them.
+ *   - `maintenance()` expires stale locks via `locks.expireStale()`
+ *     and logs the count when non-zero.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { AgentBus } from './index.js'
+
+function makeLogger(): Logger {
+	// Recursive self-returning child — AgentBus nests FileLockManager /
+	// EditOwnershipTracker / CircuitBreaker, each of which chains a
+	// `log.child(...)` call in its constructor.
+	const self = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: vi.fn(),
+	} as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+describe('AgentBus', () => {
+	let bus: AgentBus
+	let log: Logger
+
+	beforeEach(() => {
+		log = makeLogger()
+		bus = new AgentBus(log, { lockTimeoutMs: 60_000, lockAcquireTimeoutMs: 60 })
+	})
+
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	describe('listener lifecycle', () => {
+		it('broadcasts events to every registered listener', async () => {
+			const a: AgentBusEvent[] = []
+			const b: AgentBusEvent[] = []
+			bus.on((e) => a.push(e))
+			bus.on((e) => b.push(e))
+
+			await bus.locks.acquire('/tmp/f.txt', runId(1))
+
+			expect(a.length).toBeGreaterThan(0)
+			expect(b).toEqual(a)
+		})
+
+		it('unsubscribe removes the listener; later events skip it', async () => {
+			const seen: AgentBusEvent[] = []
+			const off = bus.on((e) => seen.push(e))
+
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			const countAfterFirst = seen.length
+			expect(countAfterFirst).toBeGreaterThan(0)
+
+			off()
+			await bus.locks.acquire('/tmp/b.txt', runId(1))
+			expect(seen.length).toBe(countAfterFirst)
+		})
+
+		it('preserves emission order per listener (Set insertion-order iteration)', async () => {
+			const seen: string[] = []
+			bus.on((e) => seen.push(e.type))
+
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			bus.ownership.claim('/tmp/a.txt', runId(1))
+			bus.ownership.release('/tmp/a.txt', runId(1))
+			bus.locks.release('/tmp/a.txt', runId(1))
+
+			expect(seen).toEqual([
+				'lock_acquired',
+				'ownership_claimed',
+				'ownership_released',
+				'lock_released',
+			])
+		})
+
+		it('a throwing listener does not cascade — other listeners still fire', async () => {
+			const good: AgentBusEvent[] = []
+			bus.on(() => {
+				throw new Error('boom')
+			})
+			bus.on((e) => good.push(e))
+
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			expect(good.length).toBeGreaterThan(0)
+		})
+	})
+
+	describe('composed sub-components', () => {
+		it('CircuitBreaker events flow through the bus listener', () => {
+			const seen: AgentBusEvent[] = []
+			bus.on((e) => seen.push(e))
+
+			for (let i = 0; i < 5; i++) bus.breaker.recordFailure(runId(1))
+			expect(seen.filter((e) => e.type === 'breaker_tripped')).toHaveLength(1)
+		})
+
+		it('EditOwnershipTracker events flow through the bus listener', () => {
+			const seen: AgentBusEvent[] = []
+			bus.on((e) => seen.push(e))
+
+			bus.ownership.claim('/tmp/a.txt', runId(1))
+			bus.ownership.transfer('/tmp/a.txt', runId(1), runId(2))
+			bus.ownership.release('/tmp/a.txt', runId(2))
+
+			expect(seen.map((e) => e.type)).toEqual([
+				'ownership_claimed',
+				'ownership_transferred',
+				'ownership_released',
+			])
+		})
+	})
+
+	describe('cleanupAgent', () => {
+		it('releases locks + ownerships + resets breaker for the runId', async () => {
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			bus.ownership.claim('/tmp/a.txt', runId(1))
+			for (let i = 0; i < 5; i++) bus.breaker.recordFailure(runId(1))
+			expect(bus.breaker.getSnapshot(runId(1))?.state).toBe('open')
+			expect(bus.locks.isLocked('/tmp/a.txt')).toBe(true)
+
+			bus.cleanupAgent(runId(1))
+
+			expect(bus.locks.isLocked('/tmp/a.txt')).toBe(false)
+			expect(bus.ownership.getOwner('/tmp/a.txt')).toBeUndefined()
+			expect(bus.breaker.getSnapshot(runId(1))?.state).toBe('closed')
+		})
+
+		it('does not affect other runIds', async () => {
+			await bus.locks.acquire('/tmp/a.txt', runId(1))
+			await bus.locks.acquire('/tmp/b.txt', runId(2))
+
+			bus.cleanupAgent(runId(1))
+
+			expect(bus.locks.isLocked('/tmp/a.txt')).toBe(false)
+			expect(bus.locks.isLocked('/tmp/b.txt')).toBe(true)
+			expect(bus.locks.getHolder('/tmp/b.txt')).toBe(runId(2))
+		})
+	})
+
+	describe('maintenance', () => {
+		it('sweeps expired locks', async () => {
+			vi.useFakeTimers()
+			const b = new AgentBus(makeLogger(), { lockTimeoutMs: 500, lockAcquireTimeoutMs: 30 })
+			await b.locks.acquire('/tmp/a.txt', runId(1))
+			vi.advanceTimersByTime(501)
+
+			b.maintenance()
+			expect(b.locks.isLocked('/tmp/a.txt')).toBe(false)
+		})
+	})
+})

package/src/bus/lock.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `acquire(path, owner)` returns immediately when the file is
+ *     unlocked; creates a lock with `lockId = lock_<uuid>`,
+ *     `expiresAt = now + lockTimeoutMs`, emits `lock_acquired`.
+ *   - `acquire` on a file already held by the SAME owner is idempotent
+ *     — returns `{acquired: true, lock}` (the existing lock) and emits
+ *     nothing.
+ *   - `acquire` on a file held by a DIFFERENT owner emits `lock_denied`
+ *     and then polls at `LOCK_ACQUIRE_POLL_INTERVAL_MS` (100ms) intervals
+ *     until either the holder releases, the lock expires, or
+ *     `acquireTimeoutMs` elapses. No FIFO queue; retries race.
+ *   - When the holder releases before the deadline, the waiting acquire
+ *     succeeds on its next poll.
+ *   - When `acquireTimeoutMs` elapses, acquire returns
+ *     `{acquired: false, holder, filePath}` — holder is the current
+ *     lock holder's owner if the lock still exists, else empty string.
+ *   - `maxLocksPerAgent` blocks further acquisitions by the same owner.
+ *     The internal `tryAcquire` returns `{holder: owner}` (a
+ *     "yourself" sentinel) but the public `acquire()` swallows that and
+ *     keeps polling for `acquireTimeoutMs` (there's no short-circuit
+ *     for cap-exceeded). When the deadline expires and no lock exists
+ *     on the file, the final `holder` is `''` (empty `RunId`) because
+ *     the fallback reads `this.locks.get(filePath)?.owner ?? ''`.
+ *   - `release(path, owner)` deletes the lock + emits `lock_released`
+ *     when the current lock's owner matches; cleans up the per-owner
+ *     lock set (and prunes the set entry when it becomes empty).
+ *     Returns false without emitting when no lock or owner mismatch.
+ *   - `releaseAll(owner)` drops every lock owned by `owner`, emits
+ *     `lock_released` per lock, returns the count, and prunes the
+ *     per-owner set.
+ *   - `isLocked(path)` + `getHolder(path)` auto-expire any stale lock
+ *     they observe (and emit `lock_expired`) before returning the
+ *     current state.
+ *   - `expireStale()` sweeps every lock; expired ones are deleted and
+ *     emit `lock_expired`; returns the count.
+ *   - Re-acquiring a path after its lock expires succeeds and assigns
+ *     a FRESH `lockId` (the old id is never reused).
+ *   - Lock state is per-`RunId`; no tenant dimension (design.md §2.1
+ *     aspirational).
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { FileLockManager } from './lock.js'
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+function makeManager(
+	overrides: Partial<{
+		lockTimeoutMs: number
+		acquireTimeoutMs: number
+		maxLocksPerAgent: number
+	}> = {},
+) {
+	const events: AgentBusEvent[] = []
+	const mgr = new FileLockManager(makeLogger(), (e) => events.push(e), {
+		// short defaults keep acquire-retry tests under a second total
+		lockTimeoutMs: 60_000,
+		acquireTimeoutMs: 200,
+		maxLocksPerAgent: 10,
+		...overrides,
+	})
+	return { mgr, events }
+}
+
+describe('FileLockManager', () => {
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	describe('acquire (happy path)', () => {
+		it('acquires an unheld lock immediately + emits lock_acquired', async () => {
+			const { mgr, events } = makeManager()
+			const before = Date.now()
+			const result = await mgr.acquire('/tmp/a.txt', runId(1))
+			expect(result.acquired).toBe(true)
+			if (result.acquired) {
+				expect(result.lock.owner).toBe(runId(1))
+				expect(result.lock.filePath).toBe('/tmp/a.txt')
+				expect(result.lock.lockId).toMatch(/^lock_[0-9a-f-]+$/)
+				expect(result.lock.acquiredAt).toBeGreaterThanOrEqual(before)
+				expect(result.lock.expiresAt).toBeGreaterThan(result.lock.acquiredAt)
+			}
+			const acquired = events.filter((e) => e.type === 'lock_acquired')
+			expect(acquired).toHaveLength(1)
+		})
+
+		it('is idempotent for the same owner — returns the existing lock, emits nothing', async () => {
+			const { mgr, events } = makeManager()
+			const first = await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+			const second = await mgr.acquire('/tmp/a.txt', runId(1))
+			expect(second.acquired).toBe(true)
+			if (first.acquired && second.acquired) {
+				expect(second.lock.lockId).toBe(first.lock.lockId)
+			}
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('acquire (contention)', () => {
+		it('emits lock_denied when another owner holds the lock and no release happens', async () => {
+			const { mgr, events } = makeManager({ acquireTimeoutMs: 120 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+
+			const result = await mgr.acquire('/tmp/a.txt', runId(2))
+			expect(result.acquired).toBe(false)
+			if (!result.acquired) {
+				expect(result.holder).toBe(runId(1))
+				expect(result.filePath).toBe('/tmp/a.txt')
+			}
+			expect(events.some((e) => e.type === 'lock_denied')).toBe(true)
+		})
+
+		it('succeeds on a retry once the holder releases before the deadline', async () => {
+			const { mgr } = makeManager({ acquireTimeoutMs: 500 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+
+			const contender = mgr.acquire('/tmp/a.txt', runId(2))
+			setTimeout(() => mgr.release('/tmp/a.txt', runId(1)), 120)
+
+			const result = await contender
+			expect(result.acquired).toBe(true)
+			if (result.acquired) expect(result.lock.owner).toBe(runId(2))
+		})
+	})
+
+	describe('maxLocksPerAgent cap', () => {
+		it('denies a new acquisition when the owner is at cap — acquire polls to deadline then returns empty holder', async () => {
+			const { mgr } = makeManager({ maxLocksPerAgent: 2, acquireTimeoutMs: 60 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			await mgr.acquire('/tmp/b.txt', runId(1))
+
+			const over = await mgr.acquire('/tmp/c.txt', runId(1))
+			expect(over.acquired).toBe(false)
+			if (!over.acquired) {
+				// No lock exists on /tmp/c.txt, so the fallback holder is ''.
+				expect(over.holder).toBe('' as RunId)
+				expect(over.filePath).toBe('/tmp/c.txt')
+			}
+		})
+	})
+
+	describe('release', () => {
+		it('releases an owned lock + emits lock_released', async () => {
+			const { mgr, events } = makeManager()
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+
+			expect(mgr.release('/tmp/a.txt', runId(1))).toBe(true)
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(false)
+			expect(events.some((e) => e.type === 'lock_released')).toBe(true)
+		})
+
+		it('returns false + emits nothing when the caller is not the holder', async () => {
+			const { mgr, events } = makeManager()
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			events.length = 0
+
+			expect(mgr.release('/tmp/a.txt', runId(2))).toBe(false)
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(true)
+			expect(events).toEqual([])
+		})
+
+		it('returns false when no lock exists', () => {
+			const { mgr, events } = makeManager()
+			expect(mgr.release('/tmp/never.txt', runId(1))).toBe(false)
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('releaseAll', () => {
+		it('drops every lock owned by the runId, emits one event per lock, returns count', async () => {
+			const { mgr, events } = makeManager()
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			await mgr.acquire('/tmp/b.txt', runId(1))
+			await mgr.acquire('/tmp/c.txt', runId(2))
+			events.length = 0
+
+			const count = mgr.releaseAll(runId(1))
+			expect(count).toBe(2)
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(false)
+			expect(mgr.isLocked('/tmp/b.txt')).toBe(false)
+			expect(mgr.isLocked('/tmp/c.txt')).toBe(true)
+			expect(events.filter((e) => e.type === 'lock_released')).toHaveLength(2)
+		})
+
+		it('returns 0 when the owner has no locks', () => {
+			const { mgr } = makeManager()
+			expect(mgr.releaseAll(runId(99))).toBe(0)
+		})
+	})
+
+	describe('expiry', () => {
+		it('expireStale drops expired locks + emits lock_expired per drop', async () => {
+			vi.useFakeTimers()
+			const { mgr, events } = makeManager({ lockTimeoutMs: 10_000 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+			await mgr.acquire('/tmp/b.txt', runId(2))
+			events.length = 0
+
+			vi.advanceTimersByTime(10_001)
+			const expired = mgr.expireStale()
+			expect(expired).toBe(2)
+			expect(events.filter((e) => e.type === 'lock_expired')).toHaveLength(2)
+		})
+
+		it('isLocked / getHolder auto-expire a stale lock before answering', async () => {
+			vi.useFakeTimers()
+			const { mgr, events } = makeManager({ lockTimeoutMs: 5_000 })
+			await mgr.acquire('/tmp/a.txt', runId(1))
+
+			vi.advanceTimersByTime(5_001)
+			events.length = 0
+			expect(mgr.isLocked('/tmp/a.txt')).toBe(false)
+			expect(events.some((e) => e.type === 'lock_expired')).toBe(true)
+
+			events.length = 0
+			expect(mgr.getHolder('/tmp/a.txt')).toBeUndefined()
+			// already expired by the previous call; no second emit
+			expect(events).toEqual([])
+		})
+
+		it('a fresh acquire after expiry assigns a new lockId', async () => {
+			vi.useFakeTimers()
+			const { mgr } = makeManager({ lockTimeoutMs: 1_000 })
+			const first = await mgr.acquire('/tmp/a.txt', runId(1))
+			vi.advanceTimersByTime(1_001)
+			mgr.expireStale()
+
+			vi.useRealTimers()
+			const second = await mgr.acquire('/tmp/a.txt', runId(2))
+			expect(first.acquired && second.acquired).toBe(true)
+			if (first.acquired && second.acquired) {
+				expect(second.lock.lockId).not.toBe(first.lock.lockId)
+				expect(second.lock.owner).toBe(runId(2))
+			}
+		})
+	})
+
+	describe('per-runId isolation', () => {
+		it('different runIds can hold locks on different files concurrently', async () => {
+			const { mgr } = makeManager()
+			const a = await mgr.acquire('/tmp/a.txt', runId(1))
+			const b = await mgr.acquire('/tmp/b.txt', runId(2))
+			expect(a.acquired && b.acquired).toBe(true)
+			expect(mgr.getHolder('/tmp/a.txt')).toBe(runId(1))
+			expect(mgr.getHolder('/tmp/b.txt')).toBe(runId(2))
+		})
+	})
+})

package/src/bus/ownership.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 1):
+ *
+ *   - `claim(path, owner)` on an unowned file creates ownership, emits
+ *     `ownership_claimed`, returns `{claimed: true, ownership}`.
+ *   - `claim(path, owner)` by the same owner is idempotent — returns
+ *     `{claimed: true, ownership}` WITHOUT re-emitting.
+ *   - `claim(path, owner)` by a different owner is denied — emits
+ *     `ownership_denied`, returns `{claimed: false, currentOwner, filePath}`.
+ *   - `release(path, owner)` on the current owner deletes + emits; returns
+ *     true. On mismatch or missing entry: returns false; no emit.
+ *   - `transfer(path, from, to)` requires the current owner to equal
+ *     `from`. Success replaces the entry with a new `claimedAt`, emits
+ *     `ownership_transferred`; no intervening `ownership_released` or
+ *     `ownership_claimed` events. Failure returns false; no emit.
+ *   - `releaseAll(owner)` sweeps every ownership for `owner`, emits
+ *     `ownership_released` per entry, returns the count. Other owners'
+ *     entries are untouched.
+ *   - File paths are normalised via `path.resolve` before keying —
+ *     `./foo/bar` and the absolute resolution of the same path collide
+ *     into one ownership slot.
+ *   - Ownership is not per-tenant; only per-`RunId`. There is no tenant
+ *     isolation at this layer (design.md §2.1 aspirational; see §2.7).
+ */
+
+import path from 'node:path'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { AgentBusEvent } from '../types/bus/index.js'
+import type { RunId } from '../types/ids/index.js'
+import type { Logger } from '../utils/logger.js'
+
+import { EditOwnershipTracker } from './ownership.js'
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+function runId(n: number): RunId {
+	return `run_${n}` as RunId
+}
+
+describe('EditOwnershipTracker', () => {
+	let events: AgentBusEvent[]
+	let tracker: EditOwnershipTracker
+
+	beforeEach(() => {
+		events = []
+		tracker = new EditOwnershipTracker(makeLogger(), (e) => events.push(e))
+	})
+
+	describe('claim', () => {
+		it('claims an unowned file, emits ownership_claimed, returns ownership', () => {
+			const before = Date.now()
+			const result = tracker.claim('/tmp/file.txt', runId(1))
+			const after = Date.now()
+
+			expect(result.claimed).toBe(true)
+			if (result.claimed) {
+				expect(result.ownership.owner).toBe(runId(1))
+				expect(result.ownership.filePath).toBe(path.resolve('/tmp/file.txt'))
+				expect(result.ownership.claimedAt).toBeGreaterThanOrEqual(before)
+				expect(result.ownership.claimedAt).toBeLessThanOrEqual(after)
+			}
+			expect(events).toEqual([
+				{ type: 'ownership_claimed', filePath: path.resolve('/tmp/file.txt'), owner: runId(1) },
+			])
+		})
+
+		it('is idempotent when the same owner re-claims — no re-emit', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const result = tracker.claim('/tmp/file.txt', runId(1))
+			expect(result.claimed).toBe(true)
+			expect(events).toEqual([])
+		})
+
+		it('denies a claim by a different owner, emits ownership_denied', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const result = tracker.claim('/tmp/file.txt', runId(2))
+			expect(result.claimed).toBe(false)
+			if (!result.claimed) {
+				expect(result.currentOwner).toBe(runId(1))
+				expect(result.filePath).toBe(path.resolve('/tmp/file.txt'))
+			}
+			expect(events).toEqual([
+				{
+					type: 'ownership_denied',
+					filePath: path.resolve('/tmp/file.txt'),
+					requester: runId(2),
+					currentOwner: runId(1),
+				},
+			])
+		})
+
+		it('normalises file paths — equivalent paths collide', () => {
+			tracker.claim('/tmp/foo/../file.txt', runId(1))
+			const result = tracker.claim('/tmp/file.txt', runId(2))
+			expect(result.claimed).toBe(false)
+		})
+	})
+
+	describe('release', () => {
+		it('releases an owned file, emits ownership_released, returns true', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.release('/tmp/file.txt', runId(1))
+			expect(ok).toBe(true)
+			expect(tracker.getOwner('/tmp/file.txt')).toBeUndefined()
+			expect(events).toEqual([
+				{
+					type: 'ownership_released',
+					filePath: path.resolve('/tmp/file.txt'),
+					previousOwner: runId(1),
+				},
+			])
+		})
+
+		it('returns false when no ownership exists — no emit', () => {
+			const ok = tracker.release('/tmp/never-claimed.txt', runId(1))
+			expect(ok).toBe(false)
+			expect(events).toEqual([])
+		})
+
+		it('returns false when owner mismatches — no emit', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.release('/tmp/file.txt', runId(2))
+			expect(ok).toBe(false)
+			expect(tracker.getOwner('/tmp/file.txt')).toBe(runId(1))
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('transfer', () => {
+		it('transfers ownership from current owner to another — atomic, single event', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.transfer('/tmp/file.txt', runId(1), runId(2))
+			expect(ok).toBe(true)
+			expect(tracker.getOwner('/tmp/file.txt')).toBe(runId(2))
+			expect(events).toEqual([
+				{
+					type: 'ownership_transferred',
+					filePath: path.resolve('/tmp/file.txt'),
+					from: runId(1),
+					to: runId(2),
+				},
+			])
+		})
+
+		it('returns false when the `from` argument is not the current owner — no emit', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			events.length = 0
+
+			const ok = tracker.transfer('/tmp/file.txt', runId(99), runId(2))
+			expect(ok).toBe(false)
+			expect(tracker.getOwner('/tmp/file.txt')).toBe(runId(1))
+			expect(events).toEqual([])
+		})
+
+		it('returns false when no ownership exists — no emit', () => {
+			const ok = tracker.transfer('/tmp/file.txt', runId(1), runId(2))
+			expect(ok).toBe(false)
+			expect(events).toEqual([])
+		})
+
+		it('refreshes claimedAt on successful transfer', async () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			const t0 = tracker.getOwner('/tmp/file.txt')
+			expect(t0).toBe(runId(1))
+
+			await new Promise((r) => setTimeout(r, 2))
+			tracker.transfer('/tmp/file.txt', runId(1), runId(2))
+			const list = tracker.listByOwner(runId(2))
+			expect(list).toHaveLength(1)
+			const after = list[0]
+			expect(after?.claimedAt).toBeGreaterThan(0)
+			expect(after?.owner).toBe(runId(2))
+		})
+	})
+
+	describe('releaseAll', () => {
+		it('releases every ownership for the owner, returns count, emits per-entry', () => {
+			tracker.claim('/tmp/a.txt', runId(1))
+			tracker.claim('/tmp/b.txt', runId(1))
+			tracker.claim('/tmp/c.txt', runId(2))
+			events.length = 0
+
+			const count = tracker.releaseAll(runId(1))
+			expect(count).toBe(2)
+			expect(tracker.getOwner('/tmp/a.txt')).toBeUndefined()
+			expect(tracker.getOwner('/tmp/b.txt')).toBeUndefined()
+			expect(tracker.getOwner('/tmp/c.txt')).toBe(runId(2))
+
+			const released = events.filter((e) => e.type === 'ownership_released')
+			expect(released.length).toBe(2)
+			for (const e of released) {
+				if (e.type === 'ownership_released') {
+					expect(e.previousOwner).toBe(runId(1))
+				}
+			}
+		})
+
+		it('returns 0 when the owner has no entries', () => {
+			const count = tracker.releaseAll(runId(99))
+			expect(count).toBe(0)
+			expect(events).toEqual([])
+		})
+	})
+
+	describe('read helpers', () => {
+		it('getOwner returns undefined for unclaimed paths', () => {
+			expect(tracker.getOwner('/tmp/anything.txt')).toBeUndefined()
+		})
+
+		it('listByOwner returns all ownerships for a given owner', () => {
+			tracker.claim('/tmp/a.txt', runId(1))
+			tracker.claim('/tmp/b.txt', runId(1))
+			tracker.claim('/tmp/c.txt', runId(2))
+
+			const list = tracker.listByOwner(runId(1))
+			expect(list.length).toBe(2)
+			expect(new Set(list.map((o) => o.filePath))).toEqual(
+				new Set([path.resolve('/tmp/a.txt'), path.resolve('/tmp/b.txt')]),
+			)
+		})
+
+		it('checkConflict returns the current owner iff a different owner holds the file', () => {
+			tracker.claim('/tmp/file.txt', runId(1))
+			expect(tracker.checkConflict('/tmp/file.txt', runId(1))).toBeUndefined()
+			expect(tracker.checkConflict('/tmp/file.txt', runId(2))).toBe(runId(1))
+			expect(tracker.checkConflict('/tmp/other.txt', runId(2))).toBeUndefined()
+		})
+	})
+})

package/src/config/runtime.ts

@@ -51,8 +51,6 @@ export const PromptCacheConfigSchema = z.object({
 	strategy: z.enum(['auto', 'disabled']).default('auto'),
 })
 
-export type PromptCacheConfig = z.infer<typeof PromptCacheConfigSchema>
-
 export const PluginRuntimeConfigSchema = z.object({
 	enabled: z.boolean().default(false),
 	autoDiscovery: z.boolean().default(true),