@cleocode/cleo 2026.3.70 → 2026.3.72

package/dist/cli/index.js

@@ -199,6 +199,39 @@ var init_exit_codes = __esm({
   }
 });
 
+// packages/contracts/src/facade.ts
+var BRAIN_OBSERVATION_TYPES, AGENT_INSTANCE_STATUSES, AGENT_TYPES;
+var init_facade = __esm({
+  "packages/contracts/src/facade.ts"() {
+    "use strict";
+    BRAIN_OBSERVATION_TYPES = [
+      "discovery",
+      "change",
+      "feature",
+      "bugfix",
+      "decision",
+      "refactor"
+    ];
+    AGENT_INSTANCE_STATUSES = [
+      "starting",
+      "active",
+      "idle",
+      "error",
+      "crashed",
+      "stopped"
+    ];
+    AGENT_TYPES = [
+      "orchestrator",
+      "executor",
+      "researcher",
+      "architect",
+      "validator",
+      "documentor",
+      "custom"
+    ];
+  }
+});
+
 // packages/contracts/src/lafs.ts
 function isLafsSuccess(envelope) {
   return envelope.success === true;
@@ -489,6 +522,7 @@ var init_src = __esm({
   "packages/contracts/src/index.ts"() {
     init_errors();
     init_exit_codes();
+    init_facade();
     init_lafs();
     init_operations();
     init_session2();
@@ -8915,12 +8949,12 @@ var init_status_registry2 = __esm({
 
 // packages/core/src/agents/agent-schema.ts
 import { sql as sql2 } from "drizzle-orm";
-var AGENT_INSTANCE_STATUSES, AGENT_TYPES, agentInstances, agentErrorLog;
+var AGENT_INSTANCE_STATUSES2, AGENT_TYPES2, agentInstances, agentErrorLog;
 var init_agent_schema = __esm({
   "packages/core/src/agents/agent-schema.ts"() {
     "use strict";
     init_sqlite_core();
-    AGENT_INSTANCE_STATUSES = [
+    AGENT_INSTANCE_STATUSES2 = [
       "starting",
       "active",
       "idle",
@@ -8928,7 +8962,7 @@ var init_agent_schema = __esm({
       "crashed",
       "stopped"
     ];
-    AGENT_TYPES = [
+    AGENT_TYPES2 = [
       "orchestrator",
       "executor",
       "researcher",
@@ -8941,8 +8975,8 @@ var init_agent_schema = __esm({
       "agent_instances",
       {
         id: text("id").primaryKey(),
-        agentType: text("agent_type", { enum: AGENT_TYPES }).notNull(),
-        status: text("status", { enum: AGENT_INSTANCE_STATUSES }).notNull().default("starting"),
+        agentType: text("agent_type", { enum: AGENT_TYPES2 }).notNull(),
+        status: text("status", { enum: AGENT_INSTANCE_STATUSES2 }).notNull().default("starting"),
         // T033: FK constraints enforced at DB level by migration; kept soft here
         // to avoid circular dependency with tasks-schema.ts (which imports agent-schema.ts).
         // The migration SQL adds: session_id -> sessions ON DELETE SET NULL,
@@ -9042,8 +9076,8 @@ var init_chain_schema = __esm({
 var tasks_schema_exports = {};
 __export(tasks_schema_exports, {
   ADR_STATUSES: () => ADR_STATUSES,
-  AGENT_INSTANCE_STATUSES: () => AGENT_INSTANCE_STATUSES,
-  AGENT_TYPES: () => AGENT_TYPES,
+  AGENT_INSTANCE_STATUSES: () => AGENT_INSTANCE_STATUSES2,
+  AGENT_TYPES: () => AGENT_TYPES2,
   EXTERNAL_LINK_TYPES: () => EXTERNAL_LINK_TYPES,
   GATE_STATUSES: () => GATE_STATUSES,
   LIFECYCLE_EVIDENCE_TYPES: () => LIFECYCLE_EVIDENCE_TYPES,
@@ -10473,7 +10507,7 @@ __export(brain_schema_exports, {
   BRAIN_MEMORY_TYPES: () => BRAIN_MEMORY_TYPES,
   BRAIN_NODE_TYPES: () => BRAIN_NODE_TYPES,
   BRAIN_OBSERVATION_SOURCE_TYPES: () => BRAIN_OBSERVATION_SOURCE_TYPES,
-  BRAIN_OBSERVATION_TYPES: () => BRAIN_OBSERVATION_TYPES,
+  BRAIN_OBSERVATION_TYPES: () => BRAIN_OBSERVATION_TYPES2,
   BRAIN_OUTCOME_TYPES: () => BRAIN_OUTCOME_TYPES,
   BRAIN_PATTERN_TYPES: () => BRAIN_PATTERN_TYPES,
   BRAIN_STICKY_COLORS: () => BRAIN_STICKY_COLORS,
@@ -10490,7 +10524,7 @@ __export(brain_schema_exports, {
   brainStickyNotes: () => brainStickyNotes
 });
 import { sql as sql5 } from "drizzle-orm";
-var BRAIN_DECISION_TYPES, BRAIN_CONFIDENCE_LEVELS, BRAIN_OUTCOME_TYPES, BRAIN_PATTERN_TYPES, BRAIN_IMPACT_LEVELS, BRAIN_LINK_TYPES, BRAIN_OBSERVATION_TYPES, BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_MEMORY_TYPES, BRAIN_STICKY_STATUSES, BRAIN_STICKY_COLORS, BRAIN_STICKY_PRIORITIES, brainDecisions, brainPatterns, brainLearnings, brainObservations, brainStickyNotes, brainMemoryLinks, brainSchemaMeta, BRAIN_NODE_TYPES, BRAIN_EDGE_TYPES, brainPageNodes, brainPageEdges;
+var BRAIN_DECISION_TYPES, BRAIN_CONFIDENCE_LEVELS, BRAIN_OUTCOME_TYPES, BRAIN_PATTERN_TYPES, BRAIN_IMPACT_LEVELS, BRAIN_LINK_TYPES, BRAIN_OBSERVATION_TYPES2, BRAIN_OBSERVATION_SOURCE_TYPES, BRAIN_MEMORY_TYPES, BRAIN_STICKY_STATUSES, BRAIN_STICKY_COLORS, BRAIN_STICKY_PRIORITIES, brainDecisions, brainPatterns, brainLearnings, brainObservations, brainStickyNotes, brainMemoryLinks, brainSchemaMeta, BRAIN_NODE_TYPES, BRAIN_EDGE_TYPES, brainPageNodes, brainPageEdges;
 var init_brain_schema = __esm({
   "packages/core/src/store/brain-schema.ts"() {
     "use strict";
@@ -10518,7 +10552,7 @@ var init_brain_schema = __esm({
       "informed_by",
       "contradicts"
     ];
-    BRAIN_OBSERVATION_TYPES = [
+    BRAIN_OBSERVATION_TYPES2 = [
       "discovery",
       "change",
       "feature",
@@ -10607,7 +10641,7 @@ var init_brain_schema = __esm({
       "brain_observations",
       {
         id: text("id").primaryKey(),
-        type: text("type", { enum: BRAIN_OBSERVATION_TYPES }).notNull(),
+        type: text("type", { enum: BRAIN_OBSERVATION_TYPES2 }).notNull(),
         title: text("title").notNull(),
         subtitle: text("subtitle"),
         narrative: text("narrative"),
@@ -16861,8 +16895,8 @@ var init_retry = __esm({
 // packages/core/src/agents/index.ts
 var agents_exports = {};
 __export(agents_exports, {
-  AGENT_INSTANCE_STATUSES: () => AGENT_INSTANCE_STATUSES,
-  AGENT_TYPES: () => AGENT_TYPES,
+  AGENT_INSTANCE_STATUSES: () => AGENT_INSTANCE_STATUSES2,
+  AGENT_TYPES: () => AGENT_TYPES2,
   DEFAULT_RETRY_POLICY: () => DEFAULT_RETRY_POLICY,
   HEARTBEAT_INTERVAL_MS: () => HEARTBEAT_INTERVAL_MS,
   MAX_TASKS_PER_AGENT: () => MAX_TASKS_PER_AGENT,
@@ -64178,7 +64212,7 @@ var init_validation_schemas = __esm({
     externalLinkTypeSchema = external_exports.enum(EXTERNAL_LINK_TYPES);
     syncDirectionSchema = external_exports.enum(SYNC_DIRECTIONS);
     lifecycleTransitionTypeSchema = external_exports.enum(LIFECYCLE_TRANSITION_TYPES);
-    brainObservationTypeSchema = external_exports.enum(BRAIN_OBSERVATION_TYPES);
+    brainObservationTypeSchema = external_exports.enum(BRAIN_OBSERVATION_TYPES2);
     brainObservationSourceTypeSchema = external_exports.enum(BRAIN_OBSERVATION_SOURCE_TYPES);
     brainDecisionTypeSchema = external_exports.enum(BRAIN_DECISION_TYPES);
     brainConfidenceLevelSchema = external_exports.enum(BRAIN_CONFIDENCE_LEVELS);
@@ -64348,8 +64382,8 @@ var init_validation_schemas = __esm({
     );
     insertAgentErrorLogSchema = createInsertSchema2(agentErrorLog);
     selectAgentErrorLogSchema = createSelectSchema2(agentErrorLog);
-    agentInstanceStatusSchema = external_exports.enum(AGENT_INSTANCE_STATUSES);
-    agentTypeSchema = external_exports.enum(AGENT_TYPES);
+    agentInstanceStatusSchema = external_exports.enum(AGENT_INSTANCE_STATUSES2);
+    agentTypeSchema = external_exports.enum(AGENT_TYPES2);
   }
 });
 
@@ -67850,6 +67884,162 @@ var init_bootstrap = __esm({
   }
 });
 
+// packages/core/src/sessions/snapshot.ts
+async function serializeSession(projectRoot, options = {}, accessor) {
+  const acc = accessor ?? await getAccessor(projectRoot);
+  const maxObs = options.maxObservations ?? 10;
+  const maxDescLen = options.maxDescriptionLength ?? 500;
+  const sessions2 = await acc.loadSessions();
+  let session;
+  if (options.sessionId) {
+    session = sessions2.find((s) => s.id === options.sessionId);
+  } else {
+    session = sessions2.filter((s) => s.status === "active").sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime())[0];
+  }
+  if (!session) {
+    throw new CleoError(
+      31 /* SESSION_NOT_FOUND */,
+      options.sessionId ? `Session '${options.sessionId}' not found` : "No active session to serialize",
+      { fix: "Use 'cleo session list' to see available sessions" }
+    );
+  }
+  const handoff = await computeHandoff(projectRoot, { sessionId: session.id });
+  const decisionLog = await getDecisionLog(projectRoot, { sessionId: session.id });
+  const decisions = decisionLog.map((d) => ({
+    decision: d.decision,
+    rationale: d.rationale,
+    taskId: d.taskId,
+    recordedAt: d.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+  }));
+  let observations = [];
+  try {
+    const { searchBrainCompact: searchBrainCompact2 } = await Promise.resolve().then(() => (init_brain_retrieval(), brain_retrieval_exports));
+    const results = await searchBrainCompact2(projectRoot, {
+      query: session.id,
+      limit: maxObs,
+      tables: ["observations"]
+    });
+    if (Array.isArray(results)) {
+      observations = results.map(
+        (r) => ({
+          id: r.id,
+          text: r.text ?? "",
+          type: r.type ?? "discovery",
+          createdAt: r.createdAt ?? ""
+        })
+      );
+    }
+  } catch {
+  }
+  let activeTask = null;
+  if (session.taskWork?.taskId) {
+    try {
+      const { tasks: tasks2 } = await acc.queryTasks({});
+      const task = tasks2.find((t) => t.id === session.taskWork?.taskId);
+      if (task) {
+        const desc7 = task.description ?? "";
+        activeTask = {
+          taskId: task.id,
+          title: task.title,
+          status: task.status,
+          priority: task.priority ?? "medium",
+          description: desc7.length > maxDescLen ? desc7.slice(0, maxDescLen) + "..." : desc7,
+          acceptance: Array.isArray(task.acceptance) ? task.acceptance.join("\n") : task.acceptance ?? void 0
+        };
+      }
+    } catch {
+    }
+  }
+  const startTime = new Date(session.startedAt).getTime();
+  const now2 = Date.now();
+  const durationMinutes = Math.round((now2 - startTime) / 6e4);
+  return {
+    version: SNAPSHOT_VERSION,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    session,
+    handoff,
+    decisions,
+    observations,
+    activeTask,
+    durationMinutes
+  };
+}
+async function restoreSession(projectRoot, snapshot, options = {}, accessor) {
+  if (snapshot.version > SNAPSHOT_VERSION) {
+    throw new CleoError(
+      6 /* VALIDATION_ERROR */,
+      `Snapshot version ${snapshot.version} is newer than supported version ${SNAPSHOT_VERSION}`,
+      { fix: "Upgrade @cleocode/core to a newer version that supports this snapshot format" }
+    );
+  }
+  const acc = accessor ?? await getAccessor(projectRoot);
+  const activate = options.activate ?? true;
+  if (activate) {
+    const sessions2 = await acc.loadSessions();
+    const scope = snapshot.session.scope;
+    const activeConflict = sessions2.find(
+      (s) => s.status === "active" && s.scope.type === scope.type && s.scope.epicId === scope.epicId && s.id !== snapshot.session.id
+    );
+    if (activeConflict) {
+      throw new CleoError(
+        32 /* SCOPE_CONFLICT */,
+        `Active session '${activeConflict.id}' already exists for scope ${scope.type}${scope.epicId ? ":" + scope.epicId : ""}`,
+        {
+          fix: `End the active session first with 'cleo session end' or restore without activating`,
+          alternatives: [
+            { action: "End conflicting session", command: "cleo session end" },
+            { action: "Restore without activating", command: "Restore with activate: false" }
+          ]
+        }
+      );
+    }
+  }
+  const restoredSession = {
+    ...snapshot.session,
+    status: activate ? "active" : snapshot.session.status,
+    notes: [
+      ...snapshot.session.notes ?? [],
+      `Restored from snapshot at ${(/* @__PURE__ */ new Date()).toISOString()} (captured ${snapshot.capturedAt}, duration ${snapshot.durationMinutes}m)`
+    ],
+    resumeCount: (snapshot.session.resumeCount ?? 0) + 1
+  };
+  if (options.agent) {
+    restoredSession.agent = options.agent;
+    restoredSession.notes = [
+      ...restoredSession.notes ?? [],
+      `Agent handoff: ${snapshot.session.agent ?? "unknown"} \u2192 ${options.agent}`
+    ];
+  }
+  restoredSession.handoffJson = JSON.stringify(snapshot.handoff);
+  await acc.upsertSingleSession(restoredSession);
+  try {
+    const { hooks: hooks2 } = await Promise.resolve().then(() => (init_registry(), registry_exports));
+    await hooks2.dispatch("onSessionStart", projectRoot, {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId: restoredSession.id,
+      name: restoredSession.name,
+      scope: restoredSession.scope,
+      agent: restoredSession.agent,
+      restored: true,
+      snapshotCapturedAt: snapshot.capturedAt
+    });
+  } catch {
+  }
+  return restoredSession;
+}
+var SNAPSHOT_VERSION;
+var init_snapshot2 = __esm({
+  "packages/core/src/sessions/snapshot.ts"() {
+    "use strict";
+    init_src();
+    init_errors3();
+    init_data_accessor();
+    init_decisions();
+    init_handoff();
+    SNAPSHOT_VERSION = 1;
+  }
+});
+
 // packages/core/src/cleo.ts
 import path from "node:path";
 var Cleo;
@@ -67872,6 +68062,7 @@ var init_cleo = __esm({
     init_link_store();
     init_release2();
     init_sessions();
+    init_snapshot2();
     init_sticky();
     init_data_accessor();
     init_task_work();
@@ -67981,7 +68172,15 @@ var init_cleo = __esm({
           recordAssumption: (p) => recordAssumption(root, p),
           contextDrift: (p) => getContextDrift(root, p),
           decisionLog: (p) => getDecisionLog(root, { sessionId: p?.sessionId, taskId: p?.taskId }),
-          lastHandoff: (scope) => getLastHandoff(root, scope)
+          lastHandoff: (scope) => getLastHandoff(root, scope),
+          serialize: (p) => serializeSession(root, {
+            sessionId: p?.sessionId,
+            maxObservations: p?.maxObservations
+          }),
+          restore: (snapshot, p) => restoreSession(root, snapshot, {
+            agent: p?.agent,
+            activate: p?.activate
+          })
         };
       }
       // === Memory ===
@@ -68158,7 +68357,10 @@ var init_cleo = __esm({
 var src_exports = {};
 __export(src_exports, {
   ADR_STATUSES: () => ADR_STATUSES,
+  AGENT_INSTANCE_STATUSES: () => AGENT_INSTANCE_STATUSES,
+  AGENT_TYPES: () => AGENT_TYPES,
   AdapterManager: () => AdapterManager,
+  BRAIN_OBSERVATION_TYPES: () => BRAIN_OBSERVATION_TYPES,
   CORE_PROTECTED_FILES: () => CORE_PROTECTED_FILES,
   Cleo: () => Cleo,
   CleoError: () => CleoError,
@@ -68334,6 +68536,7 @@ __export(src_exports, {
   remote: () => remote_exports,
   research: () => research_exports,
   resolveProjectPath: () => resolveProjectPath,
+  restoreSession: () => restoreSession,
   resumeSession: () => resumeSession,
   roadmap: () => roadmap_exports,
   routing: () => routing_exports,
@@ -68350,6 +68553,7 @@ __export(src_exports, {
   selectSessionSchema: () => selectSessionSchema,
   selectTaskSchema: () => selectTaskSchema,
   sequence: () => sequence_exports,
+  serializeSession: () => serializeSession,
   sessionStatus: () => sessionStatus,
   sessionStatusSchema: () => sessionStatusSchema,
   sessions: () => sessions_exports,
@@ -68460,6 +68664,7 @@ var init_src2 = __esm({
     init_migration();
     init_reconciliation();
     init_sessions();
+    init_snapshot2();
     init_migrate();
     init_storage_preflight();
     init_task_work();
@@ -79133,9 +79338,12 @@ var init_plan = __esm({
 var internal_exports = {};
 __export(internal_exports, {
   ADR_STATUSES: () => ADR_STATUSES,
+  AGENT_INSTANCE_STATUSES: () => AGENT_INSTANCE_STATUSES,
+  AGENT_TYPES: () => AGENT_TYPES,
   ALL_VALID_STATUSES: () => ALL_VALID_STATUSES,
   AdapterManager: () => AdapterManager,
   AuditLogInsertSchema: () => AuditLogInsertSchema,
+  BRAIN_OBSERVATION_TYPES: () => BRAIN_OBSERVATION_TYPES,
   BUILD_CONFIG: () => BUILD_CONFIG,
   CORE_PROTECTED_FILES: () => CORE_PROTECTED_FILES,
   Cleo: () => Cleo,
@@ -79705,6 +79913,7 @@ __export(internal_exports, {
   resolveTask: () => resolveTask,
   restoreBackup: () => restoreBackup,
   restoreFromBackup: () => restoreFromBackup,
+  restoreSession: () => restoreSession,
   resumeSession: () => resumeSession,
   roadmap: () => roadmap_exports,
   rollbackRelease: () => rollbackRelease,
@@ -79732,6 +79941,7 @@ __export(internal_exports, {
   selectSessionSchema: () => selectSessionSchema,
   selectTaskSchema: () => selectTaskSchema,
   sequence: () => sequence_exports,
+  serializeSession: () => serializeSession,
   sessionStatus: () => sessionStatus,
   sessionStatusSchema: () => sessionStatusSchema,
   sessions: () => sessions_exports,