feat: session serialize/restore for CleoOS agent persistence (v2026.3.72)

Add serializeSession() and restoreSession() to enable CleoOS to capture
full session state when agents die and hydrate it when new agents connect.

Snapshot includes: session object, handoff data, decision log, brain
observations, active task context, and duration. Restore handles scope
conflict detection, agent handoff tracking, and hook dispatch.

Wired into Cleo facade as sessions.serialize() and sessions.restore().
Types exported from both @cleocode/core and @cleocode/contracts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kryptobaseddev

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/monorepo",
-  "version": "2026.3.71",
+  "version": "2026.3.72",
   "private": true,
   "type": "module",
   "packageManager": "pnpm@10.30.0",

packages/adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/adapters",
-  "version": "2026.3.71",
+  "version": "2026.3.72",
   "description": "Unified provider adapters for CLEO (Claude Code, OpenCode, Cursor)",
   "type": "module",
   "main": "dist/index.js",

packages/agents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/agents",
-  "version": "2026.3.71",
+  "version": "2026.3.72",
   "description": "CLEO agent protocols and templates",
   "type": "module",
   "license": "MIT",

packages/cleo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.3.71",
+  "version": "2026.3.72",
   "description": "CLEO CLI + MCP server — the assembled product consuming @cleocode/core",
   "type": "module",
   "main": "./dist/cli/index.js",

packages/contracts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.3.71",
+  "version": "2026.3.72",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",

packages/contracts/src/facade.ts

@@ -369,6 +369,10 @@ export interface SessionsAPI {
   decisionLog(params?: { sessionId?: string; taskId?: string }): Promise<unknown>;
   /** Get last handoff for a scope. */
   lastHandoff(scope?: { type: string; epicId?: string }): Promise<unknown>;
+  /** Serialize a session into a complete snapshot for persistence. */
+  serialize(params?: { sessionId?: string; maxObservations?: number }): Promise<unknown>;
+  /** Restore a session from a previously serialized snapshot. */
+  restore(snapshot: unknown, params?: { agent?: string; activate?: boolean }): Promise<unknown>;
 }
 
 /** Memory/Brain domain API. */

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.71",
+  "version": "2026.3.72",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",

packages/core/src/cleo.ts

@@ -129,6 +129,8 @@ import {
   startSession,
   suspendSession,
 } from './sessions/index.js';
+// Session snapshots (Phase 3: persistence)
+import { restoreSession, serializeSession } from './sessions/snapshot.js';
 // Sticky
 import {
   addSticky,
@@ -289,6 +291,16 @@ export class Cleo {
       contextDrift: (p) => getContextDrift(root, p),
       decisionLog: (p) => getDecisionLog(root, { sessionId: p?.sessionId, taskId: p?.taskId }),
       lastHandoff: (scope) => getLastHandoff(root, scope),
+      serialize: (p) =>
+        serializeSession(root, {
+          sessionId: p?.sessionId,
+          maxObservations: p?.maxObservations,
+        }),
+      restore: (snapshot, p) =>
+        restoreSession(root, snapshot as import('./sessions/snapshot.js').SessionSnapshot, {
+          agent: p?.agent,
+          activate: p?.activate,
+        }),
     };
   }
 

packages/core/src/index.ts

@@ -299,6 +299,16 @@ export {
   sessionStatus,
   startSession,
 } from './sessions/index.js';
+export type {
+  RestoreOptions,
+  SerializeOptions,
+  SessionSnapshot,
+  SnapshotDecision,
+  SnapshotObservation,
+  SnapshotTaskContext,
+} from './sessions/snapshot.js';
+// Session snapshots (Phase 3: persistence)
+export { restoreSession, serializeSession } from './sessions/snapshot.js';
 export { getMigrationStatus as getSystemMigrationStatus } from './system/migrate.js';
 export { checkStorageMigration } from './system/storage-preflight.js';
 // Task work