@cleocode/core 2026.3.43 → 2026.3.45

package/src/sessions/briefing.ts

@@ -17,13 +17,13 @@
  * @epic T4914
  */
 
-import type { FileMeta, TaskWorkState } from '@cleocode/contracts';
+import type { Task, TaskWorkState } from '@cleocode/contracts';
 import type { SessionMemoryContext } from '../memory/session-memory.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 import { depsReady } from '../tasks/deps-ready.js';
 import { getLastHandoff, type HandoffData } from './handoff.js';
-import type { TaskFileExt } from './types.js';
+import type { TaskWorkStateExt } from './types.js';
 
 /**
  * Task summary for briefing output.
@@ -138,15 +138,9 @@ export async function computeBriefing(
 ): Promise<SessionBriefing> {
   const accessor = await getAccessor(projectRoot);
   const { tasks } = await accessor.queryTasks({});
-  const focus = await accessor.getMetaValue<TaskWorkState>('focus_state');
-  const fileMeta = await accessor.getMetaValue<FileMeta>('file_meta');
-
-  // Build a TaskFileExt-compatible shape from targeted queries
-  const current = {
-    tasks,
-    focus: focus ?? undefined,
-    _meta: fileMeta ?? undefined,
-  } as unknown as TaskFileExt;
+  const focus = (await accessor.getMetaValue<TaskWorkState>('focus_state')) as
+    | TaskWorkStateExt
+    | undefined;
 
   // Build task map for quick lookups
   const taskMap = new Map(tasks.map((t) => [t.id, t]));
@@ -155,19 +149,16 @@ export async function computeBriefing(
   const scopeFilter = await parseScope(options.scope, accessor);
 
   // Compute in-scope task IDs (undefined = all tasks in scope)
-  const scopeTaskIds = getScopeTaskIdSet(
-    scopeFilter,
-    tasks as unknown as Array<{ id: string; parentId?: string; [key: string]: unknown }>,
-  );
+  const scopeTaskIds = getScopeTaskIdSet(scopeFilter, tasks);
 
   // 1. Last session handoff
   const lastSession = await computeLastSession(projectRoot, scopeFilter);
 
   // 2. Current active task
-  const currentTaskInfo = computeCurrentTask(current, taskMap);
+  const currentTaskInfo = computeCurrentTask(focus, taskMap);
 
   // 3. Next tasks (leverage-scored)
-  const nextTasks = computeNextTasks(tasks, taskMap, current, {
+  const nextTasks = computeNextTasks(tasks, taskMap, focus, {
     maxTasks: options.maxNextTasks ?? 5,
     scopeTaskIds,
   });
@@ -191,7 +182,7 @@ export async function computeBriefing(
   });
 
   // 7. Pipeline stage (optional - may not be available)
-  const pipelineStage = computePipelineStage(current);
+  const pipelineStage = await computePipelineStage(focus);
 
   // 8. Brain memory context (optional, best-effort)
   let memoryContext: SessionMemoryContext | undefined;
@@ -259,7 +250,7 @@ async function parseScope(
  */
 function getScopeTaskIdSet(
   scopeFilter: { type: 'global' | 'epic'; epicId?: string } | undefined,
-  tasks: Array<{ id: string; parentId?: string; [key: string]: unknown }>,
+  tasks: Task[],
 ): Set<string> | undefined {
   if (!scopeFilter || scopeFilter.type === 'global') {
     return undefined; // All tasks in scope
@@ -325,10 +316,10 @@ async function computeLastSession(
  * Compute current active task from task file.
  */
 function computeCurrentTask(
-  current: TaskFileExt,
+  focus: TaskWorkStateExt | undefined,
   taskMap: Map<string, unknown>,
 ): CurrentTaskInfo | null {
-  const focusTaskId = current.focus?.currentTask;
+  const focusTaskId = focus?.currentTask;
   if (!focusTaskId) return null;
 
   const task = taskMap.get(focusTaskId) as
@@ -376,7 +367,7 @@ function calculateLeverage(taskId: string, taskMap: Map<string, unknown>): numbe
 function computeNextTasks(
   tasks: unknown[],
   taskMap: Map<string, unknown>,
-  current: TaskFileExt,
+  focus: TaskWorkStateExt | undefined,
   options: { maxTasks: number; scopeTaskIds?: Set<string> },
 ): BriefingTask[] {
   const pendingTasks = tasks.filter((t) => {
@@ -387,7 +378,7 @@ function computeNextTasks(
   });
 
   const scored: BriefingTask[] = [];
-  const currentPhase = current.focus?.currentPhase;
+  const currentPhase = focus?.currentPhase;
 
   for (const task of pendingTasks) {
     const t = task as {
@@ -593,28 +584,22 @@ function calculateEpicCompletion(epicId: string, taskMap: Map<string, unknown>):
 /**
  * Compute pipeline stage info from task file metadata.
  */
-function computePipelineStage(current: TaskFileExt): PipelineStageInfo | undefined {
-  // Try to get from _meta or focus
-  const stage = (current._meta as Record<string, unknown>)?.pipelineStage as string | undefined;
-  const stageStatus = (current._meta as Record<string, unknown>)?.pipelineStageStatus as
-    | string
-    | undefined;
+async function computePipelineStage(
+  focus: TaskWorkStateExt | undefined,
+): Promise<PipelineStageInfo | undefined> {
+  const taskId = focus?.currentTask;
+  if (!taskId) return undefined;
 
-  if (stage) {
-    return {
-      currentStage: stage,
-      stageStatus: stageStatus || 'active',
-    };
-  }
+  try {
+    const { getPipeline } = await import('../lifecycle/pipeline.js');
+    const pipeline = await getPipeline(taskId);
+    if (!pipeline) return undefined;
 
-  // Try from lifecycle state if available
-  const lifecycleState = current._meta?.lifecycleState as string | undefined;
-  if (lifecycleState) {
     return {
-      currentStage: lifecycleState,
-      stageStatus: 'active',
+      currentStage: pipeline.currentStage,
+      stageStatus: pipeline.isActive ? 'active' : (pipeline.status ?? 'completed'),
     };
+  } catch {
+    return undefined;
   }
-
-  return undefined;
 }

package/src/sessions/handoff.ts

@@ -15,12 +15,11 @@
 
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import type { FileMeta, Session, TaskWorkState } from '@cleocode/contracts';
+import type { Session, Task } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
 import { getAccessor } from '../store/data-accessor.js';
 import { getDecisionLog } from './decisions.js';
-import type { TaskFileExt } from './types.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -77,15 +76,8 @@ export async function computeHandoff(
     throw new CleoError(ExitCode.SESSION_NOT_FOUND, `Session '${options.sessionId}' not found`);
   }
 
-  // Load task data for scope analysis
+  // Load tasks directly from SQLite via DataAccessor
   const { tasks } = await accessor.queryTasks({});
-  const focus = await accessor.getMetaValue<TaskWorkState>('focus_state');
-  const fileMeta = await accessor.getMetaValue<FileMeta>('file_meta');
-  const current = {
-    tasks,
-    focus: focus ?? undefined,
-    _meta: fileMeta ?? undefined,
-  } as unknown as TaskFileExt;
 
   // Get decisions recorded during this session
   const decisions = await getDecisionLog(projectRoot, { sessionId: options.sessionId });
@@ -97,9 +89,9 @@ export async function computeHandoff(
     tasksCompleted: session.tasksCompleted ?? [],
     tasksCreated: session.tasksCreated ?? [],
     decisionsRecorded: decisions.length,
-    nextSuggested: computeNextSuggested(session, current),
-    openBlockers: findOpenBlockers(current, session),
-    openBugs: findOpenBugs(current, session),
+    nextSuggested: computeNextSuggested(session, tasks),
+    openBlockers: findOpenBlockers(tasks, session),
+    openBugs: findOpenBugs(tasks, session),
   };
 
   // Apply human overrides
@@ -117,20 +109,15 @@ export async function computeHandoff(
  * Compute top-3 next suggested tasks.
  * Prioritizes uncompleted tasks within the session scope.
  */
-function computeNextSuggested(session: Session, current: TaskFileExt): string[] {
-  const suggestions: string[] = [];
-
-  if (!current.tasks) return suggestions;
-
+function computeNextSuggested(session: Session, tasks: Task[]): string[] {
   // Filter to tasks in scope
-  const scopeTaskIds = getScopeTaskIds(session, current);
+  const scopeTaskIds = getScopeTaskIds(session, tasks);
 
   // Get uncompleted tasks in scope
-  const pendingTasks = current.tasks.filter(
+  const pendingTasks = tasks.filter(
     (t) =>
       scopeTaskIds.has(t.id) &&
       t.status !== 'done' &&
-      t.status !== 'completed' &&
       t.status !== 'archived' &&
       t.status !== 'cancelled',
   );
@@ -145,11 +132,9 @@ function computeNextSuggested(session: Session, current: TaskFileExt): string[]
 
   pendingTasks.sort((a, b) => {
     const priorityDiff =
-      (priorityOrder[a.priority as string] ?? 99) - (priorityOrder[b.priority as string] ?? 99);
+      (priorityOrder[a.priority ?? 'medium'] ?? 99) - (priorityOrder[b.priority ?? 'medium'] ?? 99);
     if (priorityDiff !== 0) return priorityDiff;
-    const aCreated = typeof a.createdAt === 'string' ? a.createdAt : '1970-01-01T00:00:00Z';
-    const bCreated = typeof b.createdAt === 'string' ? b.createdAt : '1970-01-01T00:00:00Z';
-    return new Date(aCreated).getTime() - new Date(bCreated).getTime();
+    return (a.createdAt ?? '').localeCompare(b.createdAt ?? '');
   });
 
   // Take top 3
@@ -159,87 +144,68 @@ function computeNextSuggested(session: Session, current: TaskFileExt): string[]
 /**
  * Find tasks with blockers in the session scope.
  */
-function findOpenBlockers(current: TaskFileExt, session: Session): string[] {
-  const blockers: string[] = [];
-
-  if (!current.tasks) return blockers;
-
-  const scopeTaskIds = getScopeTaskIds(session, current);
+function findOpenBlockers(tasks: Task[], session: Session): string[] {
+  const scopeTaskIds = getScopeTaskIds(session, tasks);
 
-  // Find blocked tasks in scope
-  const blockedTasks = current.tasks.filter(
-    (t) => scopeTaskIds.has(t.id) && t.status === 'blocked',
-  );
-
-  return blockedTasks.map((t) => t.id);
+  return tasks.filter((t) => scopeTaskIds.has(t.id) && t.status === 'blocked').map((t) => t.id);
 }
 
 /**
  * Find open bugs in the session scope.
  */
-function findOpenBugs(current: TaskFileExt, session: Session): string[] {
-  const bugs: string[] = [];
-
-  if (!current.tasks) return bugs;
-
-  const scopeTaskIds = getScopeTaskIds(session, current);
-
-  // Find bug-type tasks that aren't closed
-  const bugTasks = current.tasks.filter(
-    (t) =>
-      scopeTaskIds.has(t.id) &&
-      (t.type === 'bug' ||
-        (Array.isArray(t.labels) && t.labels.some((l: string) => l === 'bug'))) &&
-      t.status !== 'done' &&
-      t.status !== 'completed' &&
-      t.status !== 'archived' &&
-      t.status !== 'cancelled',
-  );
-
-  return bugTasks.map((t) => t.id);
+function findOpenBugs(tasks: Task[], session: Session): string[] {
+  const scopeTaskIds = getScopeTaskIds(session, tasks);
+
+  return tasks
+    .filter(
+      (t) =>
+        scopeTaskIds.has(t.id) &&
+        (t.labels ?? []).includes('bug') &&
+        t.status !== 'done' &&
+        t.status !== 'archived' &&
+        t.status !== 'cancelled',
+    )
+    .map((t) => t.id);
 }
 
 /**
  * Get set of task IDs within the session scope.
  */
-function getScopeTaskIds(session: Session, current: TaskFileExt): Set<string> {
+function getScopeTaskIds(session: Session, tasks: Task[]): Set<string> {
   const taskIds = new Set<string>();
 
-  if (!current.tasks) return taskIds;
-
   if (session.scope.type === 'global') {
-    // Global scope: all tasks
-    for (const t of current.tasks) {
+    for (const t of tasks) {
       taskIds.add(t.id);
     }
-  } else {
-    // Epic/task scope: root task and descendants
-    // Prefer rootTaskId (engine-layer), fall back to epicId (core-layer)
-    const rootId = session.scope.rootTaskId ?? session.scope.epicId;
-    if (!rootId) {
-      // No root ID, fall back to global
-      for (const t of current.tasks) {
-        taskIds.add(t.id);
-      }
-      return taskIds;
+    return taskIds;
+  }
+
+  // Epic/task scope: root task and descendants
+  const rootId = session.scope.rootTaskId ?? session.scope.epicId;
+  if (!rootId) {
+    // No root ID, fall back to global
+    for (const t of tasks) {
+      taskIds.add(t.id);
     }
+    return taskIds;
+  }
 
-    const addDescendants = (taskId: string) => {
-      taskIds.add(taskId);
-      current.tasks?.forEach((t) => {
-        if (t.parentId === taskId) {
-          addDescendants(t.id);
-        }
-      });
-    };
+  const addDescendants = (taskId: string) => {
+    taskIds.add(taskId);
+    for (const t of tasks) {
+      if (t.parentId === taskId) {
+        addDescendants(t.id);
+      }
+    }
+  };
 
-    addDescendants(rootId);
+  addDescendants(rootId);
 
-    // Include explicitTaskIds if present in scope
-    if (session.scope.explicitTaskIds) {
-      for (const id of session.scope.explicitTaskIds) {
-        taskIds.add(id);
-      }
+  // Include explicitTaskIds if present in scope
+  if (session.scope.explicitTaskIds) {
+    for (const id of session.scope.explicitTaskIds) {
+      taskIds.add(id);
     }
   }
 

package/src/sessions/index.ts

@@ -471,4 +471,8 @@ export { getSessionStats } from './session-stats.js';
 export { suspendSession } from './session-suspend.js';
 export { switchSession } from './session-switch.js';
 export { SessionView } from './session-view.js';
-export type { AssumptionRecord, DecisionRecord, TaskFileExt, TaskWorkStateExt } from './types.js';
+export type {
+  AssumptionRecord,
+  DecisionRecord,
+  TaskWorkStateExt,
+} from './types.js';

package/src/sessions/types.ts

@@ -5,6 +5,8 @@
  * @epic T4654
  */
 
+import type { SessionNote, TaskWorkState } from '@cleocode/contracts';
+
 /**
  * Session object (engine-compatible).
  */
@@ -67,45 +69,22 @@ export interface SessionRecord {
 
 /**
  * Task work state from the task store.
+ *
+ * Extends the strict contracts {@link TaskWorkState} with required-null
+ * fields for session engine compatibility. The engine layer always expects
+ * these fields to be present (even if null), whereas the contracts type
+ * marks them as optional.
  */
-export interface TaskWorkStateExt {
+export interface TaskWorkStateExt extends TaskWorkState {
   currentTask: string | null;
   currentPhase: string | null;
   blockedUntil: string | null;
   sessionNote: string | null;
-  sessionNotes: unknown[];
+  sessionNotes: SessionNote[];
   nextAction: string | null;
   primarySession: string | null;
 }
 
-/**
- * Task file structure (subset for session operations).
- */
-export interface TaskFileExt {
-  focus?:
-    | TaskWorkStateExt
-    | { currentTask?: string | null; currentPhase?: string | null; [key: string]: unknown };
-  _meta?: {
-    schemaVersion: string;
-    checksum?: string;
-    configVersion?: string;
-    lastSessionId?: string | null;
-    activeSessionCount?: number;
-    sessionsFile?: string | null;
-    generation?: number;
-    [key: string]: unknown;
-  };
-  tasks?: Array<{
-    id: string;
-    status: string;
-    parentId?: string;
-    completedAt?: string;
-    [key: string]: unknown;
-  }>;
-  lastUpdated?: string;
-  [key: string]: unknown;
-}
-
 /**
  * Decision record stored in decisions.jsonl.
  */
@@ -131,16 +110,3 @@ export interface AssumptionRecord {
   validatedAt: string | null;
   timestamp: string;
 }
-
-/**
- * Convert a TaskFile (from contracts) to the looser TaskFileExt shape.
- * Accepts any object with at least the basic TaskFileExt structure.
- * The runtime object is the same reference — this only changes the TS type.
- */
-export function toTaskFileExt<
-  T extends { _meta?: object; tasks?: unknown[]; focus?: object; lastUpdated?: string },
->(taskFile: T): TaskFileExt {
-  // The incoming object structurally satisfies TaskFileExt at runtime;
-  // this conversion bridges the strict contracts type to the loose session type.
-  return taskFile as TaskFileExt;
-}

package/src/signaldock/signaldock-transport.ts

@@ -104,8 +104,11 @@ export class SignalDockTransport implements AgentTransport {
     };
   }
 
-  async poll(agentId: string, _since?: string): Promise<Message[]> {
-    const messages = await this.request<Message[]>('GET', '/messages/poll/new', undefined, agentId);
+  async poll(agentId: string, since?: string): Promise<Message[]> {
+    const path = since
+      ? `/messages/poll/new?since=${encodeURIComponent(since)}`
+      : '/messages/poll/new';
+    const messages = await this.request<Message[]>('GET', path, undefined, agentId);
     return messages;
   }
 

package/src/skills/injection/subagent.ts

@@ -19,10 +19,9 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Task } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../../errors.js';
-import { getProjectRoot, getTaskPath } from '../../paths.js';
+import { getProjectRoot } from '../../paths.js';
 import { findSkill } from '../discovery.js';
 import { injectTokens, type TokenValues } from './token.js';
 
@@ -55,15 +54,10 @@ export function loadProtocolBase(cwd?: string): string | null {
  * Build task context block for injection into a subagent prompt.
  * @task T4521
  */
-export function buildTaskContext(taskId: string, cwd?: string): string {
-  const taskPath = getTaskPath(cwd);
-  if (!existsSync(taskPath)) {
-    return `## Task Context\n\n**Task**: ${taskId}\n**Status**: unknown\n`;
-  }
-
-  const data = JSON.parse(readFileSync(taskPath, 'utf-8'));
-  const tasks: Task[] = data.tasks ?? [];
-  const task = tasks.find((t) => t.id === taskId);
+export async function buildTaskContext(taskId: string, cwd?: string): Promise<string> {
+  const { getAccessor } = await import('../../store/data-accessor.js');
+  const acc = await getAccessor(cwd);
+  const task = await acc.loadSingleTask(taskId);
 
   if (!task) {
     return `## Task Context\n\n**Task**: ${taskId}\n**Status**: not found\n`;
@@ -165,15 +159,15 @@ export function filterProtocolByTier(content: string, tier: 0 | 1 | 2): string {
  * Composes: skill content + protocol base + task context.
  * @task T4521
  */
-export function injectProtocol(
+export async function injectProtocol(
   skillContent: string,
   taskId: string,
   tokenValues: TokenValues,
   cwd?: string,
   tier?: 0 | 1 | 2,
-): string {
+): Promise<string> {
   const protocolBase = loadProtocolBase(cwd);
-  const taskContext = buildTaskContext(taskId, cwd);
+  const taskContext = await buildTaskContext(taskId, cwd);
 
   // Inject tokens into skill content
   const resolvedSkill = injectTokens(skillContent, tokenValues);
@@ -202,13 +196,13 @@ export function injectProtocol(
  * High-level function that loads the skill, injects protocol, and returns the prompt.
  * @task T4521
  */
-export function orchestratorSpawnSkill(
+export async function orchestratorSpawnSkill(
   taskId: string,
   skillName: string,
   tokenValues: TokenValues,
   cwd?: string,
   tier?: 0 | 1 | 2,
-): string {
+): Promise<string> {
   // Find the skill
   const skill = findSkill(skillName, cwd);
   if (!skill || !skill.content) {

package/src/skills/manifests/contribution.ts

@@ -12,8 +12,7 @@
 
 import { randomBytes } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
-import type { Task } from '@cleocode/contracts';
-import { getTaskPath } from '../../paths.js';
+import { getAccessor } from '../../store/data-accessor.js';
 import type { ManifestEntry } from '../types.js';
 
 // ============================================================================
@@ -65,20 +64,13 @@ export function generateContributionId(taskId: string): string {
  * Validate that a task is suitable for contribution protocol.
  * @task T4520
  */
-export function validateContributionTask(
+export async function validateContributionTask(
   taskId: string,
   cwd?: string,
-): { valid: boolean; issues: string[] } {
+): Promise<{ valid: boolean; issues: string[] }> {
   const issues: string[] = [];
-  const taskPath = getTaskPath(cwd);
-
-  if (!existsSync(taskPath)) {
-    return { valid: false, issues: ['Todo file not found'] };
-  }
-
-  const data = JSON.parse(readFileSync(taskPath, 'utf-8'));
-  const tasks: Task[] = data.tasks ?? [];
-  const task = tasks.find((t) => t.id === taskId);
+  const acc = await getAccessor(cwd);
+  const task = await acc.loadSingleTask(taskId);
 
   if (!task) {
     return { valid: false, issues: [`Task ${taskId} not found`] };