@namzu/sdk 2.0.0 → 3.0.0

package/src/session/retention/disk-backend.ts

@@ -27,13 +27,14 @@
  */
 
 import { randomBytes } from 'node:crypto'
-import { mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { SessionId, SubSessionId, TenantId } from '../../types/ids/index.js'
 import type { ArchiveBackendRef } from '../../types/retention/archive-backend-ref.js'
 import type { SessionMessage } from '../../types/session/messages.js'
 import type { SessionSummaryRef } from '../../types/summary/ref.js'
 import type { WorkspaceRef } from '../../types/workspace/ref.js'
+import { atomicWriteFile } from '../../utils/atomic-write.js'
 import type { ArchiveBackend, ArchiveInput, ArchiveOutput } from './backend.js'
 
 /**
@@ -271,16 +272,9 @@ async function atomicWriteJson(filePath: string, value: unknown): Promise<void>
 	await atomicWriteText(filePath, JSON.stringify(value, null, 2))
 }
 
-async function atomicWriteText(filePath: string, body: string): Promise<void> {
-	const tempPath = `${filePath}.tmp`
-	try {
-		await writeFile(tempPath, body, 'utf-8')
-		await rename(tempPath, filePath)
-	} catch (err) {
-		await unlink(tempPath).catch(() => undefined)
-		throw err
-	}
-}
+// Through the shared writer: the sidecar has to be private to this
+// write, and a fixed `.tmp` is shared by every writer of the record.
+const atomicWriteText = atomicWriteFile
 
 async function readJson<T>(path: string): Promise<T | null> {
 	try {

package/src/session/workspace/__tests__/git-worktree.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
+import { posix } from '../../../test-support/paths.js'
 import type { WorkspaceRef } from '../../../types/workspace/ref.js'
 import { WorkspaceBackendError } from '../../errors.js'
 import {
@@ -45,7 +46,10 @@ describe('GitWorktreeDriver', () => {
 		const call = calls[0]
 		if (!call) throw new Error('missing call')
 		expect(call.file).toBe('git')
-		expect(call.args).toEqual([
+		// `posix()` per element: the worktree path is built with `path.join`,
+		// so it is backslash-separated on Windows. The assertion is about
+		// argv shape and ordering, not separator style.
+		expect(call.args.map(posix)).toEqual([
 			'-C',
 			'/repo',
 			'worktree',
@@ -71,7 +75,7 @@ describe('GitWorktreeDriver', () => {
 		await driver.create({ label: 'bar' })
 		const call = calls[0]
 		if (!call) throw new Error('missing call')
-		expect(call.args.at(-1)).toBe('/repo/.namzu/worktrees/bar')
+		expect(posix(call.args.at(-1))).toBe('/repo/.namzu/worktrees/bar')
 	})
 
 	it('create: wraps failures in WorkspaceBackendError', async () => {

package/src/session/workspace/__tests__/shared-run.test.ts

@@ -178,4 +178,22 @@ describe('SharedRunWorkspace', () => {
 
 		expect(() => workspace.hostPath('..', 'outside')).toThrow(/escapes root/)
 	})
+
+	it('trims a pathological run of trailing slashes in linear time', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		// A long trailing-slash run with a non-slash tail is the adversarial shape for
+		// the old /\/+$/ regex: backtracking there is O(n^2) and stalls for seconds
+		// at this length. A linear trim finishes well inside the timeout.
+		const pathological = `/mnt/user-data/${'/'.repeat(200_000)}x`
+
+		const started = Date.now()
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: pathological,
+		})
+		const elapsedMs = Date.now() - started
+
+		expect(workspace.runtimeRoot).toBe(pathological)
+		expect(elapsedMs).toBeLessThan(1000)
+	}, 5000)
 })

package/src/session/workspace/shared-run.ts

@@ -287,7 +287,13 @@ function safeJoin(root: string, segments: readonly string[]): string {
 
 function trimTrailingSlash(value: string): string {
 	if (value === '/') return value
-	return value.replace(/\/+$/, '')
+	// Manual scan instead of /\/+$/: that pattern is unanchored at the start, so a
+	// backtracking engine retries the trailing-slash run from every prior index
+	// once the terminal `$` fails to match, making it O(n^2) on a long run of
+	// slashes (runtimeRoot is caller-supplied and can be arbitrarily long).
+	let end = value.length
+	while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */) end--
+	return value.slice(0, end)
 }
 
 function ensureTrailingNewline(value: string): string {

package/src/skills/__tests__/frontmatter.test.ts

@@ -0,0 +1,135 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { loadSkill } from '../loader.js'
+
+/**
+ * The frontmatter reader is a flat key/value splitter, and the documented
+ * contract says "YAML frontmatter" with no restriction — so an author has
+ * every reason to write a block scalar or a flow sequence, and no reason to
+ * expect what happened next.
+ *
+ * All three failures were silent. `description: >-` with an indented
+ * paragraph produced the literal `">-"`, which passed validation and
+ * registered with no warning: the skill existed and was never selected,
+ * because its description said nothing. `[Read, Grep]` became that literal
+ * text and was interpolated into the prompt. And a `---` inside a quoted
+ * value cut the frontmatter there, truncating the metadata AND spilling the
+ * remainder into the body, which reaches the system prompt verbatim.
+ */
+
+let dir: string
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'namzu-skill-'))
+})
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true })
+})
+
+function skill(content: string): string {
+	const skillDir = join(dir, 'a-skill')
+	mkdirSync(skillDir, { recursive: true })
+	writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8')
+	return skillDir
+}
+
+describe('the closing fence', () => {
+	it('is a line of its own, not `---` wherever it appears', async () => {
+		const path = skill(
+			[
+				'---',
+				'name: a-skill',
+				'description: "Handles the --- separator in CSV files"',
+				'---',
+				'',
+				'Body text.',
+			].join('\n'),
+		)
+
+		const loaded = await loadSkill(path, 'full')
+		// The unanchored search cut here, losing the rest of the metadata.
+		expect(loaded.skill.metadata.description).toContain('CSV')
+		expect(loaded.skill.body).toBe('Body text.')
+	})
+
+	it('does not spill frontmatter into the body', async () => {
+		const path = skill(
+			['---', 'name: a-skill', 'description: "uses --- a lot"', '---', '', 'Real body.'].join('\n'),
+		)
+
+		const loaded = await loadSkill(path, 'full')
+		// The body reaches the system prompt verbatim, so a leak here is a
+		// leak into the prompt.
+		expect(loaded.skill.body).not.toContain('description:')
+		expect(loaded.skill.body).toBe('Real body.')
+	})
+
+	it('still rejects genuinely unclosed frontmatter', async () => {
+		const path = skill(['---', 'name: a-skill', 'description: no closing fence'].join('\n'))
+		await expect(loadSkill(path, 'full')).rejects.toThrow(/unclosed/)
+	})
+})
+
+describe('YAML this reader does not implement', () => {
+	it('refuses a block scalar instead of reading it as ">-"', async () => {
+		const path = skill(
+			[
+				'---',
+				'name: a-skill',
+				'description: >-',
+				'  A long description that wraps',
+				'  across two lines.',
+				'---',
+				'',
+				'Body.',
+			].join('\n'),
+		)
+
+		// Registering this produced a skill whose description was ">-" —
+		// present, valid, and never selected by the model.
+		await expect(loadSkill(path, 'full')).rejects.toThrow(/block scalar/)
+	})
+
+	it('refuses a flow sequence instead of interpolating its text', async () => {
+		const path = skill(
+			[
+				'---',
+				'name: a-skill',
+				'description: Does a thing',
+				'allowed-tools: [Read, Grep]',
+				'---',
+			].join('\n'),
+		)
+		await expect(loadSkill(path, 'full')).rejects.toThrow(/flow sequence/)
+	})
+
+	it('names the file and the field it refused', async () => {
+		const path = skill(['---', 'name: a-skill', 'description: |', '  text', '---'].join('\n'))
+		await expect(loadSkill(path, 'full')).rejects.toThrow(/description/)
+	})
+})
+
+describe('ordinary frontmatter', () => {
+	it('still loads', async () => {
+		const path = skill(
+			['---', 'name: a-skill', 'description: Does a useful thing', '---', '', 'Body.'].join('\n'),
+		)
+
+		const loaded = await loadSkill(path, 'full')
+		expect(loaded.skill.metadata.name).toBe('a-skill')
+		expect(loaded.skill.metadata.description).toBe('Does a useful thing')
+		expect(loaded.skill.body).toBe('Body.')
+	})
+
+	it('accepts a quoted value with a colon in it', async () => {
+		const path = skill(
+			['---', 'name: a-skill', 'description: "Reads a URL: http://example.com"', '---'].join('\n'),
+		)
+		const loaded = await loadSkill(path, 'full')
+		expect(loaded.skill.metadata.description).toContain('http://example.com')
+	})
+})

package/src/skills/loader.ts

@@ -25,13 +25,19 @@ function parseSkillMd(raw: string, dirPath: string): ParsedSkillMd {
 		throw new Error(`SKILL.md at "${dirPath}" has no YAML frontmatter`)
 	}
 
-	const endIdx = trimmed.indexOf(FRONTMATTER_DELIMITER, FRONTMATTER_DELIMITER.length)
-	if (endIdx === -1) {
+	// Anchored to a line of its own. An unanchored search found `---`
+	// anywhere — inside a quoted value, inside a URL, inside prose — and cut
+	// the frontmatter there, which both truncated the metadata AND spilled
+	// the rest of the frontmatter into `body`, where it reaches the system
+	// prompt verbatim.
+	const closing = FRONTMATTER_FENCE.exec(trimmed.slice(FRONTMATTER_DELIMITER.length))
+	if (!closing) {
 		throw new Error(`SKILL.md at "${dirPath}" has unclosed frontmatter`)
 	}
 
+	const endIdx = FRONTMATTER_DELIMITER.length + closing.index
 	const frontmatterRaw = trimmed.slice(FRONTMATTER_DELIMITER.length, endIdx).trim()
-	const body = trimmed.slice(endIdx + FRONTMATTER_DELIMITER.length).trim()
+	const body = trimmed.slice(endIdx + closing[0].length).trim()
 
 	const metadata = parseFlatYaml(frontmatterRaw, dirPath)
 
@@ -62,6 +68,8 @@ function parseFlatYaml(raw: string, dirPath: string): SkillMetadata {
 		const key = line.slice(0, colonIdx).trim()
 		const value = normalizeYamlScalar(line.slice(colonIdx + 1).trim())
 
+		assertReadableScalar(key, value, dirPath)
+
 		section = key === 'metadata' ? 'metadata' : undefined
 		if (value) kv[key] = value
 	}
@@ -107,6 +115,42 @@ function normalizeYamlScalar(value: string): string {
 	return value.replace(/^["']|["']$/g, '').trim()
 }
 
+/** A closing fence is a line of its own, not `---` wherever it appears. */
+const FRONTMATTER_FENCE = /^---[ \t]*$/m
+
+/**
+ * YAML this reader does not implement, refused rather than mangled.
+ *
+ * The frontmatter reader here is a flat key/value splitter, and the
+ * documented contract says "YAML frontmatter" with no restriction — so an
+ * author has every reason to write a block scalar or a flow sequence, and
+ * no reason to expect what happened next. A `description: >-` followed by
+ * an indented paragraph produced the literal string `">-"`, which passed
+ * validation and registered with no warning; the skill then existed and
+ * was never selected, because its description said nothing. A
+ * `[Read, Grep]` became that literal text and was interpolated straight
+ * into the prompt.
+ *
+ * Refusing names the line and the file. That is worse for exactly one
+ * skill — the one already silently broken — and better for everyone
+ * looking for it.
+ */
+const UNSUPPORTED_YAML = [
+	{ pattern: /^[>|][-+]?\s*$/, what: 'a block scalar (`>` or `|`)' },
+	{ pattern: /^\[.*\]$/, what: 'a flow sequence (`[a, b]`)' },
+	{ pattern: /^\{.*\}$/, what: 'a flow mapping (`{a: b}`)' },
+] as const
+
+function assertReadableScalar(key: string, rawValue: string, dirPath: string): void {
+	const value = rawValue.trim()
+	for (const { pattern, what } of UNSUPPORTED_YAML) {
+		if (!pattern.test(value)) continue
+		throw new Error(
+			`SKILL.md at "${dirPath}": "${key}" uses ${what}, which this reader does not support. Write it as a single-line value instead. Refusing rather than registering a skill whose "${key}" would read as ${JSON.stringify(value)}.`,
+		)
+	}
+}
+
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
 function validateSkillName(name: string, dirPath: string): void {

package/src/store/__tests__/checkpoint-integrity.test.ts

@@ -0,0 +1,134 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import { RunDiskStore } from '../run/disk.js'
+
+/**
+ * A checkpoint file is the ONLY durable record of a park — there is no
+ * separate approval store. So an unreadable one that gets logged and
+ * skipped does not merely lose a resume point: `findPendingCheckpoint`
+ * reports "not parked" and drops an approval a human already granted.
+ *
+ * The listing path swallowed every per-file failure and returned a short
+ * list that four callers treat as complete. A missing newest checkpoint
+ * quietly resumes from an older one and re-runs a whole iteration of tool
+ * calls; pruning under-deletes, because a file the keep-count cannot see is
+ * immortal. The by-id read next door was already strict — two read paths
+ * disagreeing about whether damage matters is how the lenient one gets
+ * trusted.
+ */
+
+const RUN_ID = 'run_cp' as RunId
+
+let baseDir: string
+let store: RunDiskStore
+let cpDir: string
+
+beforeEach(async () => {
+	baseDir = mkdtempSync(join(tmpdir(), 'namzu-cp-'))
+	store = new RunDiskStore({ baseDir })
+	const runDir = await store.initRun(RUN_ID)
+	cpDir = join(runDir, 'checkpoints')
+	// The store creates this on first write; these tests plant files in it.
+	mkdirSync(cpDir, { recursive: true })
+})
+
+afterEach(() => {
+	rmSync(baseDir, { recursive: true, force: true })
+})
+
+function checkpoint(id: string, iteration: number): IterationCheckpoint {
+	return {
+		id: id as CheckpointId,
+		runId: RUN_ID,
+		iteration,
+		messages: [],
+		tokenUsage: {
+			promptTokens: 0,
+			completionTokens: 0,
+			totalTokens: 0,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costInfo: {
+			inputCost: 0,
+			outputCost: 0,
+			totalCost: 0,
+			inputCostPer1M: 0,
+			outputCostPer1M: 0,
+			cacheDiscount: 0,
+		},
+		guardState: { iterationCount: iteration, elapsedMs: 0 },
+		createdAt: 1_000 + iteration,
+	} as IterationCheckpoint
+}
+
+describe('a damaged checkpoint', () => {
+	it('is refused rather than skipped when listing', async () => {
+		await store.writeCheckpoint(checkpoint('cp_1', 1))
+		writeFileSync(join(cpDir, 'cp_2.json'), '{ not json', 'utf-8')
+
+		await expect(store.listCheckpoints()).rejects.toThrow()
+	})
+
+	it('does not quietly shorten the list', async () => {
+		await store.writeCheckpoint(checkpoint('cp_1', 1))
+		await store.writeCheckpoint(checkpoint('cp_2', 2))
+		expect(await store.listCheckpoints()).toHaveLength(2)
+
+		writeFileSync(join(cpDir, 'cp_2.json'), 'truncated', 'utf-8')
+		// Returning one here is the failure: the caller cannot tell it from
+		// a run that only ever had one checkpoint.
+		await expect(store.listCheckpoints()).rejects.toThrow()
+	})
+
+	it('is refused on the by-id path too', async () => {
+		writeFileSync(join(cpDir, 'cp_9.json'), '{ not json', 'utf-8')
+		await expect(store.readCheckpoint('cp_9' as CheckpointId)).rejects.toThrow()
+	})
+})
+
+describe('a file that parses but is not a checkpoint', () => {
+	it('is refused rather than resumed from', async () => {
+		writeFileSync(join(cpDir, 'cp_empty.json'), '{}', 'utf-8')
+		// This used to pass both read paths — a cast is not a check — and
+		// fail much later at the point of use, where the message names a
+		// missing property rather than a damaged file.
+		await expect(store.listCheckpoints()).rejects.toThrow(/not a usable checkpoint/)
+	})
+
+	it('names the file and what a resume needs', async () => {
+		writeFileSync(join(cpDir, 'cp_partial.json'), JSON.stringify({ id: 'x' }), 'utf-8')
+		await expect(store.readCheckpoint('cp_partial' as CheckpointId)).rejects.toThrow(
+			/cp_partial\.json/,
+		)
+	})
+})
+
+describe('the ordinary paths', () => {
+	it('still lists what is there, oldest first', async () => {
+		await store.writeCheckpoint(checkpoint('cp_2', 2))
+		await store.writeCheckpoint(checkpoint('cp_1', 1))
+
+		expect((await store.listCheckpoints()).map((c) => c.id)).toEqual(['cp_1', 'cp_2'])
+	})
+
+	it('returns an empty list when there are no checkpoints at all', async () => {
+		// Absent is not damaged, and must stay distinguishable from it.
+		expect(await store.listCheckpoints()).toEqual([])
+	})
+
+	it('returns null for a checkpoint that was never written', async () => {
+		expect(await store.readCheckpoint('cp_missing' as CheckpointId)).toBeNull()
+	})
+
+	it('ignores files that are not checkpoints', async () => {
+		await store.writeCheckpoint(checkpoint('cp_1', 1))
+		writeFileSync(join(cpDir, 'notes.txt'), 'scratch', 'utf-8')
+		expect(await store.listCheckpoints()).toHaveLength(1)
+	})
+})

package/src/store/__tests__/checkpoint-versioning.test.ts

@@ -0,0 +1,194 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import { RunDiskStore } from '../run/disk.js'
+
+/**
+ * A checkpoint was written bare and read with a cast. Two consequences,
+ * one latent and one live.
+ *
+ * Latent: an unstamped record is read as version 1 by definition, which is
+ * correct only while version 1 is the only version there has ever been.
+ * The moment a second exists, a file written by the newer build is read by
+ * the older one as if it were the older shape, and the refusal that exists
+ * to prevent exactly that never fires. There was no chain to hang a
+ * migration on.
+ *
+ * Live: the read validated `id`, `iteration`, `createdAt` and `messages`
+ * and skipped the budget fields — which a resume dereferences before its
+ * first iteration. A run recalled at $4.80 of a $5 cap whose `costInfo`
+ * came back malformed continues with `NaN`, which compares false against
+ * every limit, so the guard that exists to stop it never stops it.
+ */
+
+const RID = 'run_1' as RunId
+
+function checkpoint(overrides: Partial<IterationCheckpoint> = {}): IterationCheckpoint {
+	return {
+		id: 'cp_1' as CheckpointId,
+		runId: RID,
+		iteration: 2,
+		messages: [],
+		tokenUsage: {
+			promptTokens: 100,
+			completionTokens: 50,
+			totalTokens: 150,
+			cachedTokens: 0,
+			cacheWriteTokens: 0,
+		},
+		costInfo: { totalCost: 4.8 } as never,
+		guardState: { iterationCount: 2, elapsedMs: 1_000 },
+		createdAt: Date.now(),
+		...overrides,
+	}
+}
+
+describe('a checkpoint on disk', () => {
+	let dir: string
+	let store: RunDiskStore
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'namzu-cpver-'))
+		store = new RunDiskStore({ baseDir: dir })
+		await store.initRun(RID)
+	})
+
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true })
+	})
+
+	const writeRaw = async (name: string, record: unknown) => {
+		const cpDir = join(dir, RID, 'checkpoints')
+		await mkdir(cpDir, { recursive: true })
+		await writeFile(join(cpDir, `${name}.json`), JSON.stringify(record), 'utf-8')
+	}
+
+	it('is stamped ON DISK with the schema version it was written at', async () => {
+		await store.writeCheckpoint(checkpoint())
+
+		// Read the file, not the store: the reader re-stamps whatever it
+		// parses, so asking the store back cannot tell a stamped file from
+		// an unstamped one. The stamp only does its job if it is in the
+		// bytes another build will read.
+		const raw = JSON.parse(await readFile(join(dir, RID, 'checkpoints', 'cp_1.json'), 'utf-8')) as {
+			schemaVersion?: number
+		}
+		expect(raw.schemaVersion).toBe(1)
+	})
+
+	it('round-trips through the stamp without losing anything', async () => {
+		const original = checkpoint({ iteration: 7 })
+		await store.writeCheckpoint(original)
+
+		const read = await store.readCheckpoint(original.id)
+		expect(read?.iteration).toBe(7)
+		expect(read?.tokenUsage.totalTokens).toBe(150)
+	})
+
+	it('reads an unstamped record written before this existed', async () => {
+		// Optional-additive is the established practice here; an older file
+		// must keep working.
+		const { ...bare } = checkpoint({ id: 'cp_old' as CheckpointId })
+		await writeRaw('cp_old', bare)
+
+		expect((await store.readCheckpoint('cp_old' as CheckpointId))?.iteration).toBe(2)
+	})
+
+	it('refuses a record from a future version rather than reading it partially', async () => {
+		await writeRaw('cp_future', {
+			...checkpoint({ id: 'cp_future' as CheckpointId }),
+			schemaVersion: 99,
+		})
+
+		// Reading it with today's parser silently drops the fields this
+		// build does not know about, and writing it back loses them.
+		await expect(store.readCheckpoint('cp_future' as CheckpointId)).rejects.toThrow(
+			/schema version 99/,
+		)
+	})
+})
+
+describe('budget state a resume dereferences', () => {
+	let dir: string
+	let store: RunDiskStore
+
+	beforeEach(async () => {
+		dir = await mkdtemp(join(tmpdir(), 'namzu-cpbudget-'))
+		store = new RunDiskStore({ baseDir: dir })
+		await store.initRun(RID)
+	})
+
+	afterEach(async () => {
+		await rm(dir, { recursive: true, force: true })
+	})
+
+	const writeRaw = async (name: string, record: unknown) => {
+		const cpDir = join(dir, RID, 'checkpoints')
+		await mkdir(cpDir, { recursive: true })
+		await writeFile(join(cpDir, `${name}.json`), JSON.stringify(record), 'utf-8')
+	}
+
+	it('refuses a checkpoint with no cost information', async () => {
+		const { costInfo: _dropped, ...rest } = checkpoint({ id: 'cp_nocost' as CheckpointId })
+		await writeRaw('cp_nocost', rest)
+
+		// A run that resumes with an undefined cap is worse than one that
+		// refuses to resume: it looks healthy and never stops.
+		await expect(store.readCheckpoint('cp_nocost' as CheckpointId)).rejects.toThrow(
+			/malformed budget state/,
+		)
+	})
+
+	it('refuses a NaN budget, which compares false against every limit', async () => {
+		await writeRaw('cp_nan', {
+			...checkpoint({ id: 'cp_nan' as CheckpointId }),
+			// JSON has no NaN; this is what a serialized one becomes.
+			costInfo: { totalCost: null },
+		})
+
+		await expect(store.readCheckpoint('cp_nan' as CheckpointId)).rejects.toThrow(
+			/malformed budget state/,
+		)
+	})
+
+	it('refuses a missing guard state', async () => {
+		const { guardState: _dropped, ...rest } = checkpoint({ id: 'cp_noguard' as CheckpointId })
+		await writeRaw('cp_noguard', rest)
+
+		await expect(store.readCheckpoint('cp_noguard' as CheckpointId)).rejects.toThrow(
+			/malformed budget state/,
+		)
+	})
+
+	it('applies the same refusal to the listing path', async () => {
+		// Two read paths disagreeing about whether damage matters is how the
+		// lenient one gets trusted.
+		const { costInfo: _dropped, ...rest } = checkpoint({ id: 'cp_listed' as CheckpointId })
+		await writeRaw('cp_listed', rest)
+
+		await expect(store.listCheckpoints()).rejects.toThrow(/malformed budget state/)
+	})
+
+	it('accepts a zero budget, which is a real value', async () => {
+		await store.writeCheckpoint(
+			checkpoint({
+				id: 'cp_zero' as CheckpointId,
+				tokenUsage: {
+					promptTokens: 0,
+					completionTokens: 0,
+					totalTokens: 0,
+					cachedTokens: 0,
+					cacheWriteTokens: 0,
+				},
+				costInfo: { totalCost: 0 } as never,
+				guardState: { iterationCount: 0, elapsedMs: 0 },
+			}),
+		)
+
+		expect(await store.readCheckpoint('cp_zero' as CheckpointId)).not.toBeNull()
+	})
+})