@namzu/sdk 12.2.0 → 13.0.0

package/src/store/session/disk.ts

@@ -23,7 +23,7 @@
 
 import { appendFile, mkdir, readFile, readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
-import { TenantIsolationError } from '../../session/errors.js'
+import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
@@ -308,7 +308,11 @@ export class DiskSessionStore implements SessionStore {
 		return results
 	}
 
-	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
+	async updateSession(
+		session: Session,
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
+	): Promise<void> {
 		const located = await this.locateSession(session.id)
 		if (!located) {
 			throw new Error(`Session ${session.id} not found`)
@@ -323,6 +327,21 @@ export class DiskSessionStore implements SessionStore {
 		if (existing) {
 			this.assertTenant(existing.tenantId, tenantId, `session(${session.id})`)
 		}
+		// Against what is on disk, not against the payload. The write itself is
+		// atomic; this read-compare-write is NOT a critical section, so two
+		// processes can still both pass — see the contract note on
+		// `SessionStore.updateSession`. In one process it is the real lock.
+		if (
+			expectedOwnerVersion !== undefined &&
+			existing !== null &&
+			existing.ownerVersion !== expectedOwnerVersion
+		) {
+			throw new StaleSessionError({
+				sessionId: session.id,
+				expectedVersion: expectedOwnerVersion,
+				actualVersion: existing.ownerVersion,
+			})
+		}
 		const updated: Session = { ...session, updatedAt: new Date() }
 		await atomicWriteJson(join(located.path, 'session.json'), serializeSession(updated))
 	}

package/src/store/session/memory.ts

@@ -8,7 +8,7 @@
  * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
  */
 
-import { TenantIsolationError } from '../../session/errors.js'
+import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
@@ -151,7 +151,11 @@ export class InMemorySessionStore implements SessionStore {
 		return matches
 	}
 
-	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
+	async updateSession(
+		session: Session,
+		tenantId: TenantId,
+		expectedOwnerVersion?: number,
+	): Promise<void> {
 		const record = this.sessions.get(session.id)
 		if (!record) {
 			throw new Error(`Session ${session.id} not found`)
@@ -163,6 +167,20 @@ export class InMemorySessionStore implements SessionStore {
 				resource: `session(${session.id}) payload`,
 			})
 		}
+		// Compared against the STORED version, not against `session.ownerVersion`
+		// — the payload is the caller's copy, and comparing it to itself is
+		// precisely the check the handoff path was already making and getting
+		// nothing from.
+		if (
+			expectedOwnerVersion !== undefined &&
+			record.session.ownerVersion !== expectedOwnerVersion
+		) {
+			throw new StaleSessionError({
+				sessionId: session.id,
+				expectedVersion: expectedOwnerVersion,
+				actualVersion: record.session.ownerVersion,
+			})
+		}
 		this.sessions.set(session.id, { tenantId, session: { ...session, updatedAt: new Date() } })
 	}
 

package/src/types/session/store.ts

@@ -105,7 +105,34 @@ export interface SessionStore {
 
 	getSession(sessionId: SessionId, tenantId: TenantId): Promise<Session | null>
 
-	updateSession(session: Session, tenantId: TenantId): Promise<void>
+	/**
+	 * Write a Session back, optionally only if nobody else wrote it first.
+	 *
+	 * **`expectedOwnerVersion` is the single-writer lock this level is supposed
+	 * to own, and it did not exist.** `Session.ownerVersion` is documented as
+	 * the CAS counter for handoff, but nothing enforced it: both stores
+	 * overwrote unconditionally, and the handoff's own check compared a
+	 * snapshot it had read several awaits earlier against itself. Two
+	 * concurrent handoffs on one idle session both passed, both provisioned a
+	 * worktree, and one silently erased the other.
+	 *
+	 * Supply it and the store compares against the version it HAS STORED —
+	 * not against the payload, which is the caller's stale copy — and throws
+	 * {@link StaleSessionError} rather than writing. Omit it and the behaviour
+	 * is exactly what it always was, which is the compatibility promise: this
+	 * parameter is optional so that widening the interface stays invisible to
+	 * callers and harmless to hosts implementing their own store. A required
+	 * parameter would break every implementor for a guarantee they can opt
+	 * into.
+	 *
+	 * **In-process only, stated rather than implied.** `DiskSessionStore`
+	 * writes atomically, but its read-compare-write is not a critical section,
+	 * so two PROCESSES can still both pass the check. Closing that needs a
+	 * lease with an expiry — not a PID registry, because a Session is durable
+	 * and written from hosts where a PID is not a checkable fact. The same
+	 * honesty the spawn lock already carries.
+	 */
+	updateSession(session: Session, tenantId: TenantId, expectedOwnerVersion?: number): Promise<void>
 
 	/**
 	 * List every Session that belongs to the given Thread for the caller's