@masslessai/push-todo 4.0.2 → 4.0.3

package/lib/cli.js

@@ -101,6 +101,17 @@ ${bold('CONFIRM (for daemon skills):')}
   --metadata <json>                Optional JSON metadata for rich rendering
   --task <number>                  Display number (auto-detected in daemon)
 
+${bold('CRON (scheduled jobs):')}
+  push-todo cron add               Add a cron job
+    --name <name>                  Job name (required)
+    --every <interval>             Repeat interval: 30m, 1h, 24h, 7d
+    --at <iso-date>                One-shot at specific time
+    --cron <expression>            5-field cron expression
+    --notify <message>             Send Mac notification
+    --create-todo <content>        Create todo reminder
+  push-todo cron list              List all cron jobs
+  push-todo cron remove <id>       Remove a cron job by ID
+
 ${bold('SETTINGS:')}
   push-todo setting                Show all settings
   push-todo setting auto-commit    Toggle auto-commit
@@ -150,6 +161,14 @@ const options = {
   'content': { type: 'string' },
   'metadata': { type: 'string' },
   'task': { type: 'string' },
+  // Cron command options
+  'name': { type: 'string' },
+  'every': { type: 'string' },
+  'at': { type: 'string' },
+  'cron': { type: 'string' },
+  'create-todo': { type: 'string' },
+  'notify': { type: 'string' },
+  'queue-execution': { type: 'string' },
 };
 
 /**
@@ -486,6 +505,97 @@ export async function run(argv) {
     return requestConfirmation(values, positionals);
   }
 
+  // Cron command - scheduled jobs
+  if (command === 'cron') {
+    const { addJob, removeJob, listJobs } = await import('./cron.js');
+    const subCommand = positionals[1];
+
+    if (subCommand === 'add') {
+      if (!values.name) {
+        console.error(red('--name is required for cron add'));
+        process.exit(1);
+      }
+
+      // Determine schedule
+      let schedule;
+      if (values.every) {
+        schedule = { type: 'every', value: values.every };
+      } else if (values.at) {
+        schedule = { type: 'at', value: values.at };
+      } else if (values.cron) {
+        schedule = { type: 'cron', value: values.cron };
+      } else {
+        console.error(red('Schedule required: --every, --at, or --cron'));
+        process.exit(1);
+      }
+
+      // Determine action
+      let action;
+      if (values['create-todo']) {
+        action = { type: 'create-todo', content: values['create-todo'] };
+      } else if (values.notify) {
+        action = { type: 'notify', content: values.notify };
+      } else if (values['queue-execution']) {
+        action = { type: 'queue-execution', todoId: values['queue-execution'] };
+      } else {
+        console.error(red('Action required: --create-todo, --notify, or --queue-execution'));
+        process.exit(1);
+      }
+
+      try {
+        const job = addJob({ name: values.name, schedule, action });
+        console.log(green(`Created cron job: ${job.name} (ID: ${job.id.slice(0, 8)})`));
+        console.log(dim(`Next run: ${job.nextRunAt}`));
+      } catch (error) {
+        console.error(red(`Failed to create cron job: ${error.message}`));
+        process.exit(1);
+      }
+      return;
+    }
+
+    if (subCommand === 'list') {
+      const jobs = listJobs();
+      if (jobs.length === 0) {
+        console.log('No cron jobs configured.');
+        console.log(dim('Add one with: push-todo cron add --name "..." --every "24h" --notify "..."'));
+        return;
+      }
+      console.log(bold('Cron Jobs:'));
+      for (const job of jobs) {
+        const status = job.enabled ? green('ON') : dim('OFF');
+        const schedStr = job.schedule.type === 'every' ? `every ${job.schedule.value}` :
+                         job.schedule.type === 'at' ? `at ${job.schedule.value}` :
+                         `cron: ${job.schedule.value}`;
+        console.log(`  ${status} ${job.name} [${schedStr}] → ${job.action.type}: ${job.action.content || job.action.todoId || ''}`);
+        console.log(dim(`     ID: ${job.id.slice(0, 8)} | Next: ${job.nextRunAt || 'N/A'} | Last: ${job.lastRunAt || 'never'}`));
+      }
+      return;
+    }
+
+    if (subCommand === 'remove') {
+      const jobId = positionals[2];
+      if (!jobId) {
+        console.error(red('Usage: push-todo cron remove <id>'));
+        process.exit(1);
+      }
+      if (removeJob(jobId)) {
+        console.log(green(`Removed cron job ${jobId}`));
+      } else {
+        console.error(red(`Cron job not found: ${jobId}`));
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Default: show help for cron
+    console.log(`${bold('Cron Commands:')}
+  push-todo cron add     Add a new scheduled job
+  push-todo cron list    List all jobs
+  push-todo cron remove  Remove a job by ID
+    `);
+    return;
+  }
+
   // Connect command
   if (command === 'connect') {
     return runConnect(values);

package/lib/context-engine.js

@@ -0,0 +1,290 @@
+/**
+ * Context Engine + Prompt Engine for Push daemon.
+ *
+ * Scans project skills, collects git/GitHub state, builds context-rich prompts.
+ * All functions are non-fatal — errors result in empty/partial context.
+ *
+ * Architecture: docs/20260214_push_daemon_evolution_complete_architecture.md §23
+ * Pattern: Follow self-update.js — pure functions, execFileSync, no npm deps.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+
+// ==================== Cache ====================
+
+const contextCache = new Map(); // projectPath -> { data, timestamp }
+const CACHE_TTL = 3600000; // 1 hour
+
+/**
+ * Invalidate cache for a specific project path.
+ * Called before task execution to ensure fresh context.
+ */
+export function invalidateCache(projectPath) {
+  contextCache.delete(projectPath);
+}
+
+// ==================== YAML Frontmatter Parser ====================
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ * Minimal parser: extracts key: value pairs between --- markers.
+ * No npm yaml dependency — skills use simple single-line key: value format.
+ *
+ * @param {string} content - Full file content
+ * @returns {{ frontmatter: Object, body: string }}
+ */
+export function parseFrontmatter(content) {
+  const lines = content.split('\n');
+
+  // Must start with ---
+  if (lines[0].trim() !== '---') {
+    return { frontmatter: {}, body: content };
+  }
+
+  // Find closing ---
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      closingIndex = i;
+      break;
+    }
+  }
+
+  if (closingIndex === -1) {
+    return { frontmatter: {}, body: content };
+  }
+
+  // Parse key: value pairs
+  const frontmatter = {};
+  for (let i = 1; i < closingIndex; i++) {
+    const line = lines[i];
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key) {
+      frontmatter[key] = value;
+    }
+  }
+
+  const body = lines.slice(closingIndex + 1).join('\n');
+  return { frontmatter, body };
+}
+
+// ==================== Skill Scanning ====================
+
+/**
+ * Scan .claude/skills/x/SKILL.md files in a project directory.
+ *
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Array<{ name: string, description: string, requiresConfirmation: boolean }>}
+ */
+export function scanProjectSkills(projectPath) {
+  const skillsDir = join(projectPath, '.claude', 'skills');
+
+  if (!existsSync(skillsDir)) {
+    return [];
+  }
+
+  try {
+    const entries = readdirSync(skillsDir);
+    const skills = [];
+
+    for (const entry of entries) {
+      const entryPath = join(skillsDir, entry);
+
+      // Skip non-directories
+      try {
+        if (!statSync(entryPath).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+
+      const skillFile = join(entryPath, 'SKILL.md');
+      if (!existsSync(skillFile)) continue;
+
+      try {
+        const content = readFileSync(skillFile, 'utf8');
+        const { frontmatter, body } = parseFrontmatter(content);
+
+        skills.push({
+          name: frontmatter.name || entry,
+          description: frontmatter.description || '',
+          requiresConfirmation: body.includes('push-todo confirm'),
+        });
+      } catch {
+        // Skip unreadable skill files
+      }
+    }
+
+    return skills;
+  } catch {
+    return [];
+  }
+}
+
+// ==================== Project State ====================
+
+/**
+ * Collect git + GitHub state for a project.
+ * All calls are non-fatal — returns partial data on failure.
+ *
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {{ recentCommits: string[], openPRs: Array|null, currentBranch: string|null }}
+ */
+export function collectProjectState(projectPath) {
+  const result = {
+    recentCommits: [],
+    openPRs: null,
+    currentBranch: null,
+  };
+
+  // Current branch
+  try {
+    result.currentBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectPath,
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+  } catch { /* non-fatal */ }
+
+  // Recent commits
+  try {
+    const output = execFileSync('git', ['log', '--oneline', '-5'], {
+      cwd: projectPath,
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+
+    if (output) {
+      result.recentCommits = output.split('\n');
+    }
+  } catch { /* non-fatal */ }
+
+  // Open PRs (only if gh CLI is available)
+  try {
+    execFileSync('which', ['gh'], {
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const prOutput = execFileSync('gh', ['pr', 'list', '--json', 'number,title,updatedAt', '--limit', '5'], {
+      cwd: projectPath,
+      timeout: 10000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+
+    if (prOutput) {
+      result.openPRs = JSON.parse(prOutput);
+    }
+  } catch { /* non-fatal — gh not installed or not authenticated */ }
+
+  return result;
+}
+
+// ==================== Cached Context ====================
+
+/**
+ * Get project context (skills + state), with hourly cache.
+ * Call invalidateCache(projectPath) before task execution for fresh data.
+ *
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {{ skills: Array, state: Object }}
+ */
+export function getProjectContext(projectPath) {
+  const cached = contextCache.get(projectPath);
+
+  if (cached && (Date.now() - cached.timestamp) < CACHE_TTL) {
+    return cached.data;
+  }
+
+  const skills = scanProjectSkills(projectPath);
+  const state = collectProjectState(projectPath);
+  const data = { skills, state };
+
+  contextCache.set(projectPath, { data, timestamp: Date.now() });
+
+  return data;
+}
+
+// ==================== Prompt Engine ====================
+
+/**
+ * Build a context-rich prompt for Claude Code sessions.
+ * Each section is only included when data exists.
+ *
+ * @param {Object} task
+ * @param {number} task.displayNumber
+ * @param {string} task.content - Normalized content or summary
+ * @param {string} task.attachmentContext - Pre-built attachment string (links, screenshots)
+ * @param {string|null} task.actionName - Action display name from registry
+ * @param {string|null} task.contextApp - Source app (X, Safari, etc.)
+ * @param {Object} context - From getProjectContext()
+ * @param {Array} context.skills
+ * @param {Object} context.state
+ * @returns {string} Complete prompt
+ */
+export function buildSmartPrompt(task, context) {
+  const sections = [];
+
+  // 1. Task section (always present)
+  sections.push(`## Task\nWork on Push task #${task.displayNumber}:\n\n${task.content}`);
+
+  // 2. Metadata section (conditional)
+  const metaParts = [];
+  if (task.actionName) metaParts.push(`Action: ${task.actionName}`);
+  if (task.contextApp) metaParts.push(`Context app: ${task.contextApp}`);
+  if (metaParts.length > 0) {
+    sections.push(`## Metadata\n${metaParts.join('\n')}`);
+  }
+
+  // 3. Attachment section (conditional — pre-built by caller)
+  if (task.attachmentContext) {
+    sections.push(`## Attachments${task.attachmentContext}`);
+  }
+
+  // 4. Skill section (conditional)
+  if (context.skills && context.skills.length > 0) {
+    const skillLines = context.skills.map(s => {
+      const flag = s.requiresConfirmation ? ' [requires push-todo confirm]' : '';
+      return `- /${s.name}: ${s.description || 'No description'}${flag}`;
+    });
+
+    const confirmSkills = context.skills.filter(s => s.requiresConfirmation);
+    let confirmNote = '';
+    if (confirmSkills.length > 0) {
+      confirmNote = '\n\nSkills marked [requires push-todo confirm] include a user approval step before performing irreversible actions. If your task matches one of these skills, you MUST invoke it to ensure the proper confirmation workflow.';
+    }
+
+    sections.push(`## Available Skills\nThe following skills are available in this project:\n${skillLines.join('\n')}${confirmNote}`);
+  }
+
+  // 5. Project state section (conditional)
+  const stateParts = [];
+  if (context.state?.currentBranch) {
+    stateParts.push(`Current branch: ${context.state.currentBranch}`);
+  }
+  if (context.state?.recentCommits?.length > 0) {
+    stateParts.push(`Recent commits:\n${context.state.recentCommits.map(c => `  ${c}`).join('\n')}`);
+  }
+  if (context.state?.openPRs?.length > 0) {
+    stateParts.push(`Open PRs:\n${context.state.openPRs.map(pr => `  #${pr.number} ${pr.title}`).join('\n')}`);
+  }
+  if (stateParts.length > 0) {
+    sections.push(`## Project State\n${stateParts.join('\n')}`);
+  }
+
+  // 6. Instructions section (always present)
+  sections.push(`## Instructions
+1. If you need to understand the codebase, start by reading the CLAUDE.md file if it exists.
+2. ALWAYS commit your changes before finishing. Use a descriptive commit message summarizing what you did. This is critical — uncommitted changes will be lost when the worktree is cleaned up.
+3. When you're done, the SessionEnd hook will automatically report completion to Supabase.`);
+
+  return sections.join('\n\n');
+}

package/lib/cron.js

@@ -0,0 +1,382 @@
+/**
+ * Cron job scheduler for Push daemon.
+ *
+ * Stores recurring/one-shot jobs in ~/.push/cron/jobs.json.
+ * Called from daemon main loop on each poll cycle.
+ *
+ * No npm dependencies — includes minimal cron expression parser.
+ * Architecture: docs/20260214_push_daemon_evolution_complete_architecture.md §23
+ * Pattern: Follow self-update.js — pure functions, called from daemon.js.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { sendMacNotification } from './utils/notify.js';
+
+const CRON_DIR = join(homedir(), '.push', 'cron');
+const JOBS_FILE = join(CRON_DIR, 'jobs.json');
+
+// ==================== Storage ====================
+
+function ensureCronDir() {
+  mkdirSync(CRON_DIR, { recursive: true });
+}
+
+/**
+ * Load all cron jobs from disk.
+ * @returns {Array} Job objects
+ */
+export function loadJobs() {
+  if (!existsSync(JOBS_FILE)) return [];
+  try {
+    return JSON.parse(readFileSync(JOBS_FILE, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save all cron jobs to disk.
+ * @param {Array} jobs
+ */
+export function saveJobs(jobs) {
+  ensureCronDir();
+  writeFileSync(JOBS_FILE, JSON.stringify(jobs, null, 2) + '\n');
+}
+
+// ==================== Interval Parsing ====================
+
+/**
+ * Parse an interval string into milliseconds.
+ * Supports: "30m", "1h", "24h", "7d"
+ *
+ * @param {string} value - Interval string
+ * @returns {number} Milliseconds
+ */
+export function parseInterval(value) {
+  const match = value.match(/^(\d+)(m|h|d)$/);
+  if (!match) {
+    throw new Error(`Invalid interval format: "${value}". Use Nm, Nh, or Nd (e.g., "30m", "1h", "7d")`);
+  }
+
+  const num = parseInt(match[1], 10);
+  const unit = match[2];
+
+  const multipliers = { m: 60000, h: 3600000, d: 86400000 };
+  return num * multipliers[unit];
+}
+
+// ==================== Cron Expression Parser ====================
+
+// Parse a single cron field into an array of valid values.
+// Supports: *, N, N-M, N,M, and step expressions.
+function parseCronField(field, min, max) {
+  const values = new Set();
+
+  for (const part of field.split(',')) {
+    const trimmed = part.trim();
+
+    // */N — every N
+    if (trimmed.startsWith('*/')) {
+      const step = parseInt(trimmed.slice(2), 10);
+      if (isNaN(step) || step <= 0) throw new Error(`Invalid cron step: ${trimmed}`);
+      for (let i = min; i <= max; i += step) values.add(i);
+      continue;
+    }
+
+    // * — all values
+    if (trimmed === '*') {
+      for (let i = min; i <= max; i++) values.add(i);
+      continue;
+    }
+
+    // N-M — range
+    if (trimmed.includes('-')) {
+      const [startStr, endStr] = trimmed.split('-');
+      const start = parseInt(startStr, 10);
+      const end = parseInt(endStr, 10);
+      if (isNaN(start) || isNaN(end)) throw new Error(`Invalid cron range: ${trimmed}`);
+      for (let i = start; i <= end; i++) values.add(i);
+      continue;
+    }
+
+    // N — specific value
+    const num = parseInt(trimmed, 10);
+    if (isNaN(num)) throw new Error(`Invalid cron value: ${trimmed}`);
+    values.add(num);
+  }
+
+  return [...values].sort((a, b) => a - b);
+}
+
+/**
+ * Parse a 5-field cron expression and compute the next matching time.
+ *
+ * @param {string} expression - Cron expression (e.g., "0 9 * * 1")
+ * @param {Date} [fromDate] - Start searching from this date (default: now)
+ * @returns {Date|null} Next matching time, or null if none within 366 days
+ */
+export function getNextCronMatch(expression, fromDate = new Date()) {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`Cron expression must have 5 fields, got ${fields.length}: "${expression}"`);
+  }
+
+  const minutes = parseCronField(fields[0], 0, 59);
+  const hours = parseCronField(fields[1], 0, 23);
+  const daysOfMonth = parseCronField(fields[2], 1, 31);
+  const months = parseCronField(fields[3], 1, 12);
+  const daysOfWeek = parseCronField(fields[4], 0, 6); // 0=Sun
+
+  // Start from the next minute
+  const candidate = new Date(fromDate);
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+
+  // Cap search at 366 days
+  const maxDate = new Date(fromDate.getTime() + 366 * 86400000);
+
+  while (candidate <= maxDate) {
+    const month = candidate.getMonth() + 1; // 1-indexed
+    const dayOfMonth = candidate.getDate();
+    const dayOfWeek = candidate.getDay(); // 0=Sun
+    const hour = candidate.getHours();
+    const minute = candidate.getMinutes();
+
+    // Check month
+    if (!months.includes(month)) {
+      // Skip to first day of next valid month
+      candidate.setMonth(candidate.getMonth() + 1, 1);
+      candidate.setHours(0, 0, 0, 0);
+      continue;
+    }
+
+    // Check day of month AND day of week
+    // Standard cron: if both are restricted (not *), either can match (OR logic).
+    // If only one is restricted, it must match.
+    const domRestricted = fields[2] !== '*';
+    const dowRestricted = fields[4] !== '*';
+
+    let dayMatch;
+    if (domRestricted && dowRestricted) {
+      dayMatch = daysOfMonth.includes(dayOfMonth) || daysOfWeek.includes(dayOfWeek);
+    } else if (domRestricted) {
+      dayMatch = daysOfMonth.includes(dayOfMonth);
+    } else if (dowRestricted) {
+      dayMatch = daysOfWeek.includes(dayOfWeek);
+    } else {
+      dayMatch = true;
+    }
+
+    if (!dayMatch) {
+      // Skip to next day
+      candidate.setDate(candidate.getDate() + 1);
+      candidate.setHours(0, 0, 0, 0);
+      continue;
+    }
+
+    // Check hour
+    if (!hours.includes(hour)) {
+      // Skip to next hour
+      candidate.setHours(candidate.getHours() + 1, 0, 0, 0);
+      continue;
+    }
+
+    // Check minute
+    if (!minutes.includes(minute)) {
+      candidate.setMinutes(candidate.getMinutes() + 1, 0, 0);
+      continue;
+    }
+
+    // All fields match
+    return candidate;
+  }
+
+  return null; // No match within 366 days
+}
+
+// ==================== Next Run Computation ====================
+
+/**
+ * Compute the next run time for a schedule.
+ *
+ * @param {{ type: string, value: string }} schedule
+ * @param {Date} [fromDate] - Compute relative to this date (default: now)
+ * @returns {string|null} ISO string of next run, or null if expired
+ */
+export function computeNextRun(schedule, fromDate = new Date()) {
+  switch (schedule.type) {
+    case 'at': {
+      const target = new Date(schedule.value);
+      return target > fromDate ? target.toISOString() : null;
+    }
+    case 'every': {
+      const ms = parseInterval(schedule.value);
+      return new Date(fromDate.getTime() + ms).toISOString();
+    }
+    case 'cron': {
+      const next = getNextCronMatch(schedule.value, fromDate);
+      return next ? next.toISOString() : null;
+    }
+    default:
+      throw new Error(`Unknown schedule type: ${schedule.type}`);
+  }
+}
+
+// ==================== Job Management ====================
+
+/**
+ * Add a new cron job.
+ *
+ * @param {Object} config
+ * @param {string} config.name - Job name
+ * @param {{ type: string, value: string }} config.schedule - Schedule definition
+ * @param {{ type: string, content: string }} config.action - Action to perform
+ * @returns {Object} Created job
+ */
+export function addJob(config) {
+  const { name, schedule, action } = config;
+
+  if (!name) throw new Error('Job name is required');
+  if (!schedule || !schedule.type || !schedule.value) throw new Error('Schedule is required');
+  if (!action || !action.type) throw new Error('Action is required');
+
+  // Validate schedule by computing next run
+  const nextRunAt = computeNextRun(schedule);
+  if (!nextRunAt) {
+    throw new Error(`Schedule "${schedule.type}: ${schedule.value}" has no future run time`);
+  }
+
+  const job = {
+    id: randomUUID(),
+    name,
+    schedule,
+    action,
+    enabled: true,
+    createdAt: new Date().toISOString(),
+    lastRunAt: null,
+    nextRunAt,
+  };
+
+  const jobs = loadJobs();
+  jobs.push(job);
+  saveJobs(jobs);
+
+  return job;
+}
+
+/**
+ * Remove a cron job by ID or ID prefix.
+ *
+ * @param {string} idOrPrefix - Full UUID or prefix (min 4 chars)
+ * @returns {boolean} True if found and removed
+ */
+export function removeJob(idOrPrefix) {
+  const jobs = loadJobs();
+  const idx = jobs.findIndex(j =>
+    j.id === idOrPrefix || j.id.startsWith(idOrPrefix)
+  );
+
+  if (idx === -1) return false;
+
+  jobs.splice(idx, 1);
+  saveJobs(jobs);
+  return true;
+}
+
+/**
+ * List all cron jobs.
+ * @returns {Array} Job objects
+ */
+export function listJobs() {
+  return loadJobs();
+}
+
+// ==================== Execution ====================
+
+/**
+ * Execute a cron job action.
+ *
+ * @param {Object} job - Job object
+ * @param {Function} [logFn] - Optional log function
+ */
+async function executeAction(job, logFn) {
+  const log = logFn || (() => {});
+
+  switch (job.action.type) {
+    case 'notify':
+      sendMacNotification('Push Cron', job.action.content || job.name);
+      log(`Cron "${job.name}": notification sent`);
+      break;
+
+    case 'create-todo':
+      // Phase 2: notification-based (no Supabase edge function yet)
+      sendMacNotification('Push: Scheduled Todo', job.action.content || job.name);
+      log(`Cron "${job.name}": todo reminder sent (notification)`);
+      break;
+
+    case 'queue-execution':
+      // Requires todoId — log warning if missing
+      if (!job.action.todoId) {
+        log(`Cron "${job.name}": queue-execution requires todoId, skipping`);
+      } else {
+        log(`Cron "${job.name}": queue-execution for todo ${job.action.todoId} (not yet implemented)`);
+      }
+      break;
+
+    default:
+      log(`Cron "${job.name}": unknown action type "${job.action.type}"`);
+  }
+}
+
+/**
+ * Check for and run any due cron jobs.
+ * Called from daemon poll loop on every cycle.
+ *
+ * @param {Function} [logFn] - Optional log function
+ */
+export async function checkAndRunDueJobs(logFn) {
+  const jobs = loadJobs();
+  if (jobs.length === 0) return;
+
+  const now = new Date();
+  let modified = false;
+
+  for (const job of jobs) {
+    if (!job.enabled) continue;
+    if (!job.nextRunAt) continue;
+
+    const nextRun = new Date(job.nextRunAt);
+    if (nextRun > now) continue;
+
+    // Job is due — execute
+    try {
+      await executeAction(job, logFn);
+    } catch (error) {
+      if (logFn) logFn(`Cron "${job.name}" execution failed: ${error.message}`);
+    }
+
+    // Update timing
+    job.lastRunAt = now.toISOString();
+
+    if (job.schedule.type === 'at') {
+      // One-shot: disable after run
+      job.enabled = false;
+      job.nextRunAt = null;
+    } else {
+      // Recurring: compute next run
+      job.nextRunAt = computeNextRun(job.schedule, now);
+      if (!job.nextRunAt) {
+        job.enabled = false; // No more future runs
+      }
+    }
+
+    modified = true;
+  }
+
+  if (modified) {
+    saveJobs(jobs);
+  }
+}

package/lib/daemon.js

@@ -20,6 +20,10 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
 import { checkForUpdate, performUpdate } from './self-update.js';
+import { getProjectContext, buildSmartPrompt, invalidateCache } from './context-engine.js';
+import { sendMacNotification } from './utils/notify.js';
+import { checkAndRunDueJobs } from './cron.js';
+import { runHeartbeatChecks } from './heartbeat.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -193,26 +197,6 @@ function releaseLock() {
   try { unlinkSync(LOCK_FILE); } catch {}
 }
 
-// ==================== Mac Notifications ====================
-
-function sendMacNotification(title, message, sound = 'default') {
-  if (platform() !== 'darwin') return;
-
-  try {
-    const escapedTitle = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-    const escapedMessage = message.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-
-    let script = `display notification "${escapedMessage}" with title "${escapedTitle}"`;
-    if (sound && sound !== 'default') {
-      script += ` sound name "${sound}"`;
-    }
-
-    execSync(`osascript -e '${script}'`, { timeout: 5000, stdio: 'pipe' });
-  } catch {
-    // Non-critical
-  }
-}
-
 // ==================== Config ====================
 
 function getApiKey() {
@@ -601,6 +585,42 @@ function getProjectPath(gitRemote, actionType) {
   }
 }
 
+/**
+ * Get project info including path and action metadata.
+ * Like getProjectPath but also returns actionName for the prompt engine.
+ */
+function getProjectInfo(gitRemote, actionType) {
+  if (!existsSync(REGISTRY_FILE)) return null;
+  try {
+    const data = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+    const projects = data.projects || {};
+
+    // Try exact composite key first (V2 format)
+    if (actionType) {
+      const key = `${gitRemote}::${actionType}`;
+      if (projects[key]) {
+        return {
+          path: projects[key].localPath || projects[key].local_path || null,
+          actionName: projects[key].actionName || null,
+        };
+      }
+    }
+
+    // Fallback scan
+    for (const [key, info] of Object.entries(projects)) {
+      if ((info.gitRemote || key) === gitRemote) {
+        return {
+          path: info.localPath || info.local_path || null,
+          actionName: info.actionName || null,
+        };
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * List all registered projects (backward-compatible: gitRemote -> localPath).
  */
@@ -1360,15 +1380,18 @@ async function executeTask(task) {
   // Extract UUID early — needed for claim and all status updates
   const taskId = task.id || task.todo_id || '';
 
-  // Get project path (use action_type for multi-agent routing)
+  // Get project path + metadata (use action_type for multi-agent routing)
   let projectPath = null;
+  let actionName = null;
   if (gitRemote) {
-    projectPath = getProjectPath(gitRemote, taskActionType);
-    if (!projectPath) {
+    const projectInfo = getProjectInfo(gitRemote, taskActionType);
+    if (!projectInfo || !projectInfo.path) {
       log(`Task #${displayNumber}: Project not registered: ${gitRemote}`);
       log("Run '/push-todo connect' in the project directory to register");
       return null;
     }
+    projectPath = projectInfo.path;
+    actionName = projectInfo.actionName;
 
     if (!existsSync(projectPath)) {
       logError(`Task #${displayNumber}: Project path does not exist: ${projectPath}`);
@@ -1442,15 +1465,14 @@ async function executeTask(task) {
     // Non-critical — continue without attachment context
   }
 
-  // Build prompt
-  const prompt = `Work on Push task #${displayNumber}:
-
-${content}${attachmentContext}
-
-IMPORTANT:
-1. If you need to understand the codebase, start by reading the CLAUDE.md file if it exists.
-2. ALWAYS commit your changes before finishing. Use a descriptive commit message summarizing what you did. This is critical — uncommitted changes will be lost when the worktree is cleaned up.
-3. When you're done, the SessionEnd hook will automatically report completion to Supabase.`;
+  // Build context-rich prompt (skill scanning, project state, confirmation flags)
+  if (projectPath) invalidateCache(projectPath); // Fresh context for each task
+  const projectContext = projectPath ? getProjectContext(projectPath) : { skills: [], state: {} };
+  const contextApp = task.contextApp || task.context_app || null;
+  const prompt = buildSmartPrompt(
+    { displayNumber, content, attachmentContext, actionName, contextApp },
+    projectContext
+  );
 
   // Note: claimTask() already set status to 'running' with atomic: true
   // No duplicate status update needed here (was causing race conditions)
@@ -2105,6 +2127,25 @@ async function mainLoop() {
       await checkTimeouts();
       await pollAndExecute();
 
+      // Cron jobs (check every poll cycle, execution throttled by nextRunAt)
+      try {
+        await checkAndRunDueJobs(log);
+      } catch (error) {
+        logError(`Cron check error: ${error.message}`);
+      }
+
+      // Heartbeat checks (internally throttled: 10min fast, 1hr slow)
+      try {
+        const projects = getListedProjects();
+        await runHeartbeatChecks({
+          projectPaths: Object.values(projects),
+          apiRequest,
+          log,
+        });
+      } catch (error) {
+        logError(`Heartbeat error: ${error.message}`);
+      }
+
       // Self-update check (throttled to once per hour, only applies when idle)
       if (getAutoUpdateEnabled()) {
         checkAndApplyUpdate();

package/lib/heartbeat.js

@@ -0,0 +1,286 @@
+/**
+ * Heartbeat health checks for Push daemon.
+ *
+ * Tier 1 checks: deterministic, no LLM, fast, no cost.
+ * Runs on configurable intervals from the daemon poll loop.
+ *
+ * Architecture: docs/20260214_push_daemon_evolution_complete_architecture.md §23
+ * Pattern: Follow self-update.js — pure functions, non-fatal.
+ */
+
+import { execFileSync } from 'child_process';
+import { sendMacNotification } from './utils/notify.js';
+
+// ==================== Throttle Configuration ====================
+
+const FAST_CHECK_INTERVAL = 600000;  // 10 minutes
+const SLOW_CHECK_INTERVAL = 3600000; // 1 hour
+
+// ==================== Thresholds ====================
+
+const CONFIRMATION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const QUEUED_TASK_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
+const STALE_PR_HOURS = 48;
+
+// ==================== Internal State ====================
+
+let lastFastCheck = 0;
+let lastSlowCheck = 0;
+
+// Track already-notified items to avoid repeat alerts
+const notifiedItems = new Map(); // key -> timestamp (auto-expire after 24h)
+const NOTIFICATION_COOLDOWN = 24 * 60 * 60 * 1000; // 24 hours
+
+function shouldNotify(key) {
+  const last = notifiedItems.get(key);
+  if (last && (Date.now() - last) < NOTIFICATION_COOLDOWN) {
+    return false;
+  }
+  notifiedItems.set(key, Date.now());
+
+  // Prune old entries
+  if (notifiedItems.size > 200) {
+    const cutoff = Date.now() - NOTIFICATION_COOLDOWN;
+    for (const [k, t] of notifiedItems) {
+      if (t < cutoff) notifiedItems.delete(k);
+    }
+  }
+
+  return true;
+}
+
+// ==================== Fast Checks (every 10 min) ====================
+
+/**
+ * Check for tasks stuck in awaiting_confirmation.
+ *
+ * @param {Function} apiRequest - Daemon's authenticated API request function
+ * @param {Function} log - Log function
+ */
+async function checkConfirmationTimeouts(apiRequest, log) {
+  try {
+    const params = new URLSearchParams();
+    params.set('execution_status', 'awaiting_confirmation');
+    const response = await apiRequest(`synced-todos?${params}`);
+    if (!response.ok) return;
+
+    const data = await response.json();
+    const tasks = data.todos || [];
+    const now = Date.now();
+
+    for (const task of tasks) {
+      const events = task.executionEvents || task.execution_events || [];
+      const confirmEvent = events.find(e =>
+        e.type === 'confirmation_needed' || e.type === 'awaiting_confirmation'
+      );
+      if (!confirmEvent?.timestamp) continue;
+
+      const elapsed = now - new Date(confirmEvent.timestamp).getTime();
+      if (elapsed > CONFIRMATION_TIMEOUT_MS) {
+        const dn = task.displayNumber || task.display_number;
+        const minutes = Math.round(elapsed / 60000);
+        const key = `confirm-timeout-${dn}`;
+
+        if (shouldNotify(key)) {
+          sendMacNotification(
+            'Push: Confirmation Waiting',
+            `Task #${dn} has been awaiting confirmation for ${minutes} minutes`,
+            'Basso'
+          );
+          log(`Heartbeat: Task #${dn} confirmation timeout (${minutes}min)`);
+        }
+      }
+    }
+  } catch (error) {
+    log(`Heartbeat: confirmation timeout check failed: ${error.message}`);
+  }
+}
+
+/**
+ * Check for tasks queued for too long.
+ *
+ * @param {Function} apiRequest - Daemon's authenticated API request function
+ * @param {Function} log - Log function
+ */
+async function checkQueuedTaskAge(apiRequest, log) {
+  try {
+    const params = new URLSearchParams();
+    params.set('execution_status', 'queued');
+    const response = await apiRequest(`synced-todos?${params}`);
+    if (!response.ok) return;
+
+    const data = await response.json();
+    const tasks = data.todos || [];
+    const now = Date.now();
+
+    for (const task of tasks) {
+      // Use the first "queued" event timestamp, or fall back to modified_at
+      const events = task.executionEvents || task.execution_events || [];
+      const queuedEvent = events.find(e => e.type === 'queued' || e.type === 'requeued');
+      const queuedAt = queuedEvent?.timestamp || task.modified_at || task.modifiedAt;
+      if (!queuedAt) continue;
+
+      const elapsed = now - new Date(queuedAt).getTime();
+      if (elapsed > QUEUED_TASK_TIMEOUT_MS) {
+        const dn = task.displayNumber || task.display_number;
+        const hours = Math.round(elapsed / 3600000);
+        const key = `queued-age-${dn}`;
+
+        if (shouldNotify(key)) {
+          sendMacNotification(
+            'Push: Stale Queued Task',
+            `Task #${dn} has been queued for ${hours} hours`,
+            'Basso'
+          );
+          log(`Heartbeat: Task #${dn} queued for ${hours}h`);
+        }
+      }
+    }
+  } catch (error) {
+    log(`Heartbeat: queued task age check failed: ${error.message}`);
+  }
+}
+
+// ==================== Slow Checks (every 1 hour) ====================
+
+/**
+ * Check for stale PRs across registered projects.
+ *
+ * @param {string[]} projectPaths - Registered project local paths
+ * @param {Function} log - Log function
+ */
+function checkStalePRs(projectPaths, log) {
+  for (const projectPath of projectPaths) {
+    try {
+      const output = execFileSync('gh', [
+        'pr', 'list',
+        '--json', 'number,title,updatedAt',
+        '--limit', '10',
+      ], {
+        cwd: projectPath,
+        timeout: 15000,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }).trim();
+
+      if (!output) continue;
+
+      const prs = JSON.parse(output);
+      const now = Date.now();
+      const threshold = STALE_PR_HOURS * 3600000;
+
+      for (const pr of prs) {
+        if (!pr.updatedAt) continue;
+        const age = now - new Date(pr.updatedAt).getTime();
+
+        if (age > threshold) {
+          const hours = Math.round(age / 3600000);
+          const key = `stale-pr-${pr.number}`;
+
+          if (shouldNotify(key)) {
+            sendMacNotification(
+              'Push: Stale PR',
+              `PR #${pr.number} "${pr.title}" has been open ${hours}h with no activity`
+            );
+            log(`Heartbeat: Stale PR #${pr.number} (${hours}h)`);
+          }
+        }
+      }
+    } catch {
+      // gh not available or not authenticated for this project — skip
+    }
+  }
+}
+
+/**
+ * Check for CI failures on recent PRs.
+ *
+ * @param {string[]} projectPaths - Registered project local paths
+ * @param {Function} log - Log function
+ */
+function checkCIFailures(projectPaths, log) {
+  for (const projectPath of projectPaths) {
+    try {
+      // Get recent PRs
+      const prOutput = execFileSync('gh', [
+        'pr', 'list',
+        '--json', 'number,headRefName',
+        '--limit', '3',
+      ], {
+        cwd: projectPath,
+        timeout: 10000,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }).trim();
+
+      if (!prOutput) continue;
+      const prs = JSON.parse(prOutput);
+
+      for (const pr of prs) {
+        try {
+          const checksOutput = execFileSync('gh', [
+            'pr', 'checks', String(pr.number),
+            '--json', 'name,state',
+          ], {
+            cwd: projectPath,
+            timeout: 10000,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+          }).trim();
+
+          if (!checksOutput) continue;
+          const checks = JSON.parse(checksOutput);
+          const failures = checks.filter(c => c.state === 'FAILURE');
+
+          if (failures.length > 0) {
+            const key = `ci-fail-${pr.number}`;
+            if (shouldNotify(key)) {
+              const names = failures.map(f => f.name).join(', ');
+              sendMacNotification(
+                'Push: CI Failure',
+                `PR #${pr.number}: ${names} failed`,
+                'Glass'
+              );
+              log(`Heartbeat: CI failure on PR #${pr.number}: ${names}`);
+            }
+          }
+        } catch {
+          // Individual PR check failed — skip
+        }
+      }
+    } catch {
+      // gh not available — skip
+    }
+  }
+}
+
+// ==================== Main Entry ====================
+
+/**
+ * Run heartbeat checks (internally throttled).
+ *
+ * @param {Object} config
+ * @param {string[]} config.projectPaths - Registered project local paths
+ * @param {Function} config.apiRequest - Daemon's authenticated API request function
+ * @param {Function} config.log - Daemon's log function
+ */
+export async function runHeartbeatChecks(config) {
+  const { projectPaths, apiRequest, log } = config;
+  const now = Date.now();
+
+  // Fast checks (every 10 min)
+  if (now - lastFastCheck >= FAST_CHECK_INTERVAL) {
+    lastFastCheck = now;
+
+    await checkConfirmationTimeouts(apiRequest, log);
+    await checkQueuedTaskAge(apiRequest, log);
+  }
+
+  // Slow checks (every 1 hour)
+  if (now - lastSlowCheck >= SLOW_CHECK_INTERVAL) {
+    lastSlowCheck = now;
+
+    checkStalePRs(projectPaths, log);
+    checkCIFailures(projectPaths, log);
+  }
+}

package/lib/utils/notify.js

@@ -0,0 +1,32 @@
+/**
+ * Mac notification utility for Push daemon.
+ * Shared by daemon.js, cron.js, and heartbeat.js.
+ */
+
+import { execFileSync } from 'child_process';
+import { platform } from 'os';
+
+/**
+ * Send a macOS notification via osascript.
+ *
+ * @param {string} title - Notification title
+ * @param {string} message - Notification body
+ * @param {string} [sound='default'] - Sound name ('default', 'Basso', 'Glass', etc.)
+ */
+export function sendMacNotification(title, message, sound = 'default') {
+  if (platform() !== 'darwin') return;
+
+  try {
+    const escapedTitle = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const escapedMessage = message.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+
+    let script = `display notification "${escapedMessage}" with title "${escapedTitle}"`;
+    if (sound && sound !== 'default') {
+      script += ` sound name "${sound}"`;
+    }
+
+    execFileSync('osascript', ['-e', script], { timeout: 5000, stdio: 'pipe' });
+  } catch {
+    // Non-critical
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masslessai/push-todo",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "Voice tasks from Push iOS app for Claude Code",
   "type": "module",
   "bin": {