@methodts/runtime 0.1.0

package/dist/sessions/scope-hook.test.js

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import os from 'node:os';
+import { generateHookScript, installScopeHook, isPathAllowed, matchGlobPattern, } from './scope-hook.js';
+// ── Hook Script Generation Tests ──────────────────────────────
+describe('generateHookScript (PRD 014)', () => {
+    it('generates a no-op script when allowed_paths is empty', () => {
+        const script = generateHookScript('test-session', []);
+        assert.ok(script.includes('exit 0'));
+        assert.ok(script.includes('No scope constraints'));
+    });
+    it('generates a script with pattern matching for single pattern', () => {
+        const script = generateHookScript('sess-001', ['packages/bridge/**']);
+        assert.ok(script.includes('#!/usr/bin/env bash'));
+        assert.ok(script.includes('PRD 014'));
+        assert.ok(script.includes('sess-001'));
+        assert.ok(script.includes('packages/bridge/**'));
+        assert.ok(script.includes('SCOPE VIOLATION'));
+        assert.ok(script.includes('ALLOWED_PATTERNS'));
+        assert.ok(script.includes('git diff --cached --name-only'));
+    });
+    it('generates a script with multiple patterns', () => {
+        const script = generateHookScript('sess-002', [
+            'packages/bridge/src/**',
+            'packages/bridge/src/__tests__/**',
+            'docs/prds/*.md',
+        ]);
+        assert.ok(script.includes('packages/bridge/src/**'));
+        assert.ok(script.includes('packages/bridge/src/__tests__/**'));
+        assert.ok(script.includes('docs/prds/*.md'));
+    });
+    it('escapes single quotes in patterns', () => {
+        const script = generateHookScript('sess-003', ["it's/a/path"]);
+        // Pattern should be properly escaped in bash
+        assert.ok(script.includes("it"));
+        assert.ok(script.includes("ALLOWED_PATTERNS"));
+    });
+    it('includes session ID in comments for traceability', () => {
+        const script = generateHookScript('abc-def-123', ['src/**']);
+        assert.ok(script.includes('Session: abc-def-123'));
+    });
+    it('includes glob_to_regex function for pattern matching', () => {
+        const script = generateHookScript('sess-004', ['src/**']);
+        assert.ok(script.includes('glob_to_regex'));
+    });
+});
+// ── Glob Pattern Matching Tests (TypeScript) ──────────────────
+describe('matchGlobPattern (PRD 014)', () => {
+    it('matches simple file extension wildcard', () => {
+        assert.ok(matchGlobPattern('src/index.ts', '*.ts'));
+        assert.ok(!matchGlobPattern('src/index.ts', '*.js'));
+    });
+    it('matches * within a directory (no path separators)', () => {
+        assert.ok(matchGlobPattern('docs/guide.md', 'docs/*.md'));
+        assert.ok(!matchGlobPattern('docs/sub/guide.md', 'docs/*.md'));
+    });
+    it('matches ** for any depth', () => {
+        assert.ok(matchGlobPattern('packages/bridge/src/index.ts', 'packages/bridge/**'));
+        assert.ok(matchGlobPattern('packages/bridge/src/deep/nested/file.ts', 'packages/bridge/**'));
+        assert.ok(matchGlobPattern('packages/bridge/file.ts', 'packages/bridge/**'));
+    });
+    it('matches **/ prefix for any directory depth', () => {
+        assert.ok(matchGlobPattern('packages/bridge/src/index.ts', 'packages/**/index.ts'));
+        assert.ok(matchGlobPattern('packages/index.ts', 'packages/**/index.ts'));
+    });
+    it('does not match paths outside pattern scope', () => {
+        assert.ok(!matchGlobPattern('packages/core/src/index.ts', 'packages/bridge/**'));
+        assert.ok(!matchGlobPattern('registry/method.yaml', 'packages/**'));
+    });
+    it('handles ? wildcard for single character', () => {
+        assert.ok(matchGlobPattern('src/a.ts', 'src/?.ts'));
+        assert.ok(!matchGlobPattern('src/ab.ts', 'src/?.ts'));
+    });
+    it('handles exact file path matching', () => {
+        assert.ok(matchGlobPattern('CLAUDE.md', 'CLAUDE.md'));
+        assert.ok(!matchGlobPattern('README.md', 'CLAUDE.md'));
+    });
+    it('handles patterns with dots correctly', () => {
+        assert.ok(matchGlobPattern('.method/council/AGENDA.yaml', '.method/**'));
+        assert.ok(matchGlobPattern('package.json', 'package.json'));
+    });
+});
+// ── isPathAllowed Tests ───────────────────────────────────────
+describe('isPathAllowed (PRD 014)', () => {
+    it('returns true for any path when allowed_paths is empty', () => {
+        assert.ok(isPathAllowed('anything/at/all.ts', []));
+    });
+    it('returns true for paths matching allowed patterns', () => {
+        const patterns = ['packages/bridge/src/**', 'packages/bridge/src/__tests__/**'];
+        assert.ok(isPathAllowed('packages/bridge/src/pool.ts', patterns));
+        assert.ok(isPathAllowed('packages/bridge/src/__tests__/pool.test.ts', patterns));
+    });
+    it('returns false for paths outside allowed patterns', () => {
+        const patterns = ['packages/bridge/**'];
+        assert.ok(!isPathAllowed('packages/core/src/index.ts', patterns));
+        assert.ok(!isPathAllowed('registry/method.yaml', patterns));
+        assert.ok(!isPathAllowed('.method/project-card.yaml', patterns));
+    });
+    it('normalizes backslashes to forward slashes', () => {
+        const patterns = ['packages/bridge/**'];
+        assert.ok(isPathAllowed('packages\\bridge\\src\\index.ts', patterns));
+    });
+    it('supports multiple patterns — match any', () => {
+        const patterns = ['packages/bridge/**', 'docs/prds/*.md'];
+        assert.ok(isPathAllowed('packages/bridge/src/pool.ts', patterns));
+        assert.ok(isPathAllowed('docs/prds/014-scope.md', patterns));
+        assert.ok(!isPathAllowed('packages/core/src/index.ts', patterns));
+    });
+    it('no false positives — in-scope files never rejected (SC-8)', () => {
+        const patterns = ['packages/bridge/src/**', 'packages/mcp/src/**'];
+        // All these should be allowed
+        assert.ok(isPathAllowed('packages/bridge/src/scope-hook.ts', patterns));
+        assert.ok(isPathAllowed('packages/bridge/src/__tests__/scope-hook.test.ts', patterns));
+        assert.ok(isPathAllowed('packages/mcp/src/index.ts', patterns));
+        assert.ok(isPathAllowed('packages/bridge/src/deeply/nested/file.ts', patterns));
+    });
+});
+// ── installScopeHook Tests ────────────────────────────────────
+describe('installScopeHook (PRD 014)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = join(os.tmpdir(), `scope-hook-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        mkdirSync(tmpDir, { recursive: true });
+        // Initialize a git repo in tmpDir so resolveHooksDir works
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+    });
+    afterEach(() => {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { /* cleanup best-effort */ }
+    });
+    it('installs hook file with correct content', () => {
+        const result = installScopeHook(tmpDir, 'test-session-1', ['packages/bridge/**']);
+        assert.equal(result.installed, true);
+        assert.ok(result.hookPath);
+        const content = readFileSync(result.hookPath, 'utf-8');
+        assert.ok(content.includes('#!/usr/bin/env bash'));
+        assert.ok(content.includes('packages/bridge/**'));
+        assert.ok(content.includes('test-session-1'));
+        assert.ok(content.includes('SCOPE VIOLATION'));
+    });
+    it('creates hooks directory if it does not exist', () => {
+        // Remove the hooks dir if git init created it
+        const hooksDir = join(tmpDir, '.git', 'hooks');
+        try {
+            rmSync(hooksDir, { recursive: true, force: true });
+        }
+        catch { /* ok */ }
+        const result = installScopeHook(tmpDir, 'test-session-2', ['src/**']);
+        assert.equal(result.installed, true);
+        assert.ok(existsSync(result.hookPath));
+    });
+    it('returns installed=false when allowed_paths is empty', () => {
+        const result = installScopeHook(tmpDir, 'test-session-3', []);
+        assert.equal(result.installed, false);
+        assert.equal(result.hookPath, null);
+    });
+    it('handles multiple patterns correctly', () => {
+        const patterns = ['packages/bridge/**', 'packages/mcp/**', 'docs/prds/*.md'];
+        const result = installScopeHook(tmpDir, 'test-session-4', patterns);
+        assert.equal(result.installed, true);
+        const content = readFileSync(result.hookPath, 'utf-8');
+        for (const pattern of patterns) {
+            assert.ok(content.includes(pattern), `Hook should contain pattern: ${pattern}`);
+        }
+    });
+});
+// ── Integration Test: Hook Rejects Out-of-Scope Commit ────────
+describe('Scope Hook Integration (PRD 014 SC-1)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = join(os.tmpdir(), `scope-int-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        mkdirSync(tmpDir, { recursive: true });
+        // Initialize a git repo with a commit
+        execSync('git init', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.email "test@test.com"', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git config user.name "Test"', { cwd: tmpDir, stdio: 'pipe' });
+        // Create initial commit
+        writeFileSync(join(tmpDir, 'README.md'), '# Test\n');
+        execSync('git add README.md', { cwd: tmpDir, stdio: 'pipe' });
+        execSync('git commit -m "initial"', { cwd: tmpDir, stdio: 'pipe' });
+        // Create directory structure
+        mkdirSync(join(tmpDir, 'packages', 'bridge', 'src'), { recursive: true });
+        mkdirSync(join(tmpDir, 'packages', 'core', 'src'), { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { /* cleanup best-effort */ }
+    });
+    it('rejects commit with out-of-scope files (SC-1: hard block)', () => {
+        // Install hook allowing only bridge files
+        const result = installScopeHook(tmpDir, 'test-integration', ['packages/bridge/**']);
+        assert.equal(result.installed, true);
+        // Create an out-of-scope file and try to commit
+        writeFileSync(join(tmpDir, 'packages', 'core', 'src', 'index.ts'), 'export {};');
+        execSync('git add packages/core/src/index.ts', { cwd: tmpDir, stdio: 'pipe' });
+        // Commit should fail due to pre-commit hook
+        assert.throws(() => {
+            execSync('git commit -m "out-of-scope change"', {
+                cwd: tmpDir,
+                stdio: 'pipe',
+                encoding: 'utf-8',
+            });
+        }, (err) => {
+            const stderr = err.stderr?.toString() ?? err.stdout?.toString() ?? '';
+            return stderr.includes('SCOPE VIOLATION') || err.status !== 0;
+        });
+    });
+    it('allows commit with in-scope files (SC-8: no false positives)', () => {
+        // Install hook allowing bridge files
+        const result = installScopeHook(tmpDir, 'test-integration-2', ['packages/bridge/**']);
+        assert.equal(result.installed, true);
+        // Create an in-scope file and commit
+        writeFileSync(join(tmpDir, 'packages', 'bridge', 'src', 'pool.ts'), 'export {};');
+        execSync('git add packages/bridge/src/pool.ts', { cwd: tmpDir, stdio: 'pipe' });
+        // Should succeed
+        const output = execSync('git commit -m "in-scope change"', {
+            cwd: tmpDir,
+            stdio: 'pipe',
+            encoding: 'utf-8',
+        });
+        // Commit should have gone through — check it exists
+        const log = execSync('git log --oneline -1', { cwd: tmpDir, encoding: 'utf-8' });
+        assert.ok(log.includes('in-scope change'));
+    });
+    it('backwards compatible — no hook when allowed_paths empty (SC-4)', () => {
+        // Install with empty paths — should not create hook
+        const result = installScopeHook(tmpDir, 'test-compat', []);
+        assert.equal(result.installed, false);
+        // Any file should be committable
+        writeFileSync(join(tmpDir, 'packages', 'core', 'src', 'anything.ts'), 'export {};');
+        execSync('git add packages/core/src/anything.ts', { cwd: tmpDir, stdio: 'pipe' });
+        const output = execSync('git commit -m "unrestricted commit"', {
+            cwd: tmpDir,
+            stdio: 'pipe',
+            encoding: 'utf-8',
+        });
+        const log = execSync('git log --oneline -1', { cwd: tmpDir, encoding: 'utf-8' });
+        assert.ok(log.includes('unrestricted commit'));
+    });
+});
+//# sourceMappingURL=scope-hook.test.js.map

