@masslessai/push-todo 4.1.3 → 4.1.5

package/lib/agent-versions.js

@@ -0,0 +1,204 @@
+/**
+ * Agent version detection and tracking for Push daemon.
+ *
+ * Detects installed versions of Claude Code, OpenAI Codex, and OpenClaw CLIs.
+ * Reports version parity with the push-todo CLI and flags outdated agents.
+ *
+ * Pattern: follows heartbeat.js — pure functions, internally throttled, non-fatal.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const PUSH_DIR = join(homedir(), '.push');
+const VERSIONS_CACHE_FILE = join(PUSH_DIR, 'agent_versions.json');
+const CHECK_INTERVAL = 3600000; // 1 hour
+
+// ==================== Agent Definitions ====================
+
+/**
+ * Agent CLI definitions: command name, version flag, and how to parse output.
+ *
+ * Each agent has:
+ * - cmd: the CLI binary name
+ * - versionArgs: args to get version string
+ * - parseVersion: extracts semver from command output
+ */
+const AGENTS = {
+  'claude-code': {
+    cmd: 'claude',
+    versionArgs: ['--version'],
+    parseVersion(output) {
+      // "claude v2.1.41" or just "2.1.41"
+      const match = output.match(/(\d+\.\d+\.\d+)/);
+      return match ? match[1] : null;
+    },
+  },
+  'openai-codex': {
+    cmd: 'codex',
+    versionArgs: ['--version'],
+    parseVersion(output) {
+      const match = output.match(/(\d+\.\d+\.\d+)/);
+      return match ? match[1] : null;
+    },
+  },
+  'openclaw': {
+    cmd: 'openclaw',
+    versionArgs: ['--version'],
+    parseVersion(output) {
+      const match = output.match(/(\d+\.\d+\.\d+)/);
+      return match ? match[1] : null;
+    },
+  },
+};
+
+// ==================== Version Detection ====================
+
+/**
+ * Detect the installed version of a single agent CLI.
+ *
+ * @param {string} agentType - One of 'claude-code', 'openai-codex', 'openclaw'
+ * @returns {{ installed: boolean, version: string|null, error: string|null }}
+ */
+export function detectAgentVersion(agentType) {
+  const agent = AGENTS[agentType];
+  if (!agent) {
+    return { installed: false, version: null, error: `Unknown agent type: ${agentType}` };
+  }
+
+  try {
+    const output = execFileSync(agent.cmd, agent.versionArgs, {
+      timeout: 10000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+
+    const version = agent.parseVersion(output);
+    if (version) {
+      return { installed: true, version, error: null };
+    }
+    return { installed: true, version: null, error: `Could not parse version from: ${output}` };
+  } catch (err) {
+    // ENOENT = not installed; other errors = installed but broken
+    if (err.code === 'ENOENT') {
+      return { installed: false, version: null, error: null };
+    }
+    return { installed: false, version: null, error: err.message };
+  }
+}
+
+/**
+ * Detect versions of all known agent CLIs.
+ *
+ * @returns {Object.<string, { installed: boolean, version: string|null, error: string|null }>}
+ */
+export function detectAllAgentVersions() {
+  const results = {};
+  for (const agentType of Object.keys(AGENTS)) {
+    results[agentType] = detectAgentVersion(agentType);
+  }
+  return results;
+}
+
+// ==================== Cache ====================
+
+/**
+ * Load cached agent version data.
+ *
+ * @returns {{ versions: Object, checkedAt: string|null }|null}
+ */
+function loadCache() {
+  try {
+    if (existsSync(VERSIONS_CACHE_FILE)) {
+      return JSON.parse(readFileSync(VERSIONS_CACHE_FILE, 'utf8'));
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Save agent version data to cache.
+ *
+ * @param {Object} versions - Agent version results
+ */
+function saveCache(versions) {
+  try {
+    mkdirSync(PUSH_DIR, { recursive: true });
+    writeFileSync(VERSIONS_CACHE_FILE, JSON.stringify({
+      versions,
+      checkedAt: new Date().toISOString(),
+    }, null, 2));
+  } catch {}
+}
+
+// ==================== Throttled Check ====================
+
+let lastCheckTime = 0;
+let cachedResults = null;
+
+/**
+ * Get agent versions (throttled to once per hour).
+ * Returns cached results if within the check interval.
+ *
+ * @param {{ force?: boolean }} options
+ * @returns {Object.<string, { installed: boolean, version: string|null, error: string|null }>}
+ */
+export function getAgentVersions({ force = false } = {}) {
+  const now = Date.now();
+
+  // Return in-memory cache if fresh
+  if (!force && cachedResults && (now - lastCheckTime < CHECK_INTERVAL)) {
+    return cachedResults;
+  }
+
+  // Try disk cache if no in-memory cache
+  if (!force && !cachedResults) {
+    const diskCache = loadCache();
+    if (diskCache?.checkedAt) {
+      const cacheAge = now - new Date(diskCache.checkedAt).getTime();
+      if (cacheAge < CHECK_INTERVAL) {
+        cachedResults = diskCache.versions;
+        lastCheckTime = now - (CHECK_INTERVAL - cacheAge); // preserve remaining TTL
+        return cachedResults;
+      }
+    }
+  }
+
+  // Fresh detection
+  cachedResults = detectAllAgentVersions();
+  lastCheckTime = now;
+  saveCache(cachedResults);
+  return cachedResults;
+}
+
+/**
+ * Get a human-readable summary of agent versions for logging.
+ *
+ * @param {Object} versions - From getAgentVersions()
+ * @returns {string}
+ */
+export function formatAgentVersionSummary(versions) {
+  const parts = [];
+  for (const [type, info] of Object.entries(versions)) {
+    const label = type.replace(/-/g, ' ');
+    if (info.installed && info.version) {
+      parts.push(`${label}=v${info.version}`);
+    } else if (info.installed) {
+      parts.push(`${label}=installed (unknown version)`);
+    } else {
+      parts.push(`${label}=not found`);
+    }
+  }
+  return parts.join(', ');
+}
+
+/**
+ * Get the list of known agent types.
+ *
+ * @returns {string[]}
+ */
+export function getKnownAgentTypes() {
+  return Object.keys(AGENTS);
+}

package/lib/cli.js

@@ -47,6 +47,7 @@ ${bold('USAGE:')}
   push-todo connect                Run connection doctor
   push-todo search <query>         Search tasks
   push-todo review                 Review completed tasks
+  push-todo update                 Update CLI, check agents, refresh projects
 
 ${bold('OPTIONS:')}
   --all-projects, -a               List tasks from all projects
@@ -655,6 +656,12 @@ export async function run(argv) {
     return runConnect(values);
   }
 
+  // Update command - manual update of CLI, agents, and project freshness
+  if (command === 'update') {
+    const { runManualUpdate } = await import('./update.js');
+    return runManualUpdate(values);
+  }
+
   // Review command
   if (command === 'review') {
     return fetch.runReview(values);

package/lib/daemon.js

@@ -15,7 +15,7 @@
 
 import { randomUUID } from 'crypto';
 import { spawn, execSync, execFileSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, unlinkSync, statSync, renameSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync, unlinkSync, statSync, renameSync, readdirSync } from 'fs';
 import { homedir, hostname, platform } from 'os';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -25,6 +25,8 @@ import { getProjectContext, buildSmartPrompt, invalidateCache } from './context-
 import { sendMacNotification } from './utils/notify.js';
 import { checkAndRunDueJobs } from './cron.js';
 import { runHeartbeatChecks } from './heartbeat.js';
+import { getAgentVersions, formatAgentVersionSummary } from './agent-versions.js';
+import { checkAllProjectsFreshness } from './project-freshness.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -46,6 +48,10 @@ const RETRY_BACKOFF_FACTOR = 2;
 const CERTAINTY_HIGH_THRESHOLD = 0.7;
 const CERTAINTY_LOW_THRESHOLD = 0.4;
 
+// Idle auto-recovery (Level B)
+const IDLE_TIMEOUT_MS = 900000; // 15 min no stdout → kill (smarter than absolute timeout)
+const HEARTBEAT_INTERVAL_MS = 300000; // 5 min progress heartbeat to Supabase (Level A)
+
 // Stuck detection
 const STUCK_IDLE_THRESHOLD = 600000; // 10 min
 const STUCK_WARNING_THRESHOLD = 300000; // 5 min
@@ -108,6 +114,7 @@ const taskLastOutput = new Map(); // displayNumber -> timestamp
 const taskStdoutBuffer = new Map(); // displayNumber -> lines[]
 const taskStderrBuffer = new Map(); // displayNumber -> lines[]
 const taskProjectPaths = new Map(); // displayNumber -> projectPath
+const taskLastHeartbeat = new Map(); // displayNumber -> timestamp of last progress heartbeat
 let daemonStartTime = null;
 
 // ==================== Utilities ====================
@@ -281,6 +288,59 @@ let cachedCapabilities = null;
 let lastCapabilityCheck = 0;
 const CAPABILITY_CHECK_INTERVAL = 3600000; // 1 hour
 
+/**
+ * Discover skills for all registered projects.
+ * Scans ~/.claude/skills/ (global) and <projectPath>/.claude/skills/ (per-project).
+ * Returns: { "github.com/user/repo": ["skill1", "skill2"], ... }
+ */
+function discoverProjectSkills() {
+  const globalSkillsDir = join(homedir(), '.claude', 'skills');
+  const globalSkills = [];
+
+  // Enumerate global skills
+  if (existsSync(globalSkillsDir)) {
+    try {
+      for (const entry of readdirSync(globalSkillsDir, { withFileTypes: true })) {
+        if (entry.isDirectory() || entry.isSymbolicLink()) {
+          globalSkills.push(entry.name);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  // For each registered project, enumerate project-local skills and merge with global
+  const result = {};
+  if (!existsSync(REGISTRY_FILE)) return result;
+
+  try {
+    const data = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+    for (const [, info] of Object.entries(data.projects || {})) {
+      const remote = info.gitRemote;
+      const localPath = info.localPath || info.local_path;
+      if (!remote || !localPath) continue;
+
+      const projectSkillsDir = join(localPath, '.claude', 'skills');
+      const projectSkills = new Set(globalSkills);
+
+      if (existsSync(projectSkillsDir)) {
+        try {
+          for (const entry of readdirSync(projectSkillsDir, { withFileTypes: true })) {
+            if (entry.isDirectory() || entry.isSymbolicLink()) {
+              projectSkills.add(entry.name);
+            }
+          }
+        } catch { /* ignore */ }
+      }
+
+      if (projectSkills.size > 0) {
+        result[remote] = [...projectSkills].sort();
+      }
+    }
+  } catch { /* ignore */ }
+
+  return result;
+}
+
 function detectCapabilities() {
   const caps = {
     auto_merge: getAutoMergeEnabled(),
@@ -300,6 +360,8 @@ function detectCapabilities() {
     caps.gh_cli = 'not_installed';
   }
 
+  caps.project_skills = discoverProjectSkills();
+
   return caps;
 }
 
@@ -1338,6 +1400,151 @@ function checkTaskIdle(displayNumber) {
   return false;
 }
 
+// ==================== Progress Heartbeat (Level A) ====================
+
+async function sendProgressHeartbeats() {
+  const now = Date.now();
+
+  for (const [displayNumber, taskInfo] of runningTasks) {
+    const info = taskDetails.get(displayNumber) || {};
+
+    // Skip tasks awaiting user confirmation (not truly hanging)
+    if (info.phase === 'awaiting_confirmation') continue;
+
+    // Throttle: only send every HEARTBEAT_INTERVAL_MS
+    const lastHeartbeat = taskLastHeartbeat.get(displayNumber) || taskInfo.startTime;
+    if (now - lastHeartbeat < HEARTBEAT_INTERVAL_MS) continue;
+
+    // Compute metrics
+    const elapsedSec = Math.floor((now - taskInfo.startTime) / 1000);
+    const elapsedMin = Math.floor(elapsedSec / 60);
+    const lastOutputTs = taskLastOutput.get(displayNumber);
+    const idleSec = lastOutputTs ? Math.floor((now - lastOutputTs) / 1000) : elapsedSec;
+    const idleMin = Math.floor(idleSec / 60);
+
+    const activityDesc = idleSec < 60 ? 'active' : `idle ${idleMin}m`;
+    const phase = info.phase || 'executing';
+    const eventSummary = `Running for ${elapsedMin}m. Last activity: ${activityDesc}. Phase: ${phase}.`;
+
+    log(`Task #${displayNumber}: sending progress heartbeat (${eventSummary})`);
+
+    // Update throttle timestamp BEFORE the async call to prevent concurrent sends
+    taskLastHeartbeat.set(displayNumber, now);
+
+    // Send event-only update (no status field) — non-fatal if it fails
+    const taskId = info.taskId || null;
+    apiRequest('update-task-execution', {
+      method: 'PATCH',
+      body: JSON.stringify({
+        todoId: taskId,
+        displayNumber,
+        event: {
+          type: 'progress',
+          timestamp: new Date().toISOString(),
+          machineName: getMachineName() || undefined,
+          summary: eventSummary
+        }
+        // No status field — event-only update, won't change execution_status
+      })
+    }).catch(err => {
+      log(`Task #${displayNumber}: heartbeat failed (non-fatal): ${err.message}`);
+    });
+    // NOTE: intentionally not awaited — heartbeats are fire-and-forget
+    // to avoid blocking the poll loop when Supabase is slow
+  }
+}
+
+// ==================== Idle Auto-Recovery (Level B) ====================
+
+async function killIdleTasks() {
+  const now = Date.now();
+  const idleTimedOut = [];
+
+  for (const [displayNumber, taskInfo] of runningTasks) {
+    const info = taskDetails.get(displayNumber) || {};
+
+    // Exempt: tasks awaiting user confirmation
+    if (info.phase === 'awaiting_confirmation') continue;
+
+    const lastOutput = taskLastOutput.get(displayNumber);
+    if (!lastOutput) continue; // No output tracking yet — not idle, just starting
+
+    const idleMs = now - lastOutput;
+    if (idleMs > IDLE_TIMEOUT_MS) {
+      log(`Task #${displayNumber} IDLE TIMEOUT: ${Math.floor(idleMs / 1000)}s since last output`);
+      idleTimedOut.push(displayNumber);
+    }
+  }
+
+  for (const displayNumber of idleTimedOut) {
+    const taskInfo = runningTasks.get(displayNumber);
+    if (!taskInfo) continue;
+
+    const info = taskDetails.get(displayNumber) || {};
+    const projectPath = taskProjectPaths.get(displayNumber);
+    const elapsedSec = Math.floor((now - taskInfo.startTime) / 1000);
+    const idleSec = Math.floor((now - (taskLastOutput.get(displayNumber) || taskInfo.startTime)) / 1000);
+    const durationStr = elapsedSec < 60 ? `${elapsedSec}s` : `${Math.floor(elapsedSec / 60)}m ${elapsedSec % 60}s`;
+    const machineName = getMachineName() || 'Mac';
+
+    // Extract semantic summary WHILE session is still alive
+    // (a live session produces a better "what have you done so far" answer)
+    const sessionId = taskInfo.sessionId;
+    const worktreePath = getWorktreePath(displayNumber, projectPath);
+    const summaryPath = existsSync(worktreePath) ? worktreePath : (projectPath || process.cwd());
+    log(`Task #${displayNumber}: extracting pre-kill summary...`);
+    const idleSummary = extractSemanticSummary(summaryPath, sessionId);
+
+    // Now kill the process
+    log(`Task #${displayNumber}: killing idle process (PID: ${taskInfo.process.pid})`);
+    try {
+      taskInfo.process.kill('SIGTERM');
+      await new Promise(r => setTimeout(r, 5000));
+      taskInfo.process.kill('SIGKILL');
+    } catch {}
+
+    runningTasks.delete(displayNumber);
+    cleanupWorktree(displayNumber, projectPath);
+
+    const idleError = idleSummary
+      ? `${idleSummary}\nSession went idle for ${Math.floor(idleSec / 60)}m with no output. Killed after ${durationStr} on ${machineName}.`
+      : `Session went idle for ${Math.floor(idleSec / 60)}m with no output (limit: ${IDLE_TIMEOUT_MS / 60000}m). Killed after ${durationStr} on ${machineName}.`;
+
+    await updateTaskStatus(displayNumber, 'failed', {
+      error: idleError,
+      sessionId
+    }, info.taskId);
+
+    if (NOTIFY_ON_FAILURE) {
+      sendMacNotification(
+        `Task #${displayNumber} idle timeout`,
+        `${(info.summary || 'Unknown').slice(0, 40)}... idle ${Math.floor(idleSec / 60)}m`,
+        'Basso'
+      );
+    }
+
+    trackCompleted({
+      displayNumber,
+      summary: info.summary || 'Unknown task',
+      completedAt: new Date().toISOString(),
+      duration: elapsedSec,
+      status: 'idle_timeout'
+    });
+
+    // Full cleanup of all tracking Maps
+    taskDetails.delete(displayNumber);
+    taskLastOutput.delete(displayNumber);
+    taskStdoutBuffer.delete(displayNumber);
+    taskStderrBuffer.delete(displayNumber);
+    taskProjectPaths.delete(displayNumber);
+    taskLastHeartbeat.delete(displayNumber);
+  }
+
+  if (idleTimedOut.length > 0) {
+    updateStatusFile();
+  }
+}
+
 // ==================== Session ID Extraction ====================
 
 function extractSessionIdFromStdout(proc, buffer) {
@@ -1614,7 +1821,6 @@ async function executeTask(task) {
     ? [
         '--continue', previousSessionId,
         '-p', prompt,
-        '--worktree', worktreeName,
         '--allowedTools', allowedTools,
         '--output-format', 'json',
         '--permission-mode', 'bypassPermissions',
@@ -1622,7 +1828,6 @@ async function executeTask(task) {
       ]
     : [
         '-p', prompt,
-        '--worktree', worktreeName,
         '--allowedTools', allowedTools,
         '--output-format', 'json',
         '--permission-mode', 'bypassPermissions',
@@ -1658,6 +1863,7 @@ async function executeTask(task) {
     taskLastOutput.set(displayNumber, Date.now());
     taskStdoutBuffer.set(displayNumber, []);
     taskStderrBuffer.set(displayNumber, []);
+    taskLastHeartbeat.set(displayNumber, Date.now());
 
     // Monitor stderr (critical for diagnosing fast exits)
     child.stderr.on('data', (data) => {
@@ -1713,6 +1919,7 @@ async function executeTask(task) {
       runningTasks.delete(displayNumber);
       await updateTaskStatus(displayNumber, 'failed', { error: error.message }, taskId);
       taskDetails.delete(displayNumber);
+      taskLastHeartbeat.delete(displayNumber);
       updateStatusFile();
     });
 
@@ -1936,6 +2143,7 @@ async function handleTaskCompletion(displayNumber, exitCode) {
   taskStdoutBuffer.delete(displayNumber);
   taskStderrBuffer.delete(displayNumber);
   taskProjectPaths.delete(displayNumber);
+  taskLastHeartbeat.delete(displayNumber);
   updateStatusFile();
 }
 
@@ -2014,6 +2222,13 @@ function updateStatusFile() {
 // ==================== Task Checking ====================
 
 async function checkTimeouts() {
+  // Level A: Send progress heartbeats for long-running tasks
+  await sendProgressHeartbeats();
+
+  // Level B: Kill tasks that have been idle too long (fires at 15 min, before 60 min absolute)
+  await killIdleTasks();
+
+  // Absolute timeout (safety net — 60 min wall clock)
   const now = Date.now();
   const timedOut = [];
 
@@ -2080,6 +2295,7 @@ async function checkTimeouts() {
     taskStdoutBuffer.delete(displayNumber);
     taskStderrBuffer.delete(displayNumber);
     taskProjectPaths.delete(displayNumber);
+    taskLastHeartbeat.delete(displayNumber);
     cleanupWorktree(displayNumber, projectPath);
   }
 
@@ -2243,6 +2459,8 @@ async function mainLoop() {
   log(`Auto-update: ${getAutoUpdateEnabled() ? 'Enabled' : 'Disabled'}`);
   const caps = getCapabilities();
   log(`Capabilities: gh=${caps.gh_cli}, auto-merge=${caps.auto_merge}, auto-complete=${caps.auto_complete}`);
+  const agentVersions = getAgentVersions({ force: true });
+  log(`Agent versions: ${formatAgentVersionSummary(agentVersions)}`);
   log(`Log file: ${LOG_FILE}`);
 
   // Show registered projects
@@ -2313,6 +2531,30 @@ async function mainLoop() {
         logError(`Heartbeat error: ${error.message}`);
       }
 
+      // Project freshness check (internally throttled to once per hour)
+      try {
+        const projects = getListedProjects();
+        const busyPaths = new Set();
+        for (const [, info] of runningTasks) {
+          if (info.projectPath) busyPaths.add(info.projectPath);
+        }
+        checkAllProjectsFreshness({
+          projects,
+          autoRebase: getAutoUpdateEnabled(),
+          busyPaths,
+          log,
+        });
+      } catch (error) {
+        logError(`Freshness check error: ${error.message}`);
+      }
+
+      // Agent version check (internally throttled to once per hour)
+      try {
+        getAgentVersions();
+      } catch (error) {
+        logError(`Agent version check error: ${error.message}`);
+      }
+
       // Self-update check (throttled to once per hour, only applies when idle)
       if (getAutoUpdateEnabled()) {
         checkAndApplyUpdate();

package/lib/fetch.js

@@ -12,6 +12,7 @@ import { formatTaskForDisplay, formatSearchResult } from './utils/format.js';
 import { bold, green, yellow, red, cyan, dim, muted } from './utils/colors.js';
 import { decryptTodoField, isE2EEAvailable } from './encryption.js';
 import { getAutoCommitEnabled, getAutoMergeEnabled, getAutoCompleteEnabled, getAutoUpdateEnabled, getMaxBatchSize } from './config.js';
+import { getAgentVersions } from './agent-versions.js';
 import { writeFileSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
@@ -445,6 +446,26 @@ export async function showStatus(options = {}) {
   console.log(`${bold('Auto-update:')} ${autoUpdate ? 'Enabled' : 'Disabled'}`);
   console.log(`${bold('Max batch size:')} ${maxBatch}`);
   console.log(`${bold('Registered projects:')} ${status.registeredProjects}`);
+  console.log('');
+
+  // Agent versions
+  const agentVersions = getAgentVersions();
+  console.log(bold('Agent Versions:'));
+  const agentLabels = {
+    'claude-code': 'Claude Code',
+    'openai-codex': 'Codex',
+    'openclaw': 'OpenClaw',
+  };
+  for (const [type, info] of Object.entries(agentVersions)) {
+    const label = agentLabels[type] || type;
+    if (info.installed && info.version) {
+      console.log(`  ${bold(label + ':')} ${green('v' + info.version)}`);
+    } else if (info.installed) {
+      console.log(`  ${bold(label + ':')} ${yellow('installed (unknown version)')}`);
+    } else {
+      console.log(`  ${bold(label + ':')} ${dim('not installed')}`);
+    }
+  }
 }
 
 /**

package/lib/project-freshness.js

@@ -0,0 +1,270 @@
+/**
+ * Project freshness checker for Push daemon.
+ *
+ * Checks if registered projects are behind their remote and optionally
+ * pulls updates via rebase. Only updates when the working tree is clean
+ * and no daemon tasks are running for that project.
+ *
+ * Pattern: follows heartbeat.js — pure functions, internally throttled, non-fatal.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+// ==================== Configuration ====================
+
+const FRESHNESS_CHECK_INTERVAL = 3600000; // 1 hour
+
+// ==================== Internal State ====================
+
+let lastFreshnessCheck = 0;
+
+// ==================== Git Helpers ====================
+
+/**
+ * Get the default branch for a repository (main or master).
+ *
+ * @param {string} projectPath
+ * @returns {string|null}
+ */
+function getDefaultBranch(projectPath) {
+  try {
+    // Try symbolic-ref to origin/HEAD first
+    const ref = execFileSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
+      cwd: projectPath,
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    // "refs/remotes/origin/main" → "main"
+    return ref.split('/').pop();
+  } catch {
+    // Fallback: check if main or master exists
+    for (const branch of ['main', 'master']) {
+      try {
+        execFileSync('git', ['rev-parse', '--verify', `refs/remotes/origin/${branch}`], {
+          cwd: projectPath,
+          timeout: 5000,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return branch;
+      } catch {}
+    }
+    return null;
+  }
+}
+
+/**
+ * Get the currently checked-out branch.
+ *
+ * @param {string} projectPath
+ * @returns {string|null}
+ */
+function getCurrentBranch(projectPath) {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], {
+      cwd: projectPath,
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the working tree is clean (no uncommitted changes).
+ *
+ * @param {string} projectPath
+ * @returns {boolean}
+ */
+function isWorkingTreeClean(projectPath) {
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      cwd: projectPath,
+      timeout: 10000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    return status === '';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Fetch from remote (quiet, non-interactive).
+ *
+ * @param {string} projectPath
+ * @returns {boolean} true if fetch succeeded
+ */
+function gitFetch(projectPath) {
+  try {
+    execFileSync('git', ['fetch', '--quiet'], {
+      cwd: projectPath,
+      timeout: 30000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Count how many commits the local branch is behind the remote.
+ *
+ * @param {string} projectPath
+ * @param {string} branch
+ * @returns {number} commits behind, or -1 on error
+ */
+function commitsBehind(projectPath, branch) {
+  try {
+    const output = execFileSync('git', [
+      'rev-list', '--count', `${branch}..origin/${branch}`
+    ], {
+      cwd: projectPath,
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    return parseInt(output, 10) || 0;
+  } catch {
+    return -1;
+  }
+}
+
+// ==================== Freshness Check ====================
+
+/**
+ * Check and optionally update a single project.
+ *
+ * @param {string} projectPath - Absolute path to the project
+ * @param {Object} options
+ * @param {boolean} options.autoRebase - If true, pull --rebase when behind
+ * @param {Set<string>} options.busyPaths - Paths with running tasks (skip these)
+ * @param {Function} options.log - Logging function
+ * @returns {{ status: string, behind?: number, updated?: boolean, error?: string }}
+ */
+export function checkProjectFreshness(projectPath, { autoRebase = false, busyPaths = new Set(), log = () => {} } = {}) {
+  if (!existsSync(join(projectPath, '.git'))) {
+    return { status: 'not_a_repo' };
+  }
+
+  const defaultBranch = getDefaultBranch(projectPath);
+  if (!defaultBranch) {
+    return { status: 'no_default_branch' };
+  }
+
+  const currentBranch = getCurrentBranch(projectPath);
+
+  // Fetch latest from remote
+  if (!gitFetch(projectPath)) {
+    return { status: 'fetch_failed' };
+  }
+
+  // Check how far behind the default branch is
+  const behind = commitsBehind(projectPath, defaultBranch);
+  if (behind < 0) {
+    return { status: 'compare_failed' };
+  }
+
+  if (behind === 0) {
+    return { status: 'up_to_date', behind: 0 };
+  }
+
+  // Project is behind — decide whether to auto-update
+  if (!autoRebase) {
+    return { status: 'behind', behind };
+  }
+
+  // Skip if tasks are running in this project
+  if (busyPaths.has(projectPath)) {
+    log(`Freshness: ${projectPath} is ${behind} commit(s) behind but has running tasks — skipping rebase`);
+    return { status: 'behind_busy', behind };
+  }
+
+  // Skip if not on default branch (user is on a feature branch)
+  if (currentBranch !== defaultBranch) {
+    log(`Freshness: ${projectPath} is ${behind} commit(s) behind but on branch '${currentBranch}' — skipping rebase`);
+    return { status: 'behind_wrong_branch', behind, currentBranch };
+  }
+
+  // Skip if working tree is dirty
+  if (!isWorkingTreeClean(projectPath)) {
+    log(`Freshness: ${projectPath} is ${behind} commit(s) behind but working tree is dirty — skipping rebase`);
+    return { status: 'behind_dirty', behind };
+  }
+
+  // Safe to rebase
+  try {
+    execFileSync('git', ['pull', '--rebase', '--quiet'], {
+      cwd: projectPath,
+      timeout: 60000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    log(`Freshness: ${projectPath} updated (${behind} commit(s) rebased)`);
+    return { status: 'updated', behind, updated: true };
+  } catch (err) {
+    // Abort failed rebase to leave tree clean
+    try {
+      execFileSync('git', ['rebase', '--abort'], {
+        cwd: projectPath,
+        timeout: 5000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {}
+    log(`Freshness: ${projectPath} rebase failed — aborted. Error: ${err.message}`);
+    return { status: 'rebase_failed', behind, error: err.message };
+  }
+}
+
+/**
+ * Check freshness of all registered projects (internally throttled).
+ *
+ * @param {Object} config
+ * @param {Object.<string, string>} config.projects - gitRemote → localPath mapping
+ * @param {boolean} config.autoRebase - Whether to auto-pull when behind
+ * @param {Set<string>} config.busyPaths - Paths with running tasks
+ * @param {Function} config.log - Logging function
+ * @param {boolean} [config.force] - Skip throttle
+ * @returns {Object.<string, Object>|null} Results per project path, or null if throttled
+ */
+export function checkAllProjectsFreshness(config) {
+  const { projects, autoRebase = false, busyPaths = new Set(), log = () => {}, force = false } = config;
+  const now = Date.now();
+
+  if (!force && (now - lastFreshnessCheck < FRESHNESS_CHECK_INTERVAL)) {
+    return null; // throttled
+  }
+  lastFreshnessCheck = now;
+
+  const results = {};
+  const paths = Object.values(projects);
+
+  for (const projectPath of paths) {
+    results[projectPath] = checkProjectFreshness(projectPath, {
+      autoRebase,
+      busyPaths,
+      log,
+    });
+  }
+
+  // Log summary
+  const behindCount = Object.values(results).filter(r =>
+    r.status === 'behind' || r.status === 'behind_busy' ||
+    r.status === 'behind_dirty' || r.status === 'behind_wrong_branch'
+  ).length;
+  const updatedCount = Object.values(results).filter(r => r.status === 'updated').length;
+
+  if (behindCount > 0 || updatedCount > 0) {
+    log(`Freshness: ${updatedCount} project(s) updated, ${behindCount} behind`);
+  }
+
+  return results;
+}

package/lib/update.js

@@ -0,0 +1,150 @@
+/**
+ * Manual update orchestrator for Push CLI.
+ *
+ * `push-todo update` performs three actions:
+ * 1. Self-update: check and install latest push-todo from npm
+ * 2. Agent versions: detect and display installed agent CLI versions
+ * 3. Project freshness: fetch and rebase registered projects that are behind
+ *
+ * Separation of concerns:
+ * - Daemon: runs all three checks periodically (hourly, throttled, non-interactive)
+ * - This module: runs on explicit user request (immediate, verbose, interactive)
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+import { checkForUpdate, performUpdate, compareSemver } from './self-update.js';
+import { getAgentVersions, getKnownAgentTypes } from './agent-versions.js';
+import { checkProjectFreshness } from './project-freshness.js';
+import { getRegistry } from './project-registry.js';
+import { bold, green, yellow, red, cyan, dim } from './utils/colors.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getVersion() {
+  try {
+    return JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+const AGENT_LABELS = {
+  'claude-code': 'Claude Code',
+  'openai-codex': 'Codex',
+  'openclaw': 'OpenClaw',
+};
+
+/**
+ * Run the manual update flow.
+ *
+ * @param {Object} values - Parsed CLI flags
+ */
+export async function runManualUpdate(values) {
+  const currentVersion = getVersion();
+
+  console.log();
+  console.log(bold('  Push Update'));
+  console.log('  ' + '='.repeat(40));
+  console.log();
+
+  // ── 1. Self-update ──────────────────────────────────────
+  console.log(bold('  Push CLI'));
+  console.log(`  Current version: v${currentVersion}`);
+
+  // Force bypass throttle for manual check
+  const updateResult = checkForUpdate(currentVersion);
+
+  if (updateResult.available) {
+    console.log(`  Latest version:  ${green('v' + updateResult.version)}`);
+    console.log();
+    console.log(`  Updating to v${updateResult.version}...`);
+    const success = performUpdate(updateResult.version);
+    if (success) {
+      console.log(`  ${green('Updated successfully')}`);
+    } else {
+      console.log(`  ${red('Update failed')} — try: npm install -g @masslessai/push-todo`);
+    }
+  } else if (updateResult.reason === 'too_recent') {
+    console.log(`  Latest version:  v${updateResult.version} ${dim('(published <1hr ago, waiting)')}`);
+    console.log(`  ${green('Up to date')}`);
+  } else {
+    console.log(`  ${green('Up to date')}`);
+  }
+  console.log();
+
+  // ── 2. Agent versions ──────────────────────────────────
+  console.log(bold('  Agent CLIs'));
+
+  const agentVersions = getAgentVersions({ force: true });
+  for (const type of getKnownAgentTypes()) {
+    const info = agentVersions[type];
+    const label = AGENT_LABELS[type] || type;
+
+    if (info.installed && info.version) {
+      console.log(`  ${label}: ${green('v' + info.version)}`);
+    } else if (info.installed) {
+      console.log(`  ${label}: ${yellow('installed')} ${dim('(version unknown)')}`);
+    } else {
+      console.log(`  ${label}: ${dim('not installed')}`);
+    }
+  }
+  console.log();
+
+  // ── 3. Project freshness ───────────────────────────────
+  const registry = getRegistry();
+  const projects = registry.listProjects();
+  const projectPaths = Object.entries(projects);
+
+  if (projectPaths.length === 0) {
+    console.log(bold('  Projects'));
+    console.log(`  ${dim('No projects registered')}`);
+    console.log();
+    return;
+  }
+
+  console.log(bold('  Project Freshness'));
+
+  for (const [remote, localPath] of projectPaths) {
+    const result = checkProjectFreshness(localPath, {
+      autoRebase: true,
+      busyPaths: new Set(), // Manual update has no running tasks
+      log: (msg) => console.log(`  ${dim(msg)}`),
+    });
+
+    const shortRemote = remote.length > 40
+      ? '...' + remote.slice(-37)
+      : remote;
+
+    switch (result.status) {
+      case 'up_to_date':
+        console.log(`  ${shortRemote}: ${green('up to date')}`);
+        break;
+      case 'updated':
+        console.log(`  ${shortRemote}: ${green('updated')} ${dim(`(${result.behind} commit(s) rebased)`)}`);
+        break;
+      case 'behind_wrong_branch':
+        console.log(`  ${shortRemote}: ${yellow(`${result.behind} behind`)} ${dim(`(on branch '${result.currentBranch}')`)}`);
+        break;
+      case 'behind_dirty':
+        console.log(`  ${shortRemote}: ${yellow(`${result.behind} behind`)} ${dim('(dirty working tree)')}`);
+        break;
+      case 'rebase_failed':
+        console.log(`  ${shortRemote}: ${red('rebase failed')} ${dim(`(${result.behind} behind)`)}`);
+        break;
+      case 'fetch_failed':
+        console.log(`  ${shortRemote}: ${dim('fetch failed (offline?)')}`);
+        break;
+      case 'not_a_repo':
+        console.log(`  ${shortRemote}: ${dim('path is not a git repo')}`);
+        break;
+      default:
+        console.log(`  ${shortRemote}: ${dim(result.status)}`);
+    }
+  }
+
+  console.log();
+}

package/package.json

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