@cleocode/core 2026.3.42 → 2026.3.44

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`] };

package/src/skills/orchestrator/__tests__/spawn-tier.test.ts

@@ -29,6 +29,22 @@ vi.mock('../../discovery.js', () => ({
   mapSkillName: vi.fn(() => ({ canonical: 'task-executor', mapped: true })),
 }));
 
+vi.mock('../../../store/data-accessor.js', () => ({
+  getAccessor: vi.fn().mockResolvedValue({
+    loadSingleTask: vi.fn().mockResolvedValue({
+      id: 'T100',
+      title: 'Test task',
+      status: 'active',
+      description: 'A test',
+      priority: 'medium',
+      labels: [],
+      depends: [],
+    }),
+    loadTasks: vi.fn().mockResolvedValue([]),
+    queryTasks: vi.fn().mockResolvedValue({ tasks: [], total: 0 }),
+  }),
+}));
+
 import { existsSync, readFileSync } from 'node:fs';
 import { findSkill } from '../../discovery.js';
 import { injectProtocol, orchestratorSpawnSkill } from '../../injection/subagent.js';
@@ -67,7 +83,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
     } as any);
   });
 
-  it('passes tier 0 through — output excludes standard and orchestrator', () => {
+  it('passes tier 0 through — output excludes standard and orchestrator', async () => {
     vi.mocked(readFileSync).mockImplementation((path: unknown) => {
       const p = String(path);
       if (p.includes('subagent-protocol-base')) return TIERED_PROTOCOL;
@@ -75,7 +91,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
       return '';
     });
 
-    const result = orchestratorSpawnSkill(
+    const result = await orchestratorSpawnSkill(
       'T100',
       'test-skill',
       { TASK_ID: 'T100' },
@@ -89,7 +105,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
     expect(result).toContain('Test Skill');
   });
 
-  it('passes tier 1 through — output includes minimal + standard', () => {
+  it('passes tier 1 through — output includes minimal + standard', async () => {
     vi.mocked(readFileSync).mockImplementation((path: unknown) => {
       const p = String(path);
       if (p.includes('subagent-protocol-base')) return TIERED_PROTOCOL;
@@ -97,7 +113,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
       return '';
     });
 
-    const result = orchestratorSpawnSkill(
+    const result = await orchestratorSpawnSkill(
       'T100',
       'test-skill',
       { TASK_ID: 'T100' },
@@ -110,7 +126,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
     expect(result).not.toContain('Orchestrator Section');
   });
 
-  it('passes tier 2 through — output includes all tiers', () => {
+  it('passes tier 2 through — output includes all tiers', async () => {
     vi.mocked(readFileSync).mockImplementation((path: unknown) => {
       const p = String(path);
       if (p.includes('subagent-protocol-base')) return TIERED_PROTOCOL;
@@ -118,7 +134,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
       return '';
     });
 
-    const result = orchestratorSpawnSkill(
+    const result = await orchestratorSpawnSkill(
       'T100',
       'test-skill',
       { TASK_ID: 'T100' },
@@ -131,7 +147,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
     expect(result).toContain('Orchestrator Section');
   });
 
-  it('omitting tier includes full protocol (backward compat)', () => {
+  it('omitting tier includes full protocol (backward compat)', async () => {
     vi.mocked(readFileSync).mockImplementation((path: unknown) => {
       const p = String(path);
       if (p.includes('subagent-protocol-base')) return TIERED_PROTOCOL;
@@ -140,7 +156,7 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
     });
 
     // No tier parameter — should pass through unfiltered
-    const result = orchestratorSpawnSkill(
+    const result = await orchestratorSpawnSkill(
       'T100',
       'test-skill',
       { TASK_ID: 'T100' },
@@ -153,12 +169,12 @@ describe('orchestratorSpawnSkill tier passthrough', () => {
     expect(result).toContain('TIER:orchestrator');
   });
 
-  it('throws when skill not found', () => {
+  it('throws when skill not found', async () => {
     vi.mocked(findSkill).mockReturnValue(null);
 
-    expect(() => {
-      orchestratorSpawnSkill('T100', 'nonexistent', { TASK_ID: 'T100' }, '/mock/project', 0);
-    }).toThrow(/Skill not found/);
+    await expect(
+      orchestratorSpawnSkill('T100', 'nonexistent', { TASK_ID: 'T100' }, '/mock/project', 0),
+    ).rejects.toThrow(/Skill not found/);
   });
 });
 
@@ -168,29 +184,27 @@ describe('injectProtocol tier parameter', () => {
     vi.mocked(existsSync).mockReturnValue(true);
   });
 
-  it('tier undefined leaves protocol unfiltered', () => {
+  it('tier undefined leaves protocol unfiltered', async () => {
     vi.mocked(readFileSync).mockImplementation((path: unknown) => {
       const p = String(path);
       if (p.includes('subagent-protocol-base')) return TIERED_PROTOCOL;
-      if (p.includes('tasks.json')) return MOCK_TASKS_JSON;
       return '';
     });
 
-    const result = injectProtocol('# Skill', 'T100', {}, '/mock/project', undefined);
+    const result = await injectProtocol('# Skill', 'T100', {}, '/mock/project', undefined);
 
     expect(result).toContain('TIER:minimal');
     expect(result).toContain('TIER:orchestrator');
   });
 
-  it('tier 0 filters to minimal only', () => {
+  it('tier 0 filters to minimal only', async () => {
     vi.mocked(readFileSync).mockImplementation((path: unknown) => {
       const p = String(path);
       if (p.includes('subagent-protocol-base')) return TIERED_PROTOCOL;
-      if (p.includes('tasks.json')) return MOCK_TASKS_JSON;
       return '';
     });
 
-    const result = injectProtocol('# Skill', 'T100', {}, '/mock/project', 0);
+    const result = await injectProtocol('# Skill', 'T100', {}, '/mock/project', 0);
 
     expect(result).toContain('Minimal Section');
     expect(result).not.toContain('Standard Section');
@@ -218,43 +232,43 @@ describe('buildPrompt tier passthrough', () => {
     } as any);
   });
 
-  it('buildPrompt with tier 0 filters protocol to minimal only', () => {
-    const result = buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project', 0);
+  it('buildPrompt with tier 0 filters protocol to minimal only', async () => {
+    const result = await buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project', 0);
     expect(result.prompt).toContain('Minimal Section');
     expect(result.prompt).not.toContain('Standard Section');
     expect(result.prompt).not.toContain('Orchestrator Section');
     expect(result.prompt).toContain('SUBAGENT PROTOCOL');
   });
 
-  it('buildPrompt with tier 1 includes minimal + standard', () => {
-    const result = buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project', 1);
+  it('buildPrompt with tier 1 includes minimal + standard', async () => {
+    const result = await buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project', 1);
     expect(result.prompt).toContain('Minimal Section');
     expect(result.prompt).toContain('Standard Section');
     expect(result.prompt).not.toContain('Orchestrator Section');
   });
 
-  it('buildPrompt without tier includes full protocol', () => {
-    const result = buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project');
+  it('buildPrompt without tier includes full protocol', async () => {
+    const result = await buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project');
     // No tier = unfiltered, so tier markers present
     expect(result.prompt).toContain('TIER:minimal');
     expect(result.prompt).toContain('TIER:orchestrator');
   });
 
-  it('buildPrompt injects task context', () => {
-    const result = buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project', 0);
+  it('buildPrompt injects task context', async () => {
+    const result = await buildPrompt('T100', 'TASK-EXECUTOR', '/mock/project', 0);
     expect(result.prompt).toContain('Task Context');
     expect(result.prompt).toContain('T100');
   });
 
-  it('spawn passes tier through', () => {
-    const result = spawn('T100', 'TASK-EXECUTOR', '/mock/project', 0);
+  it('spawn passes tier through', async () => {
+    const result = await spawn('T100', 'TASK-EXECUTOR', '/mock/project', 0);
     expect(result.prompt).toContain('Minimal Section');
     expect(result.prompt).not.toContain('Orchestrator Section');
     expect(result.spawnTimestamp).toBeDefined();
   });
 
-  it('spawnBatch passes tier through', () => {
-    const result = spawnBatch(['T100'], 'TASK-EXECUTOR', '/mock/project', 0);
+  it('spawnBatch passes tier through', async () => {
+    const result = await spawnBatch(['T100'], 'TASK-EXECUTOR', '/mock/project', 0);
     expect(result.succeeded).toBe(1);
     expect(result.spawns[0].result!.prompt).toContain('Minimal Section');
     expect(result.spawns[0].result!.prompt).not.toContain('Orchestrator Section');

package/src/skills/orchestrator/spawn.ts

@@ -12,11 +12,11 @@
  * @task T4519
  */
 
-import { existsSync, readFileSync } from 'node:fs';
 import type { Task } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../../errors.js';
-import { getAgentOutputsDir, getTaskPath } from '../../paths.js';
+import { getAgentOutputsDir } from '../../paths.js';
+import { getAccessor } from '../../store/data-accessor.js';
 import { findSkill, mapSkillName } from '../discovery.js';
 import { injectProtocol } from '../injection/subagent.js';
 import type { TokenValues } from '../injection/token.js';
@@ -30,22 +30,14 @@ import type { SpawnPromptResult } from '../types.js';
  * Build a fully-resolved prompt for spawning a subagent.
  * @task T4519
  */
-export function buildPrompt(
+export async function buildPrompt(
   taskId: string,
   templateName: string = 'TASK-EXECUTOR',
   cwd?: string,
   tier?: 0 | 1 | 2,
-): SpawnPromptResult {
-  const taskPath = getTaskPath(cwd);
-
-  if (!existsSync(taskPath)) {
-    throw new CleoError(ExitCode.NOT_FOUND, 'Todo file not found. Run: cleo init');
-  }
-
-  // Load task
-  const data = JSON.parse(readFileSync(taskPath, 'utf-8'));
-  const tasks: Task[] = data.tasks ?? [];
-  const task = tasks.find((t) => t.id === taskId);
+): Promise<SpawnPromptResult> {
+  const acc = await getAccessor(cwd);
+  const task = await acc.loadSingleTask(taskId);
 
   if (!task) {
     throw new CleoError(ExitCode.NOT_FOUND, `Task ${taskId} not found`);
@@ -121,7 +113,7 @@ export function buildPrompt(
   }
 
   // Inject tokens and protocol into template
-  const promptContent = injectProtocol(skill.content, taskId, tokenValues, cwd, tier);
+  const promptContent = await injectProtocol(skill.content, taskId, tokenValues, cwd, tier);
 
   return {
     taskId,
@@ -138,13 +130,13 @@ export function buildPrompt(
  * Generate full spawn command with metadata.
  * @task T4519
  */
-export function spawn(
+export async function spawn(
   taskId: string,
   templateName: string = 'TASK-EXECUTOR',
   cwd?: string,
   tier?: 0 | 1 | 2,
-): SpawnPromptResult & { spawnTimestamp: string } {
-  const result = buildPrompt(taskId, templateName, cwd, tier);
+): Promise<SpawnPromptResult & { spawnTimestamp: string }> {
+  const result = await buildPrompt(taskId, templateName, cwd, tier);
 
   return {
     ...result,
@@ -156,25 +148,20 @@ export function spawn(
  * Check if tasks can be spawned in parallel (no inter-dependencies).
  * @task T4519
  */
-export function canParallelize(
+export async function canParallelize(
   taskIds: string[],
   cwd?: string,
-): {
+): Promise<{
   canParallelize: boolean;
   conflicts: Array<Pick<Task, 'id'> & { dependsOn: string[] }>;
   safeToSpawn: string[];
-} {
+}> {
   if (taskIds.length === 0) {
     return { canParallelize: true, conflicts: [], safeToSpawn: [] };
   }
 
-  const taskPath = getTaskPath(cwd);
-  if (!existsSync(taskPath)) {
-    return { canParallelize: true, conflicts: [], safeToSpawn: taskIds };
-  }
-
-  const data = JSON.parse(readFileSync(taskPath, 'utf-8'));
-  const tasks: Task[] = data.tasks ?? [];
+  const acc = await getAccessor(cwd);
+  const tasks = await acc.loadTasks(taskIds);
   const taskIdSet = new Set(taskIds);
 
   const conflicts: Array<Pick<Task, 'id'> & { dependsOn: string[] }> = [];
@@ -229,17 +216,17 @@ export interface BatchSpawnResult {
  * @task T4712
  * @epic T4663
  */
-export function spawnBatch(
+export async function spawnBatch(
   taskIds: string[],
   templateName?: string,
   cwd?: string,
   tier?: 0 | 1 | 2,
-): BatchSpawnResult {
+): Promise<BatchSpawnResult> {
   const spawns: BatchSpawnEntry[] = [];
 
   for (const taskId of taskIds) {
     try {
-      const result = spawn(taskId, templateName, cwd, tier);
+      const result = await spawn(taskId, templateName, cwd, tier);
       spawns.push({ taskId, success: true, result });
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : String(err);