@cleocode/core 2026.3.60 → 2026.3.62

package/src/internal.ts

@@ -98,7 +98,7 @@ export type {
   RiskFactor,
   ValidationPrediction,
 } from './intelligence/types.js';
-
+export { type AddIssueParams, type AddIssueResult, addIssue } from './issue/create.js';
 // Issue
 export { collectDiagnostics } from './issue/diagnostics.js';
 // Lib — shared primitives
@@ -240,6 +240,9 @@ export {
 } from './otel/index.js';
 // Paths (additional)
 export { getAgentOutputsAbsolute, getAgentsHome } from './paths.js';
+// Phases — dependency graph (taskId-scoped critical path; distinct from tasks/graph-ops getCriticalPath)
+export type { CriticalPathResult as DepsCriticalPathResult } from './phases/deps.js';
+export { getCriticalPath as depsCriticalPath } from './phases/deps.js';
 export type { ListPhasesResult } from './phases/index.js';
 // Phases
 export { advancePhase, deletePhase, renamePhase, setPhase, startPhase } from './phases/index.js';
@@ -389,7 +392,7 @@ export {
 export { computeChecksum, readJson } from './store/json.js';
 export { createSession, getActiveSession } from './store/session-store.js';
 export { getDb, getNativeDb } from './store/sqlite.js';
-export { createTask } from './store/task-store.js';
+export { createTask, getTask } from './store/task-store.js';
 export {
   auditLog,
   externalTaskLinks,
@@ -415,8 +418,8 @@ export type { ArchiveStatsResult } from './system/archive-stats.js';
 export { getArchiveStats } from './system/archive-stats.js';
 export type { AuditResult } from './system/audit.js';
 export { auditData } from './system/audit.js';
-export type { BackupResult, RestoreResult } from './system/backup.js';
-export { restoreBackup } from './system/backup.js';
+export type { BackupEntry, BackupResult, RestoreResult } from './system/backup.js';
+export { listSystemBackups, restoreBackup } from './system/backup.js';
 export type { CleanupResult } from './system/cleanup.js';
 export { cleanupSystem } from './system/cleanup.js';
 export type { DiagnosticsResult, HealthResult } from './system/health.js';

package/src/phases/deps.ts

@@ -9,15 +9,17 @@
 import type { Task, TaskRef } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
-import type { DataAccessor } from '../store/data-accessor.js';
+import { type DataAccessor, getAccessor } from '../store/data-accessor.js';
 
 /**
  * Load all tasks via targeted query.
+ * Creates a fresh accessor from cwd when none is provided.
  * @task T4659
  * @epic T4654
  */
-async function loadAllTasks(_cwd?: string, accessor?: DataAccessor): Promise<Task[]> {
-  const { tasks } = await accessor!.queryTasks({});
+async function loadAllTasks(cwd?: string, accessor?: DataAccessor): Promise<Task[]> {
+  const acc = accessor ?? (await getAccessor(cwd));
+  const { tasks } = await acc.queryTasks({});
   return tasks;
 }
 

package/src/repair.ts

@@ -105,6 +105,56 @@ export async function repairMissingCompletedAt(
   };
 }
 
+/**
+ * Detect and add missing required columns on the tasks table.
+ * Uses PRAGMA table_info to check actual schema vs required columns.
+ *
+ * @see https://github.com/anthropics/cleo/issues/63
+ */
+export async function repairMissingColumns(
+  cwd: string | undefined,
+  dryRun: boolean,
+): Promise<RepairAction> {
+  const { getDb } = await import('./store/sqlite.js');
+  const db = await getDb(cwd);
+
+  // getDb() already calls ensureRequiredColumns(), so if we get here
+  // the column should exist. But we still report the action for visibility.
+  const { sql } = await import('drizzle-orm');
+  const columns = db.all<{ name: string }>(sql`PRAGMA table_info(tasks)`);
+  const existingCols = new Set(columns.map((c: { name: string }) => c.name));
+
+  const missingCols = ['pipeline_stage'].filter((c) => !existingCols.has(c));
+
+  if (missingCols.length === 0) {
+    return {
+      action: 'fix_missing_columns',
+      status: 'skipped',
+      details: 'All required columns present on tasks table',
+    };
+  }
+
+  if (dryRun) {
+    return {
+      action: 'fix_missing_columns',
+      status: 'preview',
+      details: `Would add missing column(s): ${missingCols.join(', ')}`,
+    };
+  }
+
+  // Columns should already be added by ensureRequiredColumns() in getDb(),
+  // but apply again defensively.
+  for (const col of missingCols) {
+    db.run(sql.raw(`ALTER TABLE tasks ADD COLUMN ${col} text`));
+  }
+
+  return {
+    action: 'fix_missing_columns',
+    status: 'applied',
+    details: `Added missing column(s): ${missingCols.join(', ')}`,
+  };
+}
+
 /**
  * Run all repair functions.
  * Returns all actions taken (or previewed in dry-run mode).
@@ -113,9 +163,10 @@ export async function runAllRepairs(
   cwd: string | undefined,
   dryRun: boolean,
 ): Promise<RepairAction[]> {
-  const [sizes, completedAt] = await Promise.all([
+  const [sizes, completedAt, columns] = await Promise.all([
     repairMissingSizes(cwd, dryRun),
     repairMissingCompletedAt(cwd, dryRun),
+    repairMissingColumns(cwd, dryRun),
   ]);
-  return [sizes, completedAt];
+  return [sizes, completedAt, columns];
 }

package/src/routing/capability-matrix.ts

@@ -469,6 +469,13 @@ const CAPABILITY_MATRIX: OperationCapability[] = [
     mode: 'native',
     preferredChannel: 'either',
   },
+  {
+    domain: 'admin',
+    operation: 'backup',
+    gateway: 'query',
+    mode: 'native',
+    preferredChannel: 'either',
+  },
   {
     domain: 'admin',
     operation: 'backup',

package/src/sequence/index.ts

@@ -168,7 +168,7 @@ export async function showSequence(cwd?: string): Promise<Record<string, unknown
     counter: seq.counter,
     lastId: seq.lastId,
     checksum: seq.checksum,
-    nextId: `T${seq.counter + 1}`,
+    nextId: `T${String(seq.counter + 1).padStart(3, '0')}`,
   };
 }
 

package/src/stats/index.ts

@@ -149,8 +149,10 @@ export async function getProjectStats(
       )
       .get();
     archivedCompleted = archivedDoneRow?.c ?? 0;
-    // totalCompleted = currently done (not yet archived) + archived-as-completed
-    totalCompleted = (statusMap['done'] ?? 0) + archivedCompleted;
+    // totalCompleted: use audit log as SSoT (same source as completedInPeriod) to ensure
+    // the two metrics are consistent. DB-based status counts under-count because they miss
+    // tasks that were completed then cancelled, deleted, or archived with a non-default reason.
+    totalCompleted = entries.filter(isComplete).length;
   } catch {
     // fallback to audit_log counts if DB unavailable
     totalCreated = entries.filter(isCreate).length;

package/src/store/sqlite.ts

@@ -462,18 +462,48 @@ function runMigrations(nativeDb: DatabaseSync, db: NodeSQLiteDatabase<typeof sch
     }
   }
 
+  // Fix #63: Reconcile stale migration journal entries from older CLEO versions.
+  // When the DB has __drizzle_migrations entries whose hashes don't match ANY
+  // local migration file, drizzle's migrate() either throws or tries to re-run
+  // all migrations (causing "table already exists" errors). Fix by clearing stale
+  // entries and marking all local migrations as applied (tables already exist),
+  // then relying on ensureRequiredColumns() to patch any schema gaps.
+  if (tableExists(nativeDb, '__drizzle_migrations') && tableExists(nativeDb, 'tasks')) {
+    const localMigrations = readMigrationFiles({ migrationsFolder });
+    const localHashes = new Set(localMigrations.map((m) => m.hash));
+    const dbEntries = nativeDb.prepare('SELECT hash FROM "__drizzle_migrations"').all() as Array<{
+      hash: string;
+    }>;
+    const hasOrphanedEntries = dbEntries.some((e) => !localHashes.has(e.hash));
+
+    if (hasOrphanedEntries) {
+      const log = getLogger('sqlite');
+      log.warn(
+        { orphaned: dbEntries.filter((e) => !localHashes.has(e.hash)).length },
+        'Detected stale migration journal entries from a previous CLEO version. Reconciling.',
+      );
+      // Clear all entries and mark every local migration as applied.
+      // The existing tables were created by the previous version's migrations,
+      // so we skip re-running them. ensureRequiredColumns() fills any schema gaps.
+      nativeDb.exec('DELETE FROM "__drizzle_migrations"');
+      for (const m of localMigrations) {
+        nativeDb.exec(
+          `INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES ('${m.hash}', ${m.folderMillis})`,
+        );
+      }
+    }
+  }
+
   // Run pending migrations via drizzle-orm/node-sqlite/migrator (synchronous).
   // The new migrator handles its own transactions. T5185: retry on SQLITE_BUSY.
-  let lastError: unknown;
   for (let attempt = 1; attempt <= MAX_MIGRATION_RETRIES; attempt++) {
     try {
       migrate(db, { migrationsFolder });
-      return;
+      break;
     } catch (err) {
       if (!isSqliteBusy(err) || attempt === MAX_MIGRATION_RETRIES) {
         throw err;
       }
-      lastError = err;
       const delay = Math.min(
         MIGRATION_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) * (1 + Math.random() * 0.5),
         MIGRATION_RETRY_MAX_DELAY_MS,
@@ -481,8 +511,45 @@ function runMigrations(nativeDb: DatabaseSync, db: NodeSQLiteDatabase<typeof sch
       Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.round(delay));
     }
   }
-  /* c8 ignore next */
-  throw lastError;
+
+  // Fix #63: Defensive column safety net — add any columns the schema expects
+  // but that are missing from the actual table. This catches gaps from stale
+  // migration journals, partial migrations, or version skew.
+  ensureRequiredColumns(nativeDb);
+}
+
+/**
+ * Required columns that MUST exist on the tasks table.
+ * Maps column name → ALTER TABLE ADD COLUMN DDL suffix.
+ * Only TEXT columns with no constraints are safe for ALTER TABLE ADD in SQLite.
+ *
+ * @see https://github.com/anthropics/cleo/issues/63
+ */
+const REQUIRED_TASK_COLUMNS: Array<{ name: string; ddl: string }> = [
+  { name: 'pipeline_stage', ddl: 'text' },
+];
+
+/**
+ * Ensure all required columns exist on the tasks table.
+ * Uses PRAGMA table_info to inspect the schema and adds any missing columns
+ * via ALTER TABLE ADD COLUMN. This is a safety net for databases where
+ * Drizzle migrations could not run due to journal corruption or version skew.
+ *
+ * @see https://github.com/anthropics/cleo/issues/63
+ */
+function ensureRequiredColumns(nativeDb: DatabaseSync): void {
+  if (!tableExists(nativeDb, 'tasks')) return;
+
+  const columns = nativeDb.prepare('PRAGMA table_info(tasks)').all() as Array<{ name: string }>;
+  const existingCols = new Set(columns.map((c) => c.name));
+
+  for (const req of REQUIRED_TASK_COLUMNS) {
+    if (!existingCols.has(req.name)) {
+      const log = getLogger('sqlite');
+      log.warn({ column: req.name }, `Adding missing column tasks.${req.name} via ALTER TABLE`);
+      nativeDb.exec(`ALTER TABLE tasks ADD COLUMN ${req.name} ${req.ddl}`);
+    }
+  }
 }
 
 /**

package/src/system/backup.ts

@@ -3,7 +3,7 @@
  * @task T4783
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
@@ -80,6 +80,57 @@ export function createBackup(
   return { backupId, path: backupDir, timestamp, type: btype, files: backedUp };
 }
 
+/** A single backup entry returned by listSystemBackups. */
+export interface BackupEntry {
+  backupId: string;
+  type: string;
+  timestamp: string;
+  note?: string;
+  files: string[];
+}
+
+/**
+ * List all available system backups (snapshot, safety, migration types).
+ * Reads `.meta.json` sidecar files written by createBackup.
+ * This is a pure read operation — it does not modify any files.
+ * @task T4783
+ */
+export function listSystemBackups(projectRoot: string): BackupEntry[] {
+  const cleoDir = join(projectRoot, '.cleo');
+  const backupTypes = ['snapshot', 'safety', 'migration'];
+  const entries: BackupEntry[] = [];
+
+  for (const btype of backupTypes) {
+    const backupDir = join(cleoDir, 'backups', btype);
+    if (!existsSync(backupDir)) continue;
+    try {
+      const files = readdirSync(backupDir).filter((f) => f.endsWith('.meta.json'));
+      for (const metaFile of files) {
+        try {
+          const raw = readFileSync(join(backupDir, metaFile), 'utf-8');
+          const meta = JSON.parse(raw) as Partial<BackupEntry>;
+          if (meta.backupId && meta.timestamp) {
+            entries.push({
+              backupId: meta.backupId,
+              type: meta.type ?? btype,
+              timestamp: meta.timestamp,
+              note: meta.note,
+              files: meta.files ?? [],
+            });
+          }
+        } catch {
+          // skip malformed meta files
+        }
+      }
+    } catch {
+      // skip unreadable backup directories
+    }
+  }
+
+  // Sort newest first
+  return entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+
 /** Restore from a backup. */
 export function restoreBackup(
   projectRoot: string,

package/src/tasks/__tests__/add.test.ts

@@ -286,7 +286,9 @@ describe('addTask (integration)', () => {
       accessor,
     );
     expect(result.dryRun).toBe(true);
-    expect(result.task.id).toBe('T001');
+    // Dry run does not allocate a real sequence ID — the task is a preview only
+    expect(result.task.id).toBe('T???');
+    expect(result.task.title).toBe('Dry run task');
   });
 
   it('validates parent hierarchy', async () => {

package/src/tasks/add.ts

@@ -645,6 +645,72 @@ export async function addTask(
     return { task: duplicate, duplicate: true };
   }
 
+  // Dry run: build a preview task without allocating a sequence ID or writing to the DB.
+  // Must be checked before allocateNextTaskId to avoid advancing the counter on no-op runs.
+  if (options.dryRun) {
+    const previewNow = new Date().toISOString();
+
+    // Resolve pipeline stage for the preview without any DB writes
+    let previewParentForStage: import('./pipeline-stage.js').ResolvedParent | null = null;
+    if (parentId) {
+      const previewParentTask = await dataAccessor.loadSingleTask(parentId);
+      previewParentForStage = previewParentTask
+        ? { pipelineStage: previewParentTask.pipelineStage, type: previewParentTask.type }
+        : null;
+    }
+    const previewPipelineStage = resolveDefaultPipelineStage({
+      explicitStage: options.pipelineStage,
+      taskType: taskType ?? null,
+      parentTask: previewParentForStage,
+    });
+    const previewPosition =
+      options.position !== undefined
+        ? options.position
+        : await dataAccessor.getNextPosition(parentId);
+
+    const previewTask: Task = {
+      id: 'T???',
+      title: options.title,
+      description: options.description,
+      status,
+      priority,
+      type: taskType,
+      parentId: parentId || null,
+      position: previewPosition,
+      positionVersion: 0,
+      size,
+      pipelineStage: previewPipelineStage,
+      createdAt: previewNow,
+      updatedAt: previewNow,
+    };
+    if (phase) previewTask.phase = phase;
+    if (options.labels?.length) previewTask.labels = options.labels.map((l) => l.trim());
+    if (options.files?.length) previewTask.files = options.files.map((f) => f.trim());
+    if (options.acceptance?.length)
+      previewTask.acceptance = options.acceptance.map((a) => a.trim());
+    if (options.depends?.length) previewTask.depends = options.depends.map((d) => d.trim());
+    if (options.notes) {
+      const previewNote = `${new Date()
+        .toISOString()
+        .replace('T', ' ')
+        .replace(/\.\d+Z$/, ' UTC')}: ${options.notes}`;
+      previewTask.notes = [previewNote];
+    }
+    if (status === 'blocked' && options.description) {
+      previewTask.blockedBy = options.description;
+    }
+    if (status === 'done') {
+      previewTask.completedAt = previewNow;
+    }
+    if (taskType !== 'epic') {
+      const verificationEnabledRaw = await getRawConfigValue('verification.enabled', cwd);
+      if (verificationEnabledRaw === true) {
+        previewTask.verification = buildDefaultVerification(previewNow);
+      }
+    }
+    return { task: previewTask, dryRun: true };
+  }
+
   const taskId = await allocateNextTaskId(cwd);
 
   const now = new Date().toISOString();
@@ -741,11 +807,6 @@ export async function addTask(
     }
   }
 
-  // Dry run
-  if (options.dryRun) {
-    return { task, dryRun: true };
-  }
-
   // Wrap all writes in a transaction for TOCTOU safety (T023)
   await dataAccessor.transaction(async (tx: TransactionAccessor) => {
     // Position shuffling via bulk SQL update (T025)