package/dist/sessions/scope-hook.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-hook.test.js","sourceRoot":"","sources":["../../src/sessions/scope-hook.test.ts"],"names":[],"mappings":"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"}

package/dist/sessions/session-store/checkpoint-sink-impl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default `CheckpointSink` implementation — PRD-061 §5 "Default sink".
+ *
+ * Observes session-scoped `RuntimeEvent`s, debounces per-session writes, and
+ * calls `SessionStore.appendCheckpoint` with a fencing token supplied by the
+ * caller. Mirrors the legacy `SessionCheckpointSink` behavior (debounced per-
+ * turn writes) but talks to the new `SessionStore` port.
+ *
+ * The sink NEVER blocks bus emit — handler failures are logged via the
+ * `onError` callback (if supplied) and otherwise swallowed.
+ */
+import type { CheckpointSink, CheckpointSinkOptions } from '../../ports/checkpoint-sink.js';
+/** Default set of session-lifecycle event types that drive per-turn checkpoints. */
+export declare const SESSION_LIFECYCLE_TYPES: readonly string[];
+export declare function createCheckpointSink(opts: CheckpointSinkOptions): CheckpointSink;
+//# sourceMappingURL=checkpoint-sink-impl.d.ts.map

package/dist/sessions/session-store/checkpoint-sink-impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-sink-impl.d.ts","sourceRoot":"","sources":["../../../src/sessions/session-store/checkpoint-sink-impl.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,gCAAgC,CAAC;AAOxC,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAMpD,CAAC;AAwLF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,cAAc,CAEhF"}

package/dist/sessions/session-store/checkpoint-sink-impl.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Default `CheckpointSink` implementation — PRD-061 §5 "Default sink".
+ *
+ * Observes session-scoped `RuntimeEvent`s, debounces per-session writes, and
+ * calls `SessionStore.appendCheckpoint` with a fencing token supplied by the
+ * caller. Mirrors the legacy `SessionCheckpointSink` behavior (debounced per-
+ * turn writes) but talks to the new `SessionStore` port.
+ *
+ * The sink NEVER blocks bus emit — handler failures are logged via the
+ * `onError` callback (if supplied) and otherwise swallowed.
+ */
+import { isSessionStoreError } from '../../ports/session-store-errors.js';
+const DEFAULT_DEBOUNCE_MS = 200;
+/** Default set of session-lifecycle event types that drive per-turn checkpoints. */
+export const SESSION_LIFECYCLE_TYPES = [
+    'session.spawned',
+    'session.prompt.completed',
+    'session.killed',
+    'session.dead',
+    'session.state_changed',
+];
+function compileFilter(filter) {
+    const domains = filter.domain
+        ? new Set(Array.isArray(filter.domain) ? filter.domain : [filter.domain])
+        : null;
+    const types = filter.type
+        ? (Array.isArray(filter.type) ? filter.type : [filter.type]).map(globToRegExp)
+        : null;
+    const severities = filter.severity
+        ? new Set(Array.isArray(filter.severity) ? filter.severity : [filter.severity])
+        : null;
+    return {
+        domains,
+        typePatterns: types,
+        sessionId: filter.sessionId ?? null,
+        projectId: filter.projectId ?? null,
+        severities,
+    };
+}
+function globToRegExp(pattern) {
+    // Convert simple glob (`*`) to regex. Escape everything else.
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+function matches(filter, event) {
+    if (filter.domains && !filter.domains.has(event.domain))
+        return false;
+    if (filter.typePatterns && !filter.typePatterns.some(rx => rx.test(event.type)))
+        return false;
+    if (filter.sessionId && event.sessionId !== filter.sessionId)
+        return false;
+    if (filter.projectId && event.projectId !== filter.projectId)
+        return false;
+    if (filter.severities && !filter.severities.has(event.severity))
+        return false;
+    return true;
+}
+class CheckpointSinkImpl {
+    name = 'session-checkpoint';
+    store;
+    // Retained for debug / future-use — see S4 §4.2. The sink itself derives
+    // fencing tokens from the caller's per-session lookup; the workerId is
+    // informational.
+    _workerId;
+    fencingToken;
+    capture;
+    debounceMs;
+    defaultTypes;
+    errorHook;
+    extraFilters = [];
+    timers = new Map();
+    inflight = new Map();
+    disposed = false;
+    constructor(opts) {
+        this.store = opts.store;
+        this._workerId = opts.workerId;
+        this.fencingToken = opts.fencingToken;
+        this.capture = opts.captureSnapshot;
+        this.debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.defaultTypes = new Set(opts.defaultEventTypes ?? SESSION_LIFECYCLE_TYPES);
+        this.errorHook = opts.onError;
+    }
+    onEvent(event) {
+        if (this.disposed)
+            return;
+        const sessionId = event.sessionId ?? event.payload?.sessionId;
+        if (!sessionId)
+            return;
+        const immediate = this.extraFilters.some(f => matches(f, event));
+        const lifecycle = this.defaultTypes.has(event.type);
+        if (!immediate && !lifecycle)
+            return;
+        if (immediate) {
+            // Per-event opt-in: bypass the debouncer, flush any pending timer first.
+            const pending = this.timers.get(sessionId);
+            if (pending) {
+                clearTimeout(pending);
+                this.timers.delete(sessionId);
+            }
+            void this.writeCheckpoint(sessionId);
+            return;
+        }
+        const existing = this.timers.get(sessionId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.timers.delete(sessionId);
+            void this.writeCheckpoint(sessionId);
+        }, this.debounceMs);
+        this.timers.set(sessionId, timer);
+    }
+    onError(err, event) {
+        if (!this.errorHook)
+            return;
+        const sessionId = event.sessionId ?? '';
+        this.errorHook(err, sessionId);
+    }
+    checkpointOnEvent(filter) {
+        this.extraFilters.push(compileFilter(filter));
+    }
+    async flush() {
+        const pending = [];
+        for (const [sessionId, timer] of this.timers) {
+            clearTimeout(timer);
+            pending.push(this.writeCheckpoint(sessionId));
+        }
+        this.timers.clear();
+        // Also await any writes already in flight.
+        for (const p of this.inflight.values()) {
+            pending.push(p);
+        }
+        await Promise.allSettled(pending);
+    }
+    get pendingCount() {
+        return this.timers.size + this.inflight.size;
+    }
+    dispose() {
+        this.disposed = true;
+        for (const t of this.timers.values())
+            clearTimeout(t);
+        this.timers.clear();
+    }
+    // ── internals ───────────────────────────────────────────────────
+    async writeCheckpoint(sessionId) {
+        const token = this.fencingToken(sessionId);
+        if (!token)
+            return; // no active lease — runtime has not resumed this session
+        const write = (async () => {
+            try {
+                const capture = await this.capture(sessionId);
+                if (!capture)
+                    return;
+                const latest = await this.store.loadLatestCheckpoint(sessionId);
+                const sequence = (latest?.sequence ?? 0) + 1;
+                const checkpoint = {
+                    schemaVersion: 1,
+                    sequence,
+                    sessionId,
+                    createdAt: new Date().toISOString(),
+                    eventCursor: capture.eventCursor,
+                    agentState: capture.agentState,
+                    pendingBudget: capture.pendingBudget,
+                    nextAction: capture.nextAction,
+                    note: capture.note,
+                };
+                await this.store.appendCheckpoint(sessionId, checkpoint, token);
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                if (this.errorHook)
+                    this.errorHook(e, sessionId);
+                else if (!isSessionStoreError(err)) {
+                    // eslint-disable-next-line no-console
+                    console.error(`[checkpoint-sink] checkpoint failed for ${sessionId}:`, e.message);
+                }
+            }
+        })();
+        this.inflight.set(sessionId, write);
+        try {
+            await write;
+        }
+        finally {
+            this.inflight.delete(sessionId);
+        }
+    }
+}
+export function createCheckpointSink(opts) {
+    return new CheckpointSinkImpl(opts);
+}
+//# sourceMappingURL=checkpoint-sink-impl.js.map

package/dist/sessions/session-store/checkpoint-sink-impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-sink-impl.js","sourceRoot":"","sources":["../../../src/sessions/session-store/checkpoint-sink-impl.ts"],"names":[],"mappings":"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"}

package/dist/sessions/session-store/checkpoint-sink-impl.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the default CheckpointSink impl.
+ */
+export {};
+//# sourceMappingURL=checkpoint-sink-impl.test.d.ts.map

package/dist/sessions/session-store/checkpoint-sink-impl.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-sink-impl.test.d.ts","sourceRoot":"","sources":["../../../src/sessions/session-store/checkpoint-sink-impl.test.ts"],"names":[],"mappings":"AACA;;GAEG"}

package/dist/sessions/session-store/checkpoint-sink-impl.test.js

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the default CheckpointSink impl.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createCheckpointSink } from './checkpoint-sink-impl.js';
+import { createInMemorySessionStore } from './in-memory-session-store.js';
+function snap(id) {
+    return {
+        schemaVersion: 1,
+        sessionId: id,
+        scopeId: 'app_test',
+        pactRef: { id: 'p', version: '1.0.0', fingerprint: 'sha256:x' },
+        status: 'running',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        latestCheckpointSequence: null,
+        depth: 0,
+    };
+}
+function event(sessionId, type) {
+    return {
+        id: 'evt_' + Math.random().toString(36).slice(2),
+        version: 1,
+        timestamp: new Date().toISOString(),
+        sequence: 1,
+        domain: 'session',
+        type,
+        severity: 'info',
+        sessionId,
+        payload: {},
+        source: 'test',
+    };
+}
+const capture = {
+    sessionId: 'ses_1',
+    eventCursor: { sequence: 1, id: 'evt_1' },
+    agentState: { kind: 'inline', data: {} },
+    pendingBudget: null,
+    nextAction: { kind: 'await-prompt' },
+};
+describe('CheckpointSink — debounced per-turn writes', () => {
+    it('writes one checkpoint per debounce window', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap('ses_1'));
+        const rc = await store.resume('ses_1', 'worker-a');
+        const sink = createCheckpointSink({
+            store,
+            workerId: () => 'worker-a',
+            fencingToken: () => rc.fencingToken,
+            captureSnapshot: async () => capture,
+            debounceMs: 5,
+        });
+        sink.onEvent(event('ses_1', 'session.spawned'));
+        sink.onEvent(event('ses_1', 'session.state_changed'));
+        sink.onEvent(event('ses_1', 'session.prompt.completed'));
+        await new Promise(r => setTimeout(r, 30));
+        await sink.flush();
+        const latest = await store.loadLatestCheckpoint('ses_1');
+        assert.ok(latest);
+        assert.equal(latest?.sequence, 1); // all three events collapsed into one checkpoint
+        sink.dispose();
+    });
+    it('ignores events without a fencing token (no active lease)', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap('ses_2'));
+        const sink = createCheckpointSink({
+            store,
+            workerId: () => 'worker-a',
+            fencingToken: () => null,
+            captureSnapshot: async () => ({ ...capture, sessionId: 'ses_2' }),
+            debounceMs: 5,
+        });
+        sink.onEvent(event('ses_2', 'session.spawned'));
+        await sink.flush();
+        assert.equal(await store.loadLatestCheckpoint('ses_2'), null);
+        sink.dispose();
+    });
+    it('skips non-lifecycle events by default', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap('ses_3'));
+        const rc = await store.resume('ses_3', 'worker-a');
+        const sink = createCheckpointSink({
+            store,
+            workerId: () => 'worker-a',
+            fencingToken: () => rc.fencingToken,
+            captureSnapshot: async () => ({ ...capture, sessionId: 'ses_3' }),
+            debounceMs: 5,
+        });
+        sink.onEvent(event('ses_3', 'strategy.node.started'));
+        await new Promise(r => setTimeout(r, 15));
+        await sink.flush();
+        assert.equal(await store.loadLatestCheckpoint('ses_3'), null);
+        sink.dispose();
+    });
+    it('checkpointOnEvent triggers immediate writes on match', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap('ses_4'));
+        const rc = await store.resume('ses_4', 'worker-a');
+        let captured = 0;
+        const sink = createCheckpointSink({
+            store,
+            workerId: () => 'worker-a',
+            fencingToken: () => rc.fencingToken,
+            captureSnapshot: async () => {
+                captured += 1;
+                return { ...capture, sessionId: 'ses_4' };
+            },
+            debounceMs: 500,
+        });
+        sink.checkpointOnEvent({ type: 'tool.*' });
+        sink.onEvent(event('ses_4', 'tool.invoked'));
+        // Give the microtask queue a chance to flush the immediate write.
+        await new Promise(r => setImmediate(r));
+        await sink.flush();
+        assert.ok(captured >= 1);
+        const latest = await store.loadLatestCheckpoint('ses_4');
+        assert.ok(latest);
+        sink.dispose();
+    });
+    it('dispose() clears pending timers', () => {
+        const store = createInMemorySessionStore();
+        const sink = createCheckpointSink({
+            store,
+            workerId: () => 'worker',
+            fencingToken: () => 'ft',
+            captureSnapshot: async () => null,
+            debounceMs: 5_000,
+        });
+        sink.onEvent(event('ses_5', 'session.spawned'));
+        assert.equal(sink.pendingCount, 1);
+        sink.dispose();
+        assert.equal(sink.pendingCount, 0);
+    });
+});
+//# sourceMappingURL=checkpoint-sink-impl.test.js.map