@cleocode/core 2026.4.98 → 2026.4.100

package/src/sentient/propose-tick.ts

@@ -0,0 +1,415 @@
+/**
+ * Sentient Loop Propose Tick — Single-pass Tier-2 proposal generator.
+ *
+ * Runs inside the daemon cron (every 2 hours) or standalone via
+ * `cleo sentient propose run`. Orchestrates the three ingesters,
+ * deduplicates candidates by fingerprint, applies the DB-enforced
+ * rate limit, and writes accepted candidates as tasks with
+ * `status='proposed'` and labels including `'sentient-tier2'`.
+ *
+ * Scoped IN:
+ *   - Ingest from brain.db, nexus.db, and .cleo/audit/gates.jsonl
+ *   - Transactional rate-limit check (BEGIN IMMEDIATE + COUNT + INSERT)
+ *   - Kill-switch re-check at each checkpoint (Round 2 audit §9)
+ *   - tier2Enabled guard (default false — owner opt-in)
+ *
+ * Scoped OUT:
+ *   - LLM calls (NONE — all proposal titles are structured templates)
+ *   - Tier-3 sandbox/merge (blocked on T992+T993+T995)
+ *
+ * Title format enforcement:
+ *   All proposal titles MUST match `/^\[T2-(BRAIN|NEXUS|TEST)\]/`.
+ *   This is the prompt-injection defence from T1008 §3.6 — no freeform
+ *   LLM text can enter the task title column from the Tier-2 proposer.
+ *
+ * @task T1008
+ * @see ADR-054 — Sentient Loop Tier-2
+ */
+
+import type { ProposalCandidate } from '@cleocode/contracts';
+import { runBrainIngester } from './ingesters/brain-ingester.js';
+import { runNexusIngester } from './ingesters/nexus-ingester.js';
+import { runTestIngester } from './ingesters/test-ingester.js';
+import {
+  countTodayProposals,
+  DEFAULT_DAILY_PROPOSAL_LIMIT,
+  transactionalInsertProposal,
+} from './proposal-rate-limiter.js';
+import { patchSentientState, readSentientState } from './state.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex that ALL proposal titles MUST match.
+ * Enforces structured-template-only output (no freeform LLM text).
+ */
+export const PROPOSAL_TITLE_PATTERN = /^\[T2-(BRAIN|NEXUS|TEST)\]/;
+
+/**
+ * Label applied to every Tier-2 proposal task.
+ * Used by the rate limiter to identify proposals.
+ */
+export const TIER2_LABEL = 'sentient-tier2';
+
+// ---------------------------------------------------------------------------
+// Outcome types
+// ---------------------------------------------------------------------------
+
+/** Discriminant for the propose-tick outcome. */
+export type ProposalTickOutcomeKind =
+  | 'killed' // killSwitch active
+  | 'disabled' // tier2Enabled = false
+  | 'rate-limited' // daily cap already reached
+  | 'no-candidates' // all ingesters returned empty
+  | 'wrote' // at least one proposal was written
+  | 'error'; // unexpected error
+
+/** Structured outcome of a single propose-tick pass. */
+export interface ProposeTickOutcome {
+  /** Discriminant describing how the tick ended. */
+  kind: ProposalTickOutcomeKind;
+  /** Number of proposals written in this pass. */
+  written: number;
+  /** Current daily proposal count at the end of the pass. */
+  count: number;
+  /** Human-readable detail (one line). */
+  detail: string;
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options for {@link runProposeTick}. */
+export interface ProposeTickOptions {
+  /** Absolute path to the project root (contains `.cleo/`). */
+  projectRoot: string;
+  /** Absolute path to sentient-state.json. */
+  statePath: string;
+  /**
+   * Override for the brain DB handle. Injected by tests to avoid
+   * opening a real brain.db. When omitted the real getBrainNativeDb() is used.
+   */
+  brainDb?: import('node:sqlite').DatabaseSync | null;
+  /**
+   * Override for the nexus DB handle. Injected by tests.
+   * When omitted the real getNexusNativeDb() is used.
+   */
+  nexusDb?: import('node:sqlite').DatabaseSync | null;
+  /**
+   * Override for the tasks DB handle (used by rate limiter + INSERT).
+   * Injected by tests. When omitted the real getNativeTasksDb() is used.
+   */
+  tasksDb?: import('node:sqlite').DatabaseSync | null;
+  /**
+   * Override the task ID allocator. Injected by tests.
+   * When omitted the real allocateNextTaskId() is used.
+   */
+  allocateTaskId?: () => Promise<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a deduplication fingerprint for a candidate.
+ * Two candidates with the same source + sourceId are considered identical.
+ */
+function fingerprint(candidate: ProposalCandidate): string {
+  return `${candidate.source}:${candidate.sourceId}`;
+}
+
+/**
+ * Check whether the kill switch is currently active.
+ */
+async function killSwitchActive(statePath: string): Promise<boolean> {
+  const state = await readSentientState(statePath);
+  return state.killSwitch === true;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a single Tier-2 propose pass.
+ *
+ * Steps:
+ *   1. Check killSwitch → abort if true
+ *   2. Check tier2Enabled → abort if false
+ *   3. Run all three ingesters in parallel
+ *   4. Check killSwitch again (post-ingest checkpoint)
+ *   5. Merge + deduplicate candidates by fingerprint
+ *   6. Validate title format (must match PROPOSAL_TITLE_PATTERN)
+ *   7. Score + take top-N candidates (N = limit - countTodayProposals)
+ *   8. Check killSwitch again (pre-write checkpoint)
+ *   9. For each candidate: transactional INSERT into tasks.db
+ *  10. Update tier2Stats in state
+ *
+ * @param options - Propose tick options (see {@link ProposeTickOptions})
+ * @returns Structured outcome describing how the pass ended.
+ */
+export async function runProposeTick(options: ProposeTickOptions): Promise<ProposeTickOutcome> {
+  const { projectRoot, statePath } = options;
+
+  // Checkpoint 1: killSwitch before any work
+  if (await killSwitchActive(statePath)) {
+    return { kind: 'killed', written: 0, count: 0, detail: 'killSwitch active before ingest' };
+  }
+
+  // Check tier2Enabled guard
+  const state = await readSentientState(statePath);
+  if (!state.tier2Enabled) {
+    return {
+      kind: 'disabled',
+      written: 0,
+      count: 0,
+      detail: 'tier2Enabled=false; enable via cleo sentient propose enable',
+    };
+  }
+
+  // Resolve DB handles
+  let brainDb: import('node:sqlite').DatabaseSync | null;
+  let nexusDb: import('node:sqlite').DatabaseSync | null;
+  let tasksNativeDb: import('node:sqlite').DatabaseSync | null;
+
+  if (options.brainDb !== undefined) {
+    brainDb = options.brainDb;
+  } else {
+    // Ensure brain.db is initialized before calling getBrainNativeDb
+    try {
+      const { getBrainDb, getBrainNativeDb } = await import('@cleocode/core/internal');
+      await getBrainDb(projectRoot);
+      brainDb = getBrainNativeDb();
+    } catch {
+      brainDb = null;
+    }
+  }
+
+  if (options.nexusDb !== undefined) {
+    nexusDb = options.nexusDb;
+  } else {
+    try {
+      const { getNexusNativeDb } = await import('@cleocode/core/internal');
+      nexusDb = getNexusNativeDb();
+    } catch {
+      nexusDb = null;
+    }
+  }
+
+  if (options.tasksDb !== undefined) {
+    tasksNativeDb = options.tasksDb;
+  } else {
+    const { getNativeDb, getDb } = await import('@cleocode/core/internal');
+    // Ensure tasks.db is initialized
+    await getDb(projectRoot);
+    tasksNativeDb = getNativeDb();
+  }
+
+  // Run all three ingesters in parallel
+  const [brainCandidates, nexusCandidates, testCandidates] = await Promise.all([
+    Promise.resolve(runBrainIngester(brainDb)),
+    Promise.resolve(runNexusIngester(nexusDb)),
+    Promise.resolve(runTestIngester(projectRoot)),
+  ]);
+
+  // Checkpoint 2: killSwitch after ingest
+  if (await killSwitchActive(statePath)) {
+    return {
+      kind: 'killed',
+      written: 0,
+      count: 0,
+      detail: 'killSwitch active after ingest phase',
+    };
+  }
+
+  // Merge + deduplicate by fingerprint
+  const seenFingerprints = new Set<string>();
+  const merged: ProposalCandidate[] = [];
+
+  for (const candidate of [...brainCandidates, ...nexusCandidates, ...testCandidates]) {
+    // Validate title format — reject candidates with non-template titles
+    if (!PROPOSAL_TITLE_PATTERN.test(candidate.title)) {
+      process.stderr.write(
+        `[sentient/propose-tick] Rejected candidate with invalid title format: "${candidate.title}"\n`,
+      );
+      continue;
+    }
+
+    const fp = fingerprint(candidate);
+    if (seenFingerprints.has(fp)) continue;
+    seenFingerprints.add(fp);
+    merged.push(candidate);
+  }
+
+  if (merged.length === 0) {
+    return { kind: 'no-candidates', written: 0, count: 0, detail: 'no candidates from ingesters' };
+  }
+
+  // Sort by weight descending
+  merged.sort((a, b) => b.weight - a.weight);
+
+  // Determine how many slots remain today
+  const currentCount = tasksNativeDb ? countTodayProposals(tasksNativeDb) : 0;
+  const slotsRemaining = Math.max(0, DEFAULT_DAILY_PROPOSAL_LIMIT - currentCount);
+
+  if (slotsRemaining === 0) {
+    return {
+      kind: 'rate-limited',
+      written: 0,
+      count: currentCount,
+      detail: `daily limit reached (${currentCount}/${DEFAULT_DAILY_PROPOSAL_LIMIT})`,
+    };
+  }
+
+  // Take top-N candidates
+  const toWrite = merged.slice(0, slotsRemaining);
+
+  // Checkpoint 3: killSwitch before DB writes
+  if (await killSwitchActive(statePath)) {
+    return {
+      kind: 'killed',
+      written: 0,
+      count: currentCount,
+      detail: 'killSwitch active before write phase',
+    };
+  }
+
+  // Write proposals
+  let written = 0;
+
+  for (const candidate of toWrite) {
+    // Allocate task ID
+    let taskId: string;
+    if (options.allocateTaskId) {
+      taskId = await options.allocateTaskId();
+    } else {
+      const { allocateNextTaskId } = await import('@cleocode/core/internal');
+      taskId = await allocateNextTaskId(projectRoot);
+    }
+
+    const now = new Date().toISOString();
+    const labels = JSON.stringify([TIER2_LABEL, `source:${candidate.source}`]);
+
+    if (!tasksNativeDb) {
+      process.stderr.write('[sentient/propose-tick] tasks DB not available; skipping write\n');
+      break;
+    }
+
+    // Use the SQL INSERT path (with metadata_json-equivalent stored in notes_json
+    // as a structured first element) and labels to mark the proposal.
+    // The rate limiter identifies proposals by: labels_json LIKE '%sentient-tier2%'
+    // This avoids needing a new column on the tasks table.
+    const notesJson = JSON.stringify([
+      JSON.stringify({
+        kind: 'proposal-meta',
+        proposedBy: 'sentient-tier2',
+        source: candidate.source,
+        sourceId: candidate.sourceId,
+        weight: candidate.weight,
+        proposedAt: now,
+      }),
+    ]);
+
+    const insertSql = `
+      INSERT INTO tasks (
+        id, title, description, status, priority,
+        labels_json, notes_json,
+        created_at, updated_at,
+        role, scope
+      ) VALUES (
+        :id, :title, :description, :status, :priority,
+        :labelsJson, :notesJson,
+        :createdAt, :updatedAt,
+        :role, :scope
+      )
+    `;
+
+    const insertParams = {
+      id: taskId,
+      title: candidate.title,
+      description: candidate.rationale,
+      status: 'proposed',
+      priority: 'medium',
+      labelsJson: labels,
+      notesJson,
+      createdAt: now,
+      updatedAt: now,
+      role: 'work',
+      scope: 'feature',
+    };
+
+    try {
+      const result = transactionalInsertProposal(
+        tasksNativeDb,
+        insertSql,
+        insertParams,
+        DEFAULT_DAILY_PROPOSAL_LIMIT,
+      );
+
+      if (result.inserted) {
+        written++;
+      } else if (result.reason === 'rate-limit') {
+        // Rate limit hit mid-loop — stop writing.
+        break;
+      }
+      // If 'busy', skip this one and continue.
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[sentient/propose-tick] INSERT failed for ${taskId}: ${message}\n`);
+    }
+  }
+
+  // Update tier2Stats
+  if (written > 0) {
+    const latestState = await readSentientState(statePath);
+    await patchSentientState(statePath, {
+      tier2Stats: {
+        ...latestState.tier2Stats,
+        proposalsGenerated: latestState.tier2Stats.proposalsGenerated + written,
+      },
+    });
+  }
+
+  const finalCount = tasksNativeDb ? countTodayProposals(tasksNativeDb) : currentCount + written;
+
+  if (written === 0) {
+    return {
+      kind: 'no-candidates',
+      written: 0,
+      count: finalCount,
+      detail: 'candidates available but none written (rate limit or DB unavailable)',
+    };
+  }
+
+  return {
+    kind: 'wrote',
+    written,
+    count: finalCount,
+    detail: `wrote ${written} proposal(s) (${finalCount}/${DEFAULT_DAILY_PROPOSAL_LIMIT} today)`,
+  };
+}
+
+/**
+ * Safe wrapper for {@link runProposeTick} — swallows unexpected exceptions.
+ * Used by the daemon cron handler.
+ *
+ * @param options - Propose tick options
+ * @returns The propose tick outcome, or an error outcome if the tick threw.
+ */
+export async function safeRunProposeTick(options: ProposeTickOptions): Promise<ProposeTickOutcome> {
+  try {
+    return await runProposeTick(options);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      kind: 'error',
+      written: 0,
+      count: 0,
+      detail: `propose tick threw: ${message}`,
+    };
+  }
+}

package/src/sentient/state.ts

@@ -0,0 +1,229 @@
+/**
+ * Sentient Loop State — Persistent state for the Tier-1 autonomous daemon.
+ *
+ * Stored in `.cleo/sentient-state.json` (plain JSON, not SQLite) to avoid
+ * SQLite WAL conflicts between the long-running daemon process and the
+ * main CLEO CLI process. Human-readable for debugging.
+ *
+ * The file is gitignored (see .gitignore §.cleo/ section) and survives
+ * restarts. Only `killSwitch`, `pid`, and `stats` fields are load-bearing
+ * across process boundaries.
+ *
+ * @see ADR-054 — Sentient Loop Tier-1 (autonomous task execution)
+ * @task T946
+ */
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type { Tier2Stats } from '@cleocode/contracts';
+
+/** Schema version for sentient-state.json. Bump on breaking field changes. */
+export const SENTIENT_STATE_SCHEMA_VERSION = '1.0' as const;
+
+/**
+ * Per-task failure/backoff tracking for stuck detection.
+ * Keyed by task id in {@link SentientState.stuckTasks}.
+ */
+export interface StuckTaskRecord {
+  /** Number of consecutive failed spawn attempts for this task. */
+  attempts: number;
+  /** ISO-8601 timestamp of the most recent failure. */
+  lastFailureAt: string;
+  /** Unix epoch ms when the next retry becomes eligible. */
+  nextRetryAt: number;
+  /** Last captured failure reason (truncated to 500 chars). */
+  lastReason: string;
+}
+
+/**
+ * Rolling counters persisted across daemon restarts.
+ */
+export interface SentientStats {
+  /** Total tasks picked by the loop since creation. */
+  tasksPicked: number;
+  /** Total tasks that completed successfully. */
+  tasksCompleted: number;
+  /** Total tasks whose spawn exited non-zero. */
+  tasksFailed: number;
+  /** Total ticks executed (including no-op ticks). */
+  ticksExecuted: number;
+  /** Total ticks aborted early because kill switch was active. */
+  ticksKilled: number;
+}
+
+/**
+ * Persistent sentient daemon state.
+ *
+ * Design principles:
+ * - `killSwitch` is the single load-bearing kill signal — the daemon re-checks
+ *   it between every step of a tick, not just at tick start (Round 2 audit).
+ * - `stuckTasks` keys are task ids; values encode backoff + failure counts.
+ * - `stuckTimestamps` is a rolling 1-hour window used for the self-pause rule
+ *   (5 stucks in 1 hour → killSwitch=true).
+ * - `stats` fields are monotonic counters that only ever increase.
+ */
+export interface SentientState {
+  /** JSON schema version for forward-compatibility checks. */
+  schemaVersion: typeof SENTIENT_STATE_SCHEMA_VERSION;
+  /** PID of the currently running daemon process. null = daemon not running. */
+  pid: number | null;
+  /** ISO-8601 timestamp when the daemon was last started. */
+  startedAt: string | null;
+  /** ISO-8601 timestamp of the last completed tick (any outcome). */
+  lastTickAt: string | null;
+  /**
+   * Kill-switch flag. When true, the daemon re-checks at every step of a tick
+   * and exits cleanly without picking or spawning a task.
+   */
+  killSwitch: boolean;
+  /** Reason supplied when killSwitch was last set (diagnostic only). */
+  killSwitchReason: string | null;
+  /** Rolling counters; see {@link SentientStats}. */
+  stats: SentientStats;
+  /** Per-task backoff + failure metadata for retry/stuck detection. */
+  stuckTasks: Record<string, StuckTaskRecord>;
+  /**
+   * Unix-epoch-ms timestamps of `stuck` events within the last hour.
+   * When length ≥ 5 the daemon self-pauses (killSwitch=true).
+   */
+  stuckTimestamps: number[];
+  /**
+   * Currently-active task id (set while a spawn is in-flight, cleared afterward).
+   * Enables `status` to show the in-progress task during a long-running tick.
+   */
+  activeTaskId: string | null;
+  /**
+   * Tier-2 proposal queue enabled flag.
+   *
+   * Default: `false` — Tier 2 is OFF by default to prevent surprise proposal
+   * floods on first daemon start. Owner enables via `cleo sentient propose enable`
+   * (patches this flag). See ADR-054 §Tier-2.
+   *
+   * @task T1008
+   */
+  tier2Enabled: boolean;
+  /**
+   * Rolling counters for Tier-2 proposal activity.
+   *
+   * @task T1008
+   */
+  tier2Stats: Tier2Stats;
+}
+
+/** Default (empty) sentient state for fresh initialisation. */
+export const DEFAULT_SENTIENT_STATE: SentientState = {
+  schemaVersion: SENTIENT_STATE_SCHEMA_VERSION,
+  pid: null,
+  startedAt: null,
+  lastTickAt: null,
+  killSwitch: false,
+  killSwitchReason: null,
+  stats: {
+    tasksPicked: 0,
+    tasksCompleted: 0,
+    tasksFailed: 0,
+    ticksExecuted: 0,
+    ticksKilled: 0,
+  },
+  stuckTasks: {},
+  stuckTimestamps: [],
+  activeTaskId: null,
+  tier2Enabled: false,
+  tier2Stats: {
+    proposalsGenerated: 0,
+    proposalsAccepted: 0,
+    proposalsRejected: 0,
+  },
+};
+
+/**
+ * Read the sentient state from disk.
+ *
+ * Returns the default state if the file does not exist or is malformed.
+ * Never throws — absence is not an error.
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ */
+export async function readSentientState(statePath: string): Promise<SentientState> {
+  try {
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<SentientState>;
+    return {
+      ...DEFAULT_SENTIENT_STATE,
+      ...parsed,
+      stats: { ...DEFAULT_SENTIENT_STATE.stats, ...(parsed.stats ?? {}) },
+      stuckTasks: parsed.stuckTasks ?? {},
+      stuckTimestamps: parsed.stuckTimestamps ?? [],
+      tier2Enabled: parsed.tier2Enabled ?? false,
+      tier2Stats: { ...DEFAULT_SENTIENT_STATE.tier2Stats, ...(parsed.tier2Stats ?? {}) },
+    };
+  } catch {
+    return { ...DEFAULT_SENTIENT_STATE };
+  }
+}
+
+/**
+ * Write the sentient state to disk atomically via tmp-then-rename.
+ *
+ * Atomic write prevents partial reads if the daemon crashes mid-write.
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ * @param state - State to persist
+ */
+export async function writeSentientState(statePath: string, state: SentientState): Promise<void> {
+  const dir = dirname(statePath);
+  await mkdir(dir, { recursive: true });
+
+  const tmpPath = join(dir, `.sentient-state-${process.pid}.tmp`);
+  const json = JSON.stringify(state, null, 2);
+
+  await writeFile(tmpPath, json, 'utf-8');
+  await rename(tmpPath, statePath);
+}
+
+/**
+ * Patch a subset of fields in the sentient state file.
+ *
+ * Reads current state, merges patch, writes back. Nested `stats` merges
+ * with existing stats (never clobbered wholesale).
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ * @param patch - Partial state to merge over the existing state
+ * @returns The merged state that was written to disk.
+ */
+export async function patchSentientState(
+  statePath: string,
+  patch: Partial<SentientState>,
+): Promise<SentientState> {
+  const current = await readSentientState(statePath);
+  const updated: SentientState = {
+    ...current,
+    ...patch,
+    stats: { ...current.stats, ...(patch.stats ?? {}) },
+  };
+  await writeSentientState(statePath, updated);
+  return updated;
+}
+
+/**
+ * Increment stats counters atomically.
+ *
+ * @param statePath - Absolute path to sentient-state.json
+ * @param delta - Partial stats to add to current counters
+ */
+export async function incrementStats(
+  statePath: string,
+  delta: Partial<SentientStats>,
+): Promise<SentientState> {
+  const current = await readSentientState(statePath);
+  const nextStats: SentientStats = {
+    tasksPicked: current.stats.tasksPicked + (delta.tasksPicked ?? 0),
+    tasksCompleted: current.stats.tasksCompleted + (delta.tasksCompleted ?? 0),
+    tasksFailed: current.stats.tasksFailed + (delta.tasksFailed ?? 0),
+    ticksExecuted: current.stats.ticksExecuted + (delta.ticksExecuted ?? 0),
+    ticksKilled: current.stats.ticksKilled + (delta.ticksKilled ?? 0),
+  };
+  const updated: SentientState = { ...current, stats: nextStats };
+  await writeSentientState(statePath, updated);
+  return updated;
+}