@namzu/sdk 0.1.7 → 0.2.0

package/src/session/retention/index.ts

@@ -0,0 +1,16 @@
+// Sub-barrel for the retention/archival module (Convention #4).
+// Concrete types + manager live in sibling files.
+
+export type { ArchiveBackendRef } from './archive-backend-ref.js'
+export type { RetentionPolicy } from './policy.js'
+export { RETENTION_POLICY_DISABLED } from './policy.js'
+export type { ArchiveBackend, ArchiveInput, ArchiveOutput, SubSessionTombstone } from './backend.js'
+export {
+	ArchivalManager,
+	ArchiveNotConfiguredError,
+	SubSessionNotArchivableError,
+	SubSessionNotArchivedError,
+} from './archive.js'
+export type { ArchivalManagerDeps, WorkspaceResolver } from './archive.js'
+export { ArchiveNotFoundError, DiskArchiveBackend } from './disk-backend.js'
+export type { DiskArchiveBackendConfig } from './disk-backend.js'

package/src/session/retention/policy.ts

@@ -0,0 +1,53 @@
+/**
+ * RetentionPolicy — per-project configuration for sub-session retention and
+ * archival. See session-hierarchy.md §12.3.
+ *
+ * Deny-by-default (Convention #5): the absence of any field means "no
+ * automatic archival." A policy without an `archiveBackend` cannot drive
+ * archival at all — {@link ArchivalManager.archive} rejects with
+ * {@link ArchiveNotConfiguredError}. The primitive Phase 8 ships is
+ * on-demand `archive(subSessionId)`; a scheduler that invokes the primitive
+ * is platform-layer (out of SDK scope per the roadmap "What's OUT" list).
+ *
+ * Phase 8 replaces the Phase 1 `RetentionPolicyRef = unknown` placeholder at
+ * `session/hierarchy/project.ts` with this real type.
+ */
+
+import type { ArchiveBackendRef } from './archive-backend-ref.js'
+
+/**
+ * Retention policy. Every field is optional (deny-by-default): no policy, no
+ * archival. See pattern doc §12.3 for rationale.
+ */
+export interface RetentionPolicy {
+	/**
+	 * Idle sub-sessions older than this are eligible for archival. Expressed in
+	 * milliseconds to stay dependency-free — no `Duration` type in the kernel
+	 * today. Absent field = no TTL (eligibility never triggers on age alone).
+	 */
+	readonly idleSubSessionTTL?: number
+
+	/**
+	 * Hard cap on sub-sessions per project. When exceeded, the oldest-idle
+	 * sub-sessions become archival-eligible. Absent = no cap.
+	 *
+	 * Note: enforcement of this cap is platform-layer (scheduler territory).
+	 * The SDK primitive `archive()` takes an explicit {@link SubSessionId} —
+	 * it does not walk the project tree.
+	 */
+	readonly maxSubSessionsPerProject?: number
+
+	/**
+	 * Ref for the backing {@link ArchiveBackend}. Absent = archival disabled
+	 * even if TTL/cap are set — {@link ArchivalManager.archive} rejects with
+	 * {@link ArchiveNotConfiguredError}. This is the deny-by-default gate.
+	 */
+	readonly archiveBackend?: ArchiveBackendRef
+}
+
+/**
+ * The empty retention policy — archival fully disabled. Exported as a named
+ * constant so call sites declare their deny-by-default posture explicitly
+ * rather than relying on `{}` literals (Convention #0, #5).
+ */
+export const RETENTION_POLICY_DISABLED: RetentionPolicy = Object.freeze({})

package/src/session/summary/__tests__/materialize.test.ts

@@ -0,0 +1,341 @@
+import { describe, expect, it } from 'vitest'
+import { TenantIsolationError } from '../../../session/errors.js'
+import type { ActorRef } from '../../../session/hierarchy/actor.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import type { AgentId, SessionId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { SummaryId } from '../../../types/session/ids.js'
+import type { DeliverableRef } from '../deliverable.js'
+import { SessionSummaryMaterializer } from '../materialize.js'
+import {
+	AGENT_SUMMARY_MAX_CHARS,
+	AgentSummaryTooLongError,
+	SessionAlreadySummarizedError,
+} from '../ref.js'
+
+const tenantA = 'tnt_alpha' as TenantId
+const tenantB = 'tnt_beta' as TenantId
+
+function userActor(tenantId: TenantId): ActorRef {
+	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
+}
+
+function agentActor(tenantId: TenantId): ActorRef {
+	return { kind: 'agent', agentId: 'agt_a' as AgentId, tenantId }
+}
+
+function makeSummaryIdGenerator(): () => SummaryId {
+	let n = 0
+	return (): SummaryId => `sum_test_${++n}` as SummaryId
+}
+
+async function seedActiveSession(store: InMemorySessionStore, tenantId: TenantId) {
+	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
+	const session = await store.createSession(
+		{ projectId: project.id, currentActor: agentActor(tenantId) },
+		tenantId,
+	)
+	// Put the session into `active` so the materializer's status-flip behavior
+	// is observable.
+	await store.updateSession({ ...session, status: 'active' }, tenantId)
+	return { project, session: { ...session, status: 'active' as const } }
+}
+
+function buildMaterializer(store: InMemorySessionStore) {
+	return new SessionSummaryMaterializer({
+		store,
+		generateSummaryId: makeSummaryIdGenerator(),
+		now: () => new Date('2026-04-17T00:00:00Z'),
+	})
+}
+
+describe('SessionSummaryMaterializer.materialize', () => {
+	it('materializes on an active session and flips status to idle', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded', verdict: 'done' },
+			agentSummary: 'Completed task X.',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		expect(summary.id).toBe('sum_test_1')
+		expect(summary.sessionRef).toBe(session.id)
+		expect(summary.materializedBy).toBe('kernel')
+
+		const stored = await store.getSummary(session.id, tenantA)
+		expect(stored?.id).toBe(summary.id)
+
+		const reloaded = await store.getSession(session.id, tenantA)
+		expect(reloaded?.status).toBe('idle')
+	})
+
+	it('rejects an agentSummary exceeding AGENT_SUMMARY_MAX_CHARS', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		await expect(
+			materializer.materialize({
+				sessionId: session.id,
+				tenantId: tenantA,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: 'x'.repeat(AGENT_SUMMARY_MAX_CHARS + 1),
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toBeInstanceOf(AgentSummaryTooLongError)
+	})
+
+	it('rejects re-materialization when a summary already exists', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: 'first',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		await expect(
+			materializer.materialize({
+				sessionId: session.id,
+				tenantId: tenantA,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: 'second',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toBeInstanceOf(SessionAlreadySummarizedError)
+	})
+
+	it('rejects cross-tenant materialize with TenantIsolationError', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		await expect(
+			materializer.materialize({
+				sessionId: session.id,
+				tenantId: tenantB,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: 'x',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('preserves declaredDeliverables verbatim in the emitted ref', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		const deliverables: DeliverableRef[] = [
+			{
+				id: 'del_a' as DeliverableRef['id'],
+				kind: 'file',
+				path: 'src/foo.ts',
+				contentHash: 'abc123',
+				sizeBytes: 42,
+			},
+			{
+				id: 'del_b' as DeliverableRef['id'],
+				kind: 'artifact_blob',
+				storageRef: 'blob://x',
+				mediaType: 'application/json',
+			},
+		]
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'partial' },
+			agentSummary: '',
+			declaredDeliverables: deliverables,
+			keyDecisions: [],
+		})
+
+		expect(summary.deliverables).toEqual(deliverables)
+	})
+
+	it('preserves keyDecisions verbatim in the emitted ref', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		const decisions = [
+			{ at: new Date('2026-04-17T01:00:00Z'), summary: 'plan approved' },
+			{ at: new Date('2026-04-17T02:00:00Z'), summary: 'hitl granted' },
+		]
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: decisions,
+		})
+
+		expect(summary.keyDecisions).toEqual(decisions)
+	})
+
+	it('constructs SummaryId via the injected generator', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+
+		const gen = makeSummaryIdGenerator()
+		const materializer = new SessionSummaryMaterializer({
+			store,
+			generateSummaryId: gen,
+		})
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		expect(summary.id).toBe('sum_test_1')
+	})
+
+	it('always sets materializedBy to "kernel"', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		const summary = await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		expect(summary.materializedBy).toBe('kernel')
+	})
+
+	it('leaves already-idle sessions in idle (no spurious flip)', async () => {
+		const store = new InMemorySessionStore()
+		const project = await store.createProject({ tenantId: tenantA, name: 'p1' }, tenantA)
+		const session = await store.createSession(
+			{ projectId: project.id, currentActor: userActor(tenantA) },
+			tenantA,
+		)
+		// session.status defaults to 'idle'
+		const materializer = buildMaterializer(store)
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		const reloaded = await store.getSession(session.id, tenantA)
+		expect(reloaded?.status).toBe('idle')
+	})
+
+	it('leaves failed sessions in failed (materialize does not resurrect)', async () => {
+		const store = new InMemorySessionStore()
+		const project = await store.createProject({ tenantId: tenantA, name: 'p1' }, tenantA)
+		const session = await store.createSession(
+			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			tenantA,
+		)
+		await store.updateSession({ ...session, status: 'failed' }, tenantA)
+		const materializer = buildMaterializer(store)
+
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'failed', verdict: 'gave up' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+
+		const reloaded = await store.getSession(session.id, tenantA)
+		expect(reloaded?.status).toBe('failed')
+	})
+})
+
+describe('SessionSummaryMaterializer.recover', () => {
+	it('returns null when no summary file exists (no side effect)', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		const recovered = await materializer.recover(session.id, tenantA)
+		expect(recovered).toBeNull()
+
+		const reloaded = await store.getSession(session.id, tenantA)
+		// No side effect — still active.
+		expect(reloaded?.status).toBe('active')
+	})
+
+	it('flips dangling session status idempotently when summary is present', async () => {
+		const store = new InMemorySessionStore()
+		const { session } = await seedActiveSession(store, tenantA)
+		const materializer = buildMaterializer(store)
+
+		// Simulate mid-crash: write summary directly, then force session back to
+		// active (mimicking a process death between the two atomic writes).
+		await materializer.materialize({
+			sessionId: session.id,
+			tenantId: tenantA,
+			finalOutcome: { status: 'succeeded' },
+			agentSummary: '',
+			declaredDeliverables: [],
+			keyDecisions: [],
+		})
+		const mid = await store.getSession(session.id, tenantA)
+		if (!mid) throw new Error('seed mid session missing')
+		await store.updateSession({ ...mid, status: 'active' }, tenantA)
+
+		const recovered = await materializer.recover(session.id, tenantA)
+		expect(recovered).not.toBeNull()
+
+		const reloaded = await store.getSession(session.id, tenantA)
+		expect(reloaded?.status).toBe('idle')
+
+		// Idempotent: calling recover again with session already idle is a no-op.
+		const recovered2 = await materializer.recover(session.id, tenantA)
+		expect(recovered2?.id).toBe(recovered?.id)
+		const reloaded2 = await store.getSession(session.id, tenantA)
+		expect(reloaded2?.status).toBe('idle')
+	})
+})
+
+describe('SessionSummaryMaterializer missing session', () => {
+	it('throws when the session does not exist', async () => {
+		const store = new InMemorySessionStore()
+		const materializer = buildMaterializer(store)
+
+		await expect(
+			materializer.materialize({
+				sessionId: 'ses_missing' as SessionId,
+				tenantId: tenantA,
+				finalOutcome: { status: 'succeeded' },
+				agentSummary: '',
+				declaredDeliverables: [],
+				keyDecisions: [],
+			}),
+		).rejects.toThrow(/not found/)
+	})
+})

package/src/session/summary/deliverable.ts

@@ -0,0 +1,84 @@
+/**
+ * DeliverableRef — discriminated union of artifact types a completed
+ * sub-session may emit.
+ *
+ * Consumed by two surfaces:
+ *   1. `SessionSummaryRef.deliverables` — authoritative list of artifacts a
+ *      completed sub-session produced. See session-hierarchy.md §4.7.
+ *   2. `SubSession.prevArtifactRef` — intervention chains reference a prior
+ *      immutable artifact. See session-hierarchy.md §4.5, §8.1.
+ *
+ * The `session_summary` variant is what intervention sub-sessions use — a
+ * follow-up intervention points at the previous completed session's summary,
+ * forming a strict acyclic DAG validated by
+ * `session/intervention/prev-artifact.ts`.
+ *
+ * Convention #6: this is a discriminated union on `kind`; any consumer must
+ * handle all variants exhaustively.
+ */
+
+import type { RunId, SessionId } from '../../types/ids/index.js'
+import type { DeliverableId, SummaryId } from '../../types/session/ids.js'
+
+/** Discriminator for {@link DeliverableRef}. */
+export type DeliverableKind = 'file' | 'session_summary' | 'message' | 'artifact_blob'
+
+/**
+ * A file deliverable — a path relative to the workspace root, plus a content
+ * hash pinning the file to its state at materialize time. Subsequent edits to
+ * the file on disk do not mutate the deliverable; the ref is a snapshot.
+ */
+export interface FileDeliverable {
+	readonly id: DeliverableId
+	readonly kind: 'file'
+	/** Path relative to the owning session's workspace root. */
+	readonly path: string
+	/** sha256 of the file's content at materialize time. */
+	readonly contentHash: string
+	readonly sizeBytes: number
+}
+
+/**
+ * A pointer to a previously-materialized {@link SessionSummaryRef}. The
+ * intervention DAG uses this variant to reference the immutable output of a
+ * prior completed session.
+ */
+export interface SessionSummaryDeliverable {
+	readonly id: DeliverableId
+	readonly kind: 'session_summary'
+	readonly sessionId: SessionId
+	readonly summaryRef: SummaryId
+	readonly at: Date
+}
+
+/**
+ * A specific persisted message within a session run — useful for referencing
+ * a single LLM turn as an artifact (e.g. a decision record).
+ */
+export interface MessageDeliverable {
+	readonly id: DeliverableId
+	readonly kind: 'message'
+	readonly sessionId: SessionId
+	readonly runId: RunId
+	/** Opaque identifier bound to the run's persisted message log. */
+	readonly messageId: string
+}
+
+/**
+ * An opaque blob deliverable — content lives in an out-of-band storage
+ * backend (object store, artifact registry). The SDK does not fetch or
+ * validate blob contents; callers resolve via the `storageRef`.
+ */
+export interface ArtifactBlobDeliverable {
+	readonly id: DeliverableId
+	readonly kind: 'artifact_blob'
+	/** Opaque — bound to a storage backend the consumer owns. */
+	readonly storageRef: string
+	readonly mediaType?: string
+}
+
+export type DeliverableRef =
+	| FileDeliverable
+	| SessionSummaryDeliverable
+	| MessageDeliverable
+	| ArtifactBlobDeliverable

package/src/session/summary/index.ts

@@ -0,0 +1,31 @@
+// Sub-barrel for the session summary module (Convention #4).
+//
+// See session-hierarchy.md §4.7 (SessionSummaryRef shape) and §8.1
+// (kernel-only emission invariant). Concrete types and the materializer live
+// in sibling files; re-export them here so consumers import via
+// `../session/summary/index.js`.
+
+export type {
+	ArtifactBlobDeliverable,
+	DeliverableKind,
+	DeliverableRef,
+	FileDeliverable,
+	MessageDeliverable,
+	SessionSummaryDeliverable,
+} from './deliverable.js'
+export {
+	AGENT_SUMMARY_MAX_CHARS,
+	AgentSummaryTooLongError,
+	SessionAlreadySummarizedError,
+} from './ref.js'
+export type {
+	SessionSummaryKeyDecision,
+	SessionSummaryOutcome,
+	SessionSummaryOutcomeStatus,
+	SessionSummaryRef,
+} from './ref.js'
+export { SessionSummaryMaterializer } from './materialize.js'
+export type {
+	MaterializeInput,
+	SessionSummaryMaterializerDeps,
+} from './materialize.js'

package/src/session/summary/materialize.ts

@@ -0,0 +1,169 @@
+/**
+ * SessionSummaryMaterializer — kernel terminalization primitive.
+ *
+ * The sole producer of {@link SessionSummaryRef}. No agent-callable surface
+ * exists to bypass this (Convention #0 load-bearing — see
+ * session-hierarchy.md §8.1).
+ *
+ * Atomicity contract (§8.1): the summary write and the owning session's
+ * `non-terminal → idle` status flip commit as one logical unit. In the
+ * InMemory store the two happen within the same method call under the store's
+ * Map guard; in the Disk store they are two sequential write-tmp-renames
+ * (summary.json first, then session.json). A mid-step crash leaves the
+ * summary persisted but the session still active — `recover()` replays the
+ * session-status flip idempotently on next boot.
+ *
+ * The class is function-call-style (no internal state beyond deps). Tests
+ * inject a fake generator for deterministic IDs; production uses
+ * `generateSummaryId` from `utils/id.ts`.
+ */
+
+import type { SessionId, TenantId } from '../../types/ids/index.js'
+import type { SummaryId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+import type { Session } from '../hierarchy/session.js'
+import type { DeliverableRef } from './deliverable.js'
+import {
+	AGENT_SUMMARY_MAX_CHARS,
+	AgentSummaryTooLongError,
+	SessionAlreadySummarizedError,
+	type SessionSummaryKeyDecision,
+	type SessionSummaryOutcome,
+	type SessionSummaryRef,
+} from './ref.js'
+
+/**
+ * Dependencies for {@link SessionSummaryMaterializer}. The generator is
+ * injected so tests can produce deterministic IDs; production code wires
+ * `generateSummaryId` from `utils/id.ts`.
+ */
+export interface SessionSummaryMaterializerDeps {
+	readonly store: SessionStore
+	readonly generateSummaryId: () => SummaryId
+	/** Clock hook — defaults to `new Date()` when omitted. */
+	readonly now?: () => Date
+}
+
+/**
+ * Caller-supplied payload for {@link SessionSummaryMaterializer.materialize}.
+ * The materializer validates `agentSummary` length, constructs the
+ * `SessionSummaryRef`, and delegates the atomic write to the store.
+ */
+export interface MaterializeInput {
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly finalOutcome: SessionSummaryOutcome
+	readonly agentSummary: string
+	readonly declaredDeliverables: readonly DeliverableRef[]
+	readonly keyDecisions: readonly SessionSummaryKeyDecision[]
+}
+
+/**
+ * Session statuses from which a materialize call may legally transition to
+ * `'idle'` as part of the terminalization. Other states (already `'idle'`,
+ * `'failed'`, `'archived'`, `'awaiting_hitl'`) are left untouched; the
+ * materializer never moves a session *out of* `'failed'` or `'archived'`.
+ */
+const TERMINALIZABLE_STATUSES: ReadonlySet<Session['status']> = new Set([
+	'active',
+	'locked',
+	'awaiting_merge',
+])
+
+export class SessionSummaryMaterializer {
+	private readonly deps: SessionSummaryMaterializerDeps
+
+	constructor(deps: SessionSummaryMaterializerDeps) {
+		this.deps = deps
+	}
+
+	/**
+	 * Kernel emission path. Validates, builds the immutable
+	 * {@link SessionSummaryRef}, and hands it to the store for atomic write +
+	 * status-flip. Rejects with:
+	 *
+	 * - {@link AgentSummaryTooLongError} — `agentSummary` exceeds the max char
+	 *   cap ({@link AGENT_SUMMARY_MAX_CHARS}).
+	 * - `TenantIsolationError` — session is owned by a different tenant.
+	 * - {@link SessionAlreadySummarizedError} — the session already has a
+	 *   persisted summary. Re-materialization would duplicate history; the
+	 *   caller should instead open an intervention sub-session (§4.5).
+	 */
+	async materialize(input: MaterializeInput): Promise<SessionSummaryRef> {
+		this.assertSummaryLength(input.agentSummary)
+
+		const session = await this.deps.store.getSession(input.sessionId, input.tenantId)
+		if (!session) {
+			throw new Error(`Session ${input.sessionId} not found`)
+		}
+
+		const existing = await this.deps.store.getSummary(input.sessionId, input.tenantId)
+		if (existing) {
+			throw new SessionAlreadySummarizedError({
+				sessionId: input.sessionId,
+				existingSummaryId: existing.id,
+			})
+		}
+
+		const summary: SessionSummaryRef = {
+			id: this.deps.generateSummaryId(),
+			sessionRef: input.sessionId,
+			tenantId: input.tenantId,
+			outcome: input.finalOutcome,
+			deliverables: input.declaredDeliverables,
+			agentSummary: input.agentSummary,
+			keyDecisions: input.keyDecisions,
+			at: this.clock(),
+			materializedBy: 'kernel',
+		}
+
+		await this.deps.store.recordSummary(summary, input.tenantId)
+		return summary
+	}
+
+	/**
+	 * Recovery path. Called at boot (or explicitly by the lifecycle manager)
+	 * for sessions whose `summary.json` is persisted but whose `session.json`
+	 * still reports a non-terminal status — the crash window between the two
+	 * atomic writes on disk.
+	 *
+	 * Idempotent: if the session is already `'idle'` (or another terminal
+	 * state), no write occurs; the existing summary is returned. If no summary
+	 * is persisted, returns `null` and no side effect occurs. This is the only
+	 * non-materialize path that may touch the stored summary — it does not
+	 * mint a new ID, only re-triggers the store's status flip via
+	 * `recordSummary` when it detects the dangling session.
+	 */
+	async recover(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null> {
+		const summary = await this.deps.store.getSummary(sessionId, tenantId)
+		if (!summary) return null
+
+		const session = await this.deps.store.getSession(sessionId, tenantId)
+		if (!session) return summary
+
+		if (TERMINALIZABLE_STATUSES.has(session.status)) {
+			// Dangling: summary persisted but session never flipped. Replay the
+			// status transition by re-invoking `recordSummary` — store impls
+			// treat an existing-summary path as "flip-only, no duplicate write".
+			// Cast preserves the kernel brand on the recovered record.
+			await this.deps.store.recordSummary(
+				summary as SessionSummaryRef & { materializedBy: 'kernel' },
+				tenantId,
+			)
+		}
+		return summary
+	}
+
+	private assertSummaryLength(agentSummary: string): void {
+		if (agentSummary.length > AGENT_SUMMARY_MAX_CHARS) {
+			throw new AgentSummaryTooLongError({
+				actual: agentSummary.length,
+				max: AGENT_SUMMARY_MAX_CHARS,
+			})
+		}
+	}
+
+	private clock(): Date {
+		return this.deps.now ? this.deps.now() : new Date()
+	}
+}