agentxchain 2.48.0 → 2.50.0

package/bin/agentxchain.js

@@ -107,6 +107,7 @@ import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
 import { historyCommand } from '../src/commands/history.js';
 import { eventsCommand } from '../src/commands/events.js';
+import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -258,6 +259,41 @@ program
   .option('-v, --verbose', 'Show stack traces on failure')
   .action(demoCommand);
 
+const scheduleCmd = program
+  .command('schedule')
+  .description('Run governed schedules for repo-local lights-out execution');
+
+scheduleCmd
+  .command('list')
+  .description('List configured governed schedules and due status')
+  .option('--schedule <id>', 'Show a single schedule')
+  .option('--at <iso8601>', 'Evaluate due status at a fixed time')
+  .option('-j, --json', 'Output as JSON')
+  .action(scheduleListCommand);
+
+scheduleCmd
+  .command('run-due')
+  .description('Execute every due governed schedule once')
+  .option('--schedule <id>', 'Run one configured schedule only')
+  .option('--at <iso8601>', 'Evaluate due status at a fixed time')
+  .option('-j, --json', 'Output as JSON')
+  .action(scheduleRunDueCommand);
+
+scheduleCmd
+  .command('daemon')
+  .description('Poll for due governed schedules and run them locally')
+  .option('--schedule <id>', 'Run one configured schedule only')
+  .option('--poll-seconds <n>', 'Polling interval in seconds', '60')
+  .option('--max-cycles <n>', 'Stop after N cycles (test helper)')
+  .option('-j, --json', 'Output as JSON')
+  .action(scheduleDaemonCommand);
+
+scheduleCmd
+  .command('status')
+  .description('Show daemon health: running, stale, not_running, or never_started')
+  .option('-j, --json', 'Output as JSON')
+  .action(scheduleStatusCommand);
+
 program
   .command('history')
   .description('Show cross-run history of governed runs in this project')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.48.0",
+  "version": "2.50.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/scripts/sync-homebrew.sh

@@ -27,6 +27,18 @@ formula_sha() {
   grep -E '^\s*sha256\s+"' "$formula_path" | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/' || true
 }
 
+canonical_tap_matches_target() {
+  local formula_path="$1"
+  local expected_url="$2"
+  local expected_sha="$3"
+  [[ -f "$formula_path" ]] || return 1
+  local remote_url
+  local remote_sha
+  remote_url="$(formula_url "$formula_path")"
+  remote_sha="$(formula_sha "$formula_path")"
+  [[ "$remote_url" == "$expected_url" && "$remote_sha" == "$expected_sha" ]]
+}
+
 usage() {
   echo "Usage: bash scripts/sync-homebrew.sh --target-version <semver> [--push-tap] [--dry-run]" >&2
 }
@@ -207,10 +219,21 @@ if $PUSH_TAP; then
       git add Formula/agentxchain.rb
       git commit -m "agentxchain ${TARGET_VERSION}"
       if ! git push origin HEAD:main; then
-        echo "FAIL: could not push to ${CANONICAL_TAP_REPO}" >&2
-        exit 1
+        echo "  Push rejected by ${CANONICAL_TAP_REPO}; verifying remote state..."
+        git fetch origin main >/dev/null 2>&1 || true
+        REMOTE_FORMULA="$(mktemp "${TMPDIR:-/tmp}/homebrew-tap-remote-formula.XXXXXX")"
+        if git show origin/main:Formula/agentxchain.rb >"$REMOTE_FORMULA" 2>/dev/null \
+          && canonical_tap_matches_target "$REMOTE_FORMULA" "$TARBALL_URL" "$TARBALL_SHA"; then
+          rm -f "$REMOTE_FORMULA"
+          echo "  Canonical tap already matches target after push rejection — treating sync as complete."
+        else
+          rm -f "$REMOTE_FORMULA"
+          echo "FAIL: could not push to ${CANONICAL_TAP_REPO} and remote tap does not match target artifact" >&2
+          exit 1
+        fi
+      else
+        echo "  Pushed to ${CANONICAL_TAP_REPO}"
       fi
-      echo "  Pushed to ${CANONICAL_TAP_REPO}"
     fi
   )
 

package/src/commands/init.js

@@ -65,6 +65,20 @@ function appendAcceptanceHints(baseMatrix, acceptanceHints) {
   return `${baseMatrix}\n\n## Template Guidance\n${hintLines}\n`;
 }
 
+function findGitRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (existsSync(join(current, '.git'))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
 // ── Governed init ───────────────────────────────────────────────────────────
 
 const GOVERNED_ROLES = {
@@ -950,6 +964,12 @@ async function initGoverned(opts) {
   if (dir !== process.cwd()) {
     console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
   }
+  if (!findGitRoot(dir)) {
+    console.log(`    ${chalk.bold('git init')} ${chalk.dim('# initialize the governed repo')}`);
+  }
+  console.log(`    ${chalk.bold('agentxchain template validate')} ${chalk.dim('# prove the scaffold contract before the first turn')}`);
+  console.log(`    ${chalk.bold('git add -A')} ${chalk.dim('# stage the governed scaffold')}`);
+  console.log(`    ${chalk.bold('git commit -m "initial governed scaffold"')} ${chalk.dim('# checkpoint the starting state')}`);
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');

package/src/commands/run.js

@@ -49,12 +49,18 @@ export async function runCommand(opts) {
     process.exit(1);
   }
 
+  const execution = await executeGovernedRun(context, opts);
+  process.exit(execution.exitCode);
+}
+
+export async function executeGovernedRun(context, opts = {}) {
   const { root, config, rawConfig } = context;
+  const log = opts.log || console.log;
 
   if (config.protocol_mode !== 'governed') {
-    console.log(chalk.red('The run command is only available for governed projects.'));
-    console.log(chalk.dim('Legacy projects use: agentxchain start'));
-    process.exit(1);
+    log(chalk.red('The run command is only available for governed projects.'));
+    log(chalk.dim('Legacy projects use: agentxchain start'));
+    return { exitCode: 1, result: null };
   }
 
   // ── Provenance flag validation ──────────────────────────────────────────
@@ -62,17 +68,21 @@ export async function runCommand(opts) {
   const recoverFrom = opts.recoverFrom;
 
   if (continueFrom && recoverFrom) {
-    console.log(chalk.red('Cannot specify both --continue-from and --recover-from'));
-    process.exit(1);
+    log(chalk.red('Cannot specify both --continue-from and --recover-from'));
+    return { exitCode: 1, result: null };
   }
 
-  let provenance = undefined;
+  let provenance = opts.provenance;
   if (continueFrom || recoverFrom) {
+    if (provenance) {
+      log(chalk.red('Cannot combine internal provenance overrides with --continue-from or --recover-from'));
+      return { exitCode: 1, result: null };
+    }
     const parentId = continueFrom || recoverFrom;
     const validation = validateParentRun(root, parentId);
     if (!validation.ok) {
-      console.log(chalk.red(validation.error));
-      process.exit(1);
+      log(chalk.red(validation.error));
+      return { exitCode: 1, result: null };
     }
     provenance = {
       trigger: continueFrom ? 'continuation' : 'recovery',
@@ -89,21 +99,36 @@ export async function runCommand(opts) {
     : null;
 
   if (overrideResolution?.error) {
-    console.log(chalk.red(overrideResolution.error));
+    log(chalk.red(overrideResolution.error));
     if (overrideResolution.availableRoles.length) {
-      console.log(chalk.dim(`Available roles: ${overrideResolution.availableRoles.join(', ')}`));
+      log(chalk.dim(`Available roles: ${overrideResolution.availableRoles.join(', ')}`));
+    }
+    return { exitCode: 1, result: null };
+  }
+
+  if (opts.requireFreshStart) {
+    const state = loadProjectState(root, config);
+    const allowedStatuses = new Set(opts.allowedFreshStatuses || ['idle', 'completed']);
+    const currentStatus = state?.status || 'missing';
+    if (currentStatus !== 'missing' && !allowedStatuses.has(currentStatus)) {
+      return {
+        exitCode: 0,
+        skipped: true,
+        skipReason: `state_${currentStatus}`,
+        state,
+        result: null,
+      };
     }
-    process.exit(1);
   }
 
   // ── Dry run ───────────────────────────────────────────────────────────────
   if (opts.dryRun) {
     const dryRunState = loadProjectState(root, config);
     const roleId = overrideResolution?.roleId || resolveRole(null, dryRunState, config);
-    console.log(chalk.cyan('Dry run — no execution'));
-    console.log(`  First role:   ${roleId || chalk.dim('(unresolved)')}`);
-    console.log(`  Max turns:    ${maxTurns}`);
-    console.log(`  Gate mode:    ${autoApprove ? 'auto-approve' : 'interactive'}`);
+    log(chalk.cyan('Dry run — no execution'));
+    log(`  First role:   ${roleId || chalk.dim('(unresolved)')}`);
+    log(`  Max turns:    ${maxTurns}`);
+    log(`  Gate mode:    ${autoApprove ? 'auto-approve' : 'interactive'}`);
     const roleIds = Object.keys(config.roles || {});
     for (const rid of roleIds) {
       const role = config.roles[rid];
@@ -111,9 +136,9 @@ export async function runCommand(opts) {
       const rt = config.runtimes?.[rtId];
       const rtType = rt?.type || role.runtime_class || 'manual';
       const supported = rtType !== 'manual';
-      console.log(`  ${supported ? chalk.green('✓') : chalk.red('✗')} ${rid} → ${rtType}${supported ? '' : ' (not supported in run mode)'}`);
+      log(`  ${supported ? chalk.green('✓') : chalk.red('✗')} ${rid} → ${rtType}${supported ? '' : ' (not supported in run mode)'}`);
     }
-    process.exit(0);
+    return { exitCode: 0, result: null };
   }
 
   // ── SIGINT handling ─────────────────────────────────────────────────────
@@ -128,13 +153,13 @@ export async function runCommand(opts) {
     }
     aborted = true;
     controller.abort();
-    console.log(chalk.yellow('\nSIGINT received — finishing current turn, then stopping.'));
+    log(chalk.yellow('\nSIGINT received — finishing current turn, then stopping.'));
   });
 
   // ── Run header ──────────────────────────────────────────────────────────
-  console.log(chalk.cyan.bold('agentxchain run'));
-  console.log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
-  console.log('');
+  log(chalk.cyan.bold('agentxchain run'));
+  log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
+  log('');
 
   // ── Track first-call for --role override ────────────────────────────────
   let firstSelectRole = true;
@@ -165,7 +190,7 @@ export async function runCommand(opts) {
 
       // Manual adapter is not supported in run mode
       if (runtimeType === 'manual') {
-        console.log(chalk.yellow(`Skipping manual role "${roleId}" — use agentxchain step for manual dispatch.`));
+        log(chalk.yellow(`Skipping manual role "${roleId}" — use agentxchain step for manual dispatch.`));
         return { accept: false, reason: 'manual adapter is not supported in run mode — use agentxchain step' };
       }
 
@@ -204,7 +229,7 @@ export async function runCommand(opts) {
       // ── Route to adapter ──────────────────────────────────────────────
       const adapterOpts = {
         signal: controller.signal,
-        onStatus: (msg) => console.log(chalk.dim(`  ${msg}`)),
+        onStatus: (msg) => log(chalk.dim(`  ${msg}`)),
         verifyManifest: true,
       };
 
@@ -216,18 +241,18 @@ export async function runCommand(opts) {
       let adapterResult;
 
       if (runtimeType === 'api_proxy') {
-        console.log(chalk.dim(`  Dispatching to API proxy: ${runtime?.provider || '?'} / ${runtime?.model || '?'}`));
+        log(chalk.dim(`  Dispatching to API proxy: ${runtime?.provider || '?'} / ${runtime?.model || '?'}`));
         adapterResult = await dispatchApiProxy(projectRoot, state, cfg, adapterOpts);
       } else if (runtimeType === 'mcp') {
         const transport = resolveMcpTransport(runtime);
-        console.log(chalk.dim(`  Dispatching to MCP ${transport}: ${describeMcpRuntimeTarget(runtime)}`));
+        log(chalk.dim(`  Dispatching to MCP ${transport}: ${describeMcpRuntimeTarget(runtime)}`));
         adapterResult = await dispatchMcp(projectRoot, state, cfg, adapterOpts);
       } else if (runtimeType === 'local_cli') {
         const transport = runtime ? resolvePromptTransport(runtime) : 'dispatch_bundle_only';
-        console.log(chalk.dim(`  Dispatching to local CLI: ${runtime?.command || '(default)'}  transport: ${transport}`));
+        log(chalk.dim(`  Dispatching to local CLI: ${runtime?.command || '(default)'}  transport: ${transport}`));
         adapterResult = await dispatchLocalCli(projectRoot, state, cfg, adapterOpts);
       } else if (runtimeType === 'remote_agent') {
-        console.log(chalk.dim(`  Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
+        log(chalk.dim(`  Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
         adapterResult = await dispatchRemoteAgent(projectRoot, state, cfg, adapterOpts);
       } else {
         return { accept: false, reason: `unknown runtime type "${runtimeType}"` };
@@ -286,14 +311,14 @@ export async function runCommand(opts) {
 
     async approveGate(gateType, state) {
       if (autoApprove) {
-        console.log(chalk.yellow(`  Auto-approved ${gateType} gate`));
+        log(chalk.yellow(`  Auto-approved ${gateType} gate`));
         return true;
       }
 
       // Non-TTY → fail-closed
       if (!process.stdin.isTTY) {
-        console.log(chalk.yellow(`  Gate pause: ${gateType} — stdin is not a TTY, failing closed.`));
-        console.log(chalk.dim('  Use --auto-approve for non-interactive mode.'));
+        log(chalk.yellow(`  Gate pause: ${gateType} — stdin is not a TTY, failing closed.`));
+        log(chalk.dim('  Use --auto-approve for non-interactive mode.'));
         return false;
       }
 
@@ -301,9 +326,9 @@ export async function runCommand(opts) {
         ? state.pending_phase_transition?.target || '(next phase)'
         : 'run completion';
 
-      console.log('');
-      console.log(chalk.yellow.bold(`Gate pause: ${gateType}`));
-      console.log(chalk.dim(`  Phase: ${state.phase} → ${target}`));
+      log('');
+      log(chalk.yellow.bold(`Gate pause: ${gateType}`));
+      log(chalk.dim(`  Phase: ${state.phase} → ${target}`));
 
       const answer = await promptUser(`  Approve? [y/N] `);
       const approved = /^y(es)?$/i.test(answer.trim());
@@ -313,31 +338,31 @@ export async function runCommand(opts) {
     onEvent(event) {
       switch (event.type) {
         case 'turn_assigned':
-          console.log(chalk.cyan(`Turn assigned: ${event.turn?.turn_id} → ${event.role}`));
+          log(chalk.cyan(`Turn assigned: ${event.turn?.turn_id} → ${event.role}`));
           break;
         case 'turn_accepted':
-          console.log(chalk.green(`Turn accepted: ${event.turn?.turn_id}`));
+          log(chalk.green(`Turn accepted: ${event.turn?.turn_id}`));
           break;
         case 'turn_rejected':
-          console.log(chalk.yellow(`Turn rejected: ${event.turn?.turn_id} — ${event.reason || 'no reason'}`));
+          log(chalk.yellow(`Turn rejected: ${event.turn?.turn_id} — ${event.reason || 'no reason'}`));
           break;
         case 'gate_paused':
-          console.log(chalk.yellow(`Gate paused: ${event.gateType}`));
+          log(chalk.yellow(`Gate paused: ${event.gateType}`));
           break;
         case 'gate_approved':
-          console.log(chalk.green(`Gate approved: ${event.gateType}`));
+          log(chalk.green(`Gate approved: ${event.gateType}`));
           break;
         case 'gate_held':
-          console.log(chalk.yellow(`Gate held: ${event.gateType} — run paused`));
+          log(chalk.yellow(`Gate held: ${event.gateType} — run paused`));
           break;
         case 'blocked':
-          console.log(chalk.red(`Run blocked`));
+          log(chalk.red(`Run blocked`));
           break;
         case 'completed':
-          console.log(chalk.green.bold('Run completed'));
+          log(chalk.green.bold('Run completed'));
           break;
         case 'caller_stopped':
-          console.log(chalk.yellow('Run stopped by caller'));
+          log(chalk.yellow('Run stopped by caller'));
           break;
       }
     },
@@ -347,38 +372,38 @@ export async function runCommand(opts) {
   const runLoopOpts = {
     maxTurns,
     startNewRunFromCompleted: true,
-    startNewRunFromBlocked: Boolean(provenance),
+    startNewRunFromBlocked: opts.allowBlockedRestart ?? Boolean(provenance),
   };
   if (provenance) runLoopOpts.provenance = provenance;
   const result = await runLoop(root, config, callbacks, runLoopOpts);
 
   // ── Summary ─────────────────────────────────────────────────────────────
-  console.log('');
-  console.log(chalk.dim('─── Run Summary ───'));
-  console.log(`  Status:  ${result.ok ? chalk.green('completed') : chalk.yellow(result.stop_reason)}`);
-  console.log(`  Turns:   ${result.turns_executed}`);
-  console.log(`  Gates:   ${result.gates_approved} approved`);
-  console.log(`  Errors:  ${result.errors.length ? chalk.red(result.errors.length) : 'none'}`);
+  log('');
+  log(chalk.dim('─── Run Summary ───'));
+  log(`  Status:  ${result.ok ? chalk.green('completed') : chalk.yellow(result.stop_reason)}`);
+  log(`  Turns:   ${result.turns_executed}`);
+  log(`  Gates:   ${result.gates_approved} approved`);
+  log(`  Errors:  ${result.errors.length ? chalk.red(result.errors.length) : 'none'}`);
 
   if (result.errors.length) {
     for (const err of result.errors) {
-      console.log(chalk.red(`    ${err}`));
+      log(chalk.red(`    ${err}`));
     }
   }
 
   if (qaMissingCredentialsFallback) {
-    printManualQaFallback();
+    printManualQaFallback(log);
   }
 
   // Recovery guidance for blocked/rejected states
   if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
     const recovery = deriveRecoveryDescriptor(result.state);
     if (recovery) {
-      console.log('');
-      console.log(chalk.yellow(`  Recovery: ${recovery.typed_reason}`));
-      console.log(chalk.dim(`  Action:   ${recovery.recovery_action}`));
+      log('');
+      log(chalk.yellow(`  Recovery: ${recovery.typed_reason}`));
+      log(chalk.dim(`  Action:   ${recovery.recovery_action}`));
       if (recovery.detail) {
-        console.log(chalk.dim(`  Detail:   ${recovery.detail}`));
+        log(chalk.dim(`  Detail:   ${recovery.detail}`));
       }
     }
   }
@@ -399,22 +424,25 @@ export async function runCommand(opts) {
         const reportPath = join(reportsDir, `report-${runId}.md`);
         writeFileSync(reportPath, formatGovernanceReportMarkdown(reportResult.report));
 
-        console.log('');
-        console.log(chalk.dim(`  Governance report: .agentxchain/reports/report-${runId}.md`));
+        log('');
+        log(chalk.dim(`  Governance report: .agentxchain/reports/report-${runId}.md`));
       } else {
-        console.log(chalk.dim(`  Governance report skipped: ${exportResult.error}`));
+        log(chalk.dim(`  Governance report skipped: ${exportResult.error}`));
       }
     } catch (err) {
-      console.log(chalk.dim(`  Governance report failed: ${err.message}`));
+      log(chalk.dim(`  Governance report failed: ${err.message}`));
     }
   }
 
   // ── Exit code ───────────────────────────────────────────────────────────
   const successReasons = new Set(['completed', 'gate_held', 'caller_stopped', 'max_turns_reached']);
-  if (result.ok || successReasons.has(result.stop_reason)) {
-    process.exit(0);
-  }
-  process.exit(1);
+  return {
+    exitCode: result.ok || successReasons.has(result.stop_reason) ? 0 : 1,
+    result,
+    skipped: false,
+    skipReason: null,
+    provenance: provenance || null,
+  };
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────
@@ -452,10 +480,10 @@ function shouldPrintManualQaFallback({ roleId, runtimeId, classified, rawConfig
     && rawConfig?.runtimes?.['manual-qa']?.type === 'manual';
 }
 
-function printManualQaFallback() {
-  console.log('');
-  console.log(chalk.dim('  No-key QA fallback:'));
-  console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
-  console.log(chalk.dim('  - Then recover the retained QA turn with: agentxchain step --resume'));
-  console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+function printManualQaFallback(log = console.log) {
+  log('');
+  log(chalk.dim('  No-key QA fallback:'));
+  log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+  log(chalk.dim('  - Then recover the retained QA turn with: agentxchain step --resume'));
+  log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
 }

package/src/commands/schedule.js

@@ -0,0 +1,358 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+import {
+  SCHEDULE_STATE_PATH,
+  DAEMON_STATE_PATH,
+  listSchedules,
+  updateScheduleState,
+  evaluateScheduleLaunchEligibility,
+  readDaemonState,
+  writeDaemonState,
+  updateDaemonHeartbeat,
+  createDaemonState,
+  evaluateDaemonStatus,
+} from '../lib/run-schedule.js';
+import { executeGovernedRun } from './run.js';
+
+function loadScheduleContext() {
+  const context = loadProjectContext();
+  if (!context) {
+    console.error(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exitCode = 1;
+    return null;
+  }
+  if (context.config.protocol_mode !== 'governed') {
+    console.error(chalk.red('The schedule command is only available for governed projects.'));
+    process.exitCode = 1;
+    return null;
+  }
+  return context;
+}
+
+function resolveScheduleEntries(context, scheduleId, at) {
+  const entries = listSchedules(context.root, context.config, { at });
+  if (!scheduleId) {
+    return { ok: true, entries };
+  }
+
+  const matched = entries.find((entry) => entry.id === scheduleId);
+  if (!matched) {
+    return { ok: false, error: `Unknown schedule: ${scheduleId}` };
+  }
+
+  return { ok: true, entries: [matched] };
+}
+
+function printScheduleTable(entries) {
+  if (entries.length === 0) {
+    console.log(chalk.dim('No schedules configured.'));
+    return;
+  }
+
+  const header = [
+    pad('Schedule', 24),
+    pad('Enabled', 8),
+    pad('Every', 8),
+    pad('Due', 6),
+    pad('Next Due', 24),
+    pad('Last Status', 18),
+    pad('Last Run', 14),
+  ].join(' ');
+  console.log(chalk.bold(header));
+  console.log(chalk.dim('─'.repeat(header.length)));
+
+  for (const entry of entries) {
+    console.log([
+      pad(entry.id, 24),
+      pad(entry.enabled ? 'yes' : 'no', 8),
+      pad(`${entry.every_minutes}m`, 8),
+      pad(entry.due ? 'yes' : 'no', 6),
+      pad(entry.next_due_at || '—', 24),
+      pad(entry.last_status || entry.last_skip_reason || '—', 18),
+      pad((entry.last_run_id || '—').slice(0, 12), 14),
+    ].join(' '));
+  }
+}
+
+function pad(value, width) {
+  return String(value || '').padEnd(width);
+}
+
+function buildScheduleProvenance(entry) {
+  return {
+    trigger: 'schedule',
+    created_by: 'operator',
+    trigger_reason: entry.trigger_reason || `schedule:${entry.id}`,
+  };
+}
+
+async function runDueSchedules(context, opts = {}) {
+  const resolved = resolveScheduleEntries(context, opts.schedule, opts.at);
+  if (!resolved.ok) {
+    return { ok: false, exitCode: 1, error: resolved.error, results: [] };
+  }
+
+  const nowIso = opts.at || new Date().toISOString();
+  const results = [];
+
+  for (const entry of resolved.entries) {
+    if (!entry.enabled) {
+      results.push({ id: entry.id, action: 'disabled' });
+      continue;
+    }
+    if (!entry.due) {
+      results.push({ id: entry.id, action: 'not_due', next_due_at: entry.next_due_at });
+      continue;
+    }
+
+    const eligibility = evaluateScheduleLaunchEligibility(context.root, context.config);
+    if (!eligibility.ok) {
+      updateScheduleState(context.root, context.config, entry.id, (record) => ({
+        ...record,
+        last_skip_at: nowIso,
+        last_skip_reason: eligibility.reason,
+      }));
+      results.push({
+        id: entry.id,
+        action: 'skipped',
+        reason: eligibility.reason,
+        project_status: eligibility.status,
+      });
+      continue;
+    }
+
+    if (!opts.json) {
+      console.log(chalk.cyan(`Schedule due: ${entry.id}`));
+    }
+    const execution = await executeGovernedRun(context, {
+      provenance: buildScheduleProvenance(entry),
+      maxTurns: entry.max_turns,
+      autoApprove: entry.auto_approve,
+      role: entry.initial_role || undefined,
+      report: true,
+      allowBlockedRestart: false,
+      requireFreshStart: true,
+      allowedFreshStatuses: ['idle', 'completed'],
+      log: opts.json ? () => {} : console.log,
+    });
+
+    if (execution.skipped) {
+      updateScheduleState(context.root, context.config, entry.id, (record) => ({
+        ...record,
+        last_skip_at: nowIso,
+        last_skip_reason: execution.skipReason,
+      }));
+      results.push({
+        id: entry.id,
+        action: 'skipped',
+        reason: execution.skipReason,
+      });
+      continue;
+    }
+
+    const runId = execution.result?.state?.run_id || null;
+    const startedAt = execution.result?.state?.created_at || nowIso;
+    updateScheduleState(context.root, context.config, entry.id, (record) => ({
+      ...record,
+      last_started_at: startedAt,
+      last_finished_at: new Date().toISOString(),
+      last_run_id: runId,
+      last_status: execution.result?.stop_reason || (execution.exitCode === 0 ? 'completed' : 'launch_failed'),
+      last_skip_at: null,
+      last_skip_reason: null,
+    }));
+    results.push({
+      id: entry.id,
+      action: 'ran',
+      run_id: runId,
+      stop_reason: execution.result?.stop_reason || null,
+      exit_code: execution.exitCode,
+    });
+
+    if (execution.exitCode !== 0) {
+      return { ok: false, exitCode: execution.exitCode, results };
+    }
+  }
+
+  return { ok: true, exitCode: 0, results };
+}
+
+export async function scheduleListCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const resolved = resolveScheduleEntries(context, opts.schedule, opts.at);
+  if (!resolved.ok) {
+    console.error(chalk.red(resolved.error));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      schedules: resolved.entries,
+      state_file: SCHEDULE_STATE_PATH,
+    }, null, 2));
+    return;
+  }
+
+  printScheduleTable(resolved.entries);
+}
+
+export async function scheduleRunDueCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const result = await runDueSchedules(context, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!result.ok) {
+    console.error(chalk.red(result.error || 'Scheduled run failed'));
+  } else if (result.results.length === 0) {
+    console.log(chalk.dim('No schedules configured.'));
+  } else {
+    for (const entry of result.results) {
+      if (entry.action === 'ran') {
+        console.log(chalk.green(`Schedule ran: ${entry.id} (${entry.run_id || 'no run id'})`));
+      } else if (entry.action === 'skipped') {
+        console.log(chalk.yellow(`Schedule skipped: ${entry.id} (${entry.reason})`));
+      } else if (entry.action === 'not_due') {
+        console.log(chalk.dim(`Schedule not due: ${entry.id}`));
+      } else if (entry.action === 'disabled') {
+        console.log(chalk.dim(`Schedule disabled: ${entry.id}`));
+      }
+    }
+  }
+
+  process.exitCode = result.exitCode;
+}
+
+export async function scheduleStatusCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const raw = readDaemonState(context.root);
+  const evaluation = evaluateDaemonStatus(raw);
+
+  if (opts.json) {
+    const output = {
+      ok: evaluation.status === 'running' || evaluation.status === 'never_started',
+      state_file: DAEMON_STATE_PATH,
+      daemon: {
+        status: evaluation.status,
+        pid: raw?.pid ?? null,
+        started_at: raw?.started_at ?? null,
+        last_heartbeat_at: raw?.last_heartbeat_at ?? null,
+        last_cycle_result: raw?.last_cycle_result ?? null,
+        poll_seconds: raw?.poll_seconds ?? null,
+        stale_after_seconds: evaluation.stale_after_seconds ?? null,
+        last_error: raw?.last_error ?? null,
+      },
+    };
+    if (evaluation.warning) output.daemon.warning = evaluation.warning;
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  const statusColors = {
+    running: chalk.green,
+    stale: chalk.yellow,
+    not_running: chalk.red,
+    never_started: chalk.dim,
+  };
+  const colorFn = statusColors[evaluation.status] || chalk.white;
+
+  console.log(chalk.bold('Schedule Daemon Status'));
+  console.log(`  State:     ${colorFn(evaluation.status)}`);
+
+  if (evaluation.status === 'never_started') {
+    console.log(chalk.dim('  No daemon state file found. Run `agentxchain schedule daemon` to start.'));
+    return;
+  }
+
+  if (evaluation.warning) {
+    console.log(chalk.yellow(`  Warning:   ${evaluation.warning}`));
+  }
+
+  if (raw?.pid != null) {
+    console.log(`  PID:       ${raw.pid}`);
+  }
+  if (raw?.started_at) {
+    console.log(`  Started:   ${raw.started_at}`);
+  }
+  if (raw?.last_heartbeat_at) {
+    console.log(`  Heartbeat: ${raw.last_heartbeat_at}`);
+  }
+  if (raw?.last_cycle_result) {
+    const resultColor = raw.last_cycle_result === 'ok' ? chalk.green : chalk.red;
+    console.log(`  Last cycle: ${resultColor(raw.last_cycle_result)}`);
+  }
+  if (raw?.poll_seconds != null) {
+    console.log(`  Poll:      ${raw.poll_seconds}s`);
+  }
+  if (evaluation.status === 'stale') {
+    console.log(chalk.yellow(`  ⚠ Heartbeat is ${evaluation.heartbeat_age_seconds}s old (stale after ${evaluation.stale_after_seconds}s)`));
+  }
+  if (raw?.last_error) {
+    console.log(chalk.red(`  Last error: ${raw.last_error}`));
+  }
+}
+
+export async function scheduleDaemonCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const pollSeconds = Number.parseInt(opts.pollSeconds ?? '60', 10);
+  const maxCycles = opts.maxCycles != null ? Number.parseInt(opts.maxCycles, 10) : null;
+  if (!Number.isInteger(pollSeconds) || pollSeconds < 1) {
+    console.error(chalk.red('--poll-seconds must be an integer >= 1'));
+    process.exitCode = 1;
+    return;
+  }
+  if (maxCycles !== null && (!Number.isInteger(maxCycles) || maxCycles < 1)) {
+    console.error(chalk.red('--max-cycles must be an integer >= 1'));
+    process.exitCode = 1;
+    return;
+  }
+
+  let cycle = 0;
+  const daemonState = createDaemonState(process.pid, pollSeconds, opts.schedule || null, maxCycles);
+
+  try {
+    writeDaemonState(context.root, daemonState);
+  } catch (err) {
+    console.error(chalk.red(`Cannot write daemon state: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!opts.json) {
+    console.log(chalk.bold('AgentXchain Schedule Daemon'));
+    console.log(chalk.dim(`  Poll: ${pollSeconds}s`));
+    console.log(chalk.dim(`  State: ${SCHEDULE_STATE_PATH}`));
+    console.log(chalk.dim(`  Health: ${DAEMON_STATE_PATH}`));
+    console.log('');
+  }
+
+  while (true) {
+    cycle += 1;
+    daemonState.last_cycle_started_at = new Date().toISOString();
+    const result = await runDueSchedules(context, opts);
+
+    updateDaemonHeartbeat(context.root, daemonState, result);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ cycle, ...result }));
+    }
+    if (!result.ok) {
+      process.exitCode = result.exitCode;
+      return;
+    }
+    if (maxCycles !== null && cycle >= maxCycles) {
+      process.exitCode = 0;
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollSeconds * 1000));
+  }
+}

package/src/lib/export.js

@@ -32,6 +32,8 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
   '.agentxchain/events.jsonl',
+  '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -55,6 +57,8 @@ export const RUN_RESTORE_ROOTS = [
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
   '.agentxchain/events.jsonl',
+  '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',

package/src/lib/normalized-config.js

@@ -34,6 +34,7 @@ const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
 export { DEFAULT_PHASES };
 const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_SEMANTIC_IDS = ['pm_signoff', 'system_spec', 'implementation_notes', 'acceptance_matrix', 'ship_verdict', 'release_notes', 'section_check'];
+const VALID_SCHEDULE_ID = /^[a-z0-9_-]+$/;
 
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
 const VALID_API_PROXY_RETRY_CLASSES = [
@@ -508,6 +509,12 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...notificationValidation.errors);
   }
 
+  // Schedules (optional but validated if present)
+  if (data.schedules !== undefined) {
+    const scheduleValidation = validateSchedulesConfig(data.schedules, data.roles);
+    errors.push(...scheduleValidation.errors);
+  }
+
   // Workflow Kit (optional but validated if present)
   if (data.workflow_kit !== undefined) {
     const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing, data.roles);
@@ -534,6 +541,57 @@ export function validateV4Config(data, projectRoot) {
   return { ok: errors.length === 0, errors };
 }
 
+export function validateSchedulesConfig(schedules, roles) {
+  const errors = [];
+
+  if (!schedules || typeof schedules !== 'object' || Array.isArray(schedules)) {
+    errors.push('schedules must be an object');
+    return { ok: false, errors };
+  }
+
+  for (const [scheduleId, schedule] of Object.entries(schedules)) {
+    if (!VALID_SCHEDULE_ID.test(scheduleId)) {
+      errors.push(`Schedule "${scheduleId}" must use lowercase alphanumeric, underscore, or hyphen characters only`);
+      continue;
+    }
+
+    if (!schedule || typeof schedule !== 'object' || Array.isArray(schedule)) {
+      errors.push(`Schedule "${scheduleId}" must be an object`);
+      continue;
+    }
+
+    if (!Number.isInteger(schedule.every_minutes) || schedule.every_minutes < 1) {
+      errors.push(`Schedule "${scheduleId}": every_minutes must be an integer >= 1`);
+    }
+
+    if ('enabled' in schedule && typeof schedule.enabled !== 'boolean') {
+      errors.push(`Schedule "${scheduleId}": enabled must be a boolean`);
+    }
+
+    if ('auto_approve' in schedule && typeof schedule.auto_approve !== 'boolean') {
+      errors.push(`Schedule "${scheduleId}": auto_approve must be a boolean`);
+    }
+
+    if ('max_turns' in schedule && (!Number.isInteger(schedule.max_turns) || schedule.max_turns < 1)) {
+      errors.push(`Schedule "${scheduleId}": max_turns must be an integer >= 1`);
+    }
+
+    if ('trigger_reason' in schedule && (typeof schedule.trigger_reason !== 'string' || !schedule.trigger_reason.trim())) {
+      errors.push(`Schedule "${scheduleId}": trigger_reason must be a non-empty string when provided`);
+    }
+
+    if ('initial_role' in schedule) {
+      if (typeof schedule.initial_role !== 'string' || !schedule.initial_role.trim()) {
+        errors.push(`Schedule "${scheduleId}": initial_role must be a non-empty string when provided`);
+      } else if (roles && !roles[schedule.initial_role]) {
+        errors.push(`Schedule "${scheduleId}": initial_role "${schedule.initial_role}" is not a defined role`);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
 /**
  * Validate the workflow_kit config section.
  * Returns { ok, errors, warnings }.
@@ -850,6 +908,7 @@ export function normalizeV3(raw) {
     gates: {},
     hooks: {},
     notifications: {},
+    schedules: {},
     budget: null,
     policies: [],
     approval_policy: null,
@@ -917,6 +976,7 @@ export function normalizeV4(raw) {
     gates: raw.gates || {},
     hooks: raw.hooks || {},
     notifications: raw.notifications || {},
+    schedules: normalizeSchedules(raw.schedules),
     budget: raw.budget || null,
     policies: normalizePolicies(raw.policies),
     approval_policy: raw.approval_policy || null,
@@ -949,6 +1009,26 @@ export function normalizeV4(raw) {
   };
 }
 
+function normalizeSchedules(rawSchedules) {
+  if (!rawSchedules || typeof rawSchedules !== 'object' || Array.isArray(rawSchedules)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(rawSchedules).map(([scheduleId, schedule]) => [
+      scheduleId,
+      {
+        enabled: schedule?.enabled !== false,
+        every_minutes: schedule?.every_minutes,
+        auto_approve: schedule?.auto_approve !== false,
+        max_turns: schedule?.max_turns ?? 50,
+        initial_role: schedule?.initial_role || null,
+        trigger_reason: schedule?.trigger_reason?.trim() || `schedule:${scheduleId}`,
+      },
+    ]),
+  );
+}
+
 /**
  * Load and normalize a config from raw JSON.
  * Returns { ok, normalized, errors, version }.

package/src/lib/repo-observer.js

@@ -43,6 +43,8 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/run-history.jsonl',
   '.agentxchain/events.jsonl',
   '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
   'TALK.md',
 ];
 

package/src/lib/run-schedule.js

@@ -0,0 +1,227 @@
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { safeWriteJson } from './safe-write.js';
+import { loadProjectState } from './config.js';
+
+export const SCHEDULE_STATE_PATH = '.agentxchain/schedule-state.json';
+export const DAEMON_STATE_PATH = '.agentxchain/schedule-daemon.json';
+const SCHEDULE_STATE_SCHEMA_VERSION = '0.1';
+const DAEMON_STATE_SCHEMA_VERSION = '0.1';
+
+function parseIsoTime(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const ts = Date.parse(value);
+  return Number.isFinite(ts) ? ts : null;
+}
+
+function toIso(value) {
+  return new Date(value).toISOString();
+}
+
+function normalizeScheduleStateRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {
+      last_started_at: null,
+      last_finished_at: null,
+      last_run_id: null,
+      last_status: null,
+      last_skip_at: null,
+      last_skip_reason: null,
+    };
+  }
+
+  return {
+    last_started_at: typeof value.last_started_at === 'string' ? value.last_started_at : null,
+    last_finished_at: typeof value.last_finished_at === 'string' ? value.last_finished_at : null,
+    last_run_id: typeof value.last_run_id === 'string' ? value.last_run_id : null,
+    last_status: typeof value.last_status === 'string' ? value.last_status : null,
+    last_skip_at: typeof value.last_skip_at === 'string' ? value.last_skip_at : null,
+    last_skip_reason: typeof value.last_skip_reason === 'string' ? value.last_skip_reason : null,
+  };
+}
+
+function normalizeScheduleState(value, config) {
+  const schedules = {};
+  const configuredIds = Object.keys(config?.schedules || {});
+  for (const scheduleId of configuredIds) {
+    schedules[scheduleId] = normalizeScheduleStateRecord(value?.schedules?.[scheduleId]);
+  }
+
+  return {
+    schema_version: SCHEDULE_STATE_SCHEMA_VERSION,
+    schedules,
+  };
+}
+
+export function readScheduleState(root, config) {
+  const absPath = join(root, SCHEDULE_STATE_PATH);
+  if (!existsSync(absPath)) {
+    return normalizeScheduleState(null, config);
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(absPath, 'utf8'));
+    return normalizeScheduleState(parsed, config);
+  } catch {
+    return normalizeScheduleState(null, config);
+  }
+}
+
+export function writeScheduleState(root, state) {
+  const absPath = join(root, SCHEDULE_STATE_PATH);
+  mkdirSync(dirname(absPath), { recursive: true });
+  safeWriteJson(absPath, state);
+}
+
+export function updateScheduleState(root, config, scheduleId, updater) {
+  const state = readScheduleState(root, config);
+  const current = normalizeScheduleStateRecord(state.schedules[scheduleId]);
+  state.schedules[scheduleId] = normalizeScheduleStateRecord(updater(current));
+  writeScheduleState(root, state);
+  return state.schedules[scheduleId];
+}
+
+export function computeScheduleStatus(schedule, record, now = Date.now()) {
+  if (schedule.enabled === false) {
+    return {
+      due: false,
+      next_due_at: null,
+      due_reason: 'disabled',
+    };
+  }
+
+  const lastStartedAt = parseIsoTime(record.last_started_at);
+  if (lastStartedAt === null) {
+    return {
+      due: true,
+      next_due_at: toIso(now),
+      due_reason: 'never_started',
+    };
+  }
+
+  const nextDueTs = lastStartedAt + (schedule.every_minutes * 60 * 1000);
+  return {
+    due: now >= nextDueTs,
+    next_due_at: toIso(nextDueTs),
+    due_reason: now >= nextDueTs ? 'interval_elapsed' : 'waiting_interval',
+  };
+}
+
+export function listSchedules(root, config, { at } = {}) {
+  const now = at ? Date.parse(at) : Date.now();
+  const scheduleState = readScheduleState(root, config);
+  const projectState = loadProjectState(root, config);
+  const projectStatus = projectState?.status || 'missing';
+
+  return Object.entries(config?.schedules || {}).map(([scheduleId, schedule]) => {
+    const record = scheduleState.schedules[scheduleId] || normalizeScheduleStateRecord(null);
+    const status = computeScheduleStatus(schedule, record, now);
+    return {
+      id: scheduleId,
+      enabled: schedule.enabled !== false,
+      every_minutes: schedule.every_minutes,
+      auto_approve: schedule.auto_approve !== false,
+      max_turns: schedule.max_turns ?? 50,
+      initial_role: schedule.initial_role || null,
+      trigger_reason: schedule.trigger_reason || `schedule:${scheduleId}`,
+      due: status.due,
+      due_reason: status.due_reason,
+      next_due_at: status.next_due_at,
+      project_status: projectStatus,
+      last_started_at: record.last_started_at,
+      last_finished_at: record.last_finished_at,
+      last_run_id: record.last_run_id,
+      last_status: record.last_status,
+      last_skip_at: record.last_skip_at,
+      last_skip_reason: record.last_skip_reason,
+    };
+  });
+}
+
+export function evaluateScheduleLaunchEligibility(root, config) {
+  const projectState = loadProjectState(root, config);
+  const status = projectState?.status || 'missing';
+
+  if (status === 'missing' || status === 'idle' || status === 'completed') {
+    return { ok: true, status };
+  }
+
+  if (status === 'blocked') {
+    return { ok: false, status, reason: 'run_blocked' };
+  }
+
+  if (status === 'active') {
+    return { ok: false, status, reason: 'run_active' };
+  }
+
+  if (status === 'paused') {
+    return { ok: false, status, reason: 'run_paused' };
+  }
+
+  return { ok: false, status, reason: `run_${status}` };
+}
+
+// ── Daemon Health State ─────────────────────────────────────────────────────
+
+export function readDaemonState(root) {
+  const absPath = join(root, DAEMON_STATE_PATH);
+  if (!existsSync(absPath)) return null;
+  try {
+    return JSON.parse(readFileSync(absPath, 'utf8'));
+  } catch {
+    return { _parse_error: true };
+  }
+}
+
+export function writeDaemonState(root, state) {
+  const absPath = join(root, DAEMON_STATE_PATH);
+  mkdirSync(dirname(absPath), { recursive: true });
+  safeWriteJson(absPath, { schema_version: DAEMON_STATE_SCHEMA_VERSION, ...state });
+}
+
+export function updateDaemonHeartbeat(root, daemonState, cycleResult) {
+  const now = new Date().toISOString();
+  const updated = {
+    ...daemonState,
+    last_heartbeat_at: now,
+    last_cycle_finished_at: now,
+    last_cycle_result: cycleResult.ok ? 'ok' : 'error',
+    last_error: cycleResult.ok ? null : (cycleResult.error || 'cycle failed'),
+  };
+  writeDaemonState(root, updated);
+  return updated;
+}
+
+export function createDaemonState(pid, pollSeconds, scheduleId, maxCycles) {
+  const now = new Date().toISOString();
+  return {
+    pid,
+    started_at: now,
+    last_heartbeat_at: now,
+    last_cycle_started_at: null,
+    last_cycle_finished_at: null,
+    last_cycle_result: null,
+    poll_seconds: pollSeconds,
+    schedule_id: scheduleId || null,
+    max_cycles: maxCycles,
+    last_error: null,
+  };
+}
+
+export function evaluateDaemonStatus(daemonState, now = Date.now()) {
+  if (!daemonState) return { status: 'never_started' };
+  if (daemonState._parse_error) return { status: 'not_running', warning: 'state file is malformed' };
+
+  const heartbeat = parseIsoTime(daemonState.last_heartbeat_at);
+  if (heartbeat === null) return { status: 'not_running', warning: 'no heartbeat recorded' };
+
+  const pollSeconds = typeof daemonState.poll_seconds === 'number' ? daemonState.poll_seconds : 60;
+  const staleAfterSeconds = Math.max(pollSeconds * 3, 30);
+  const ageSeconds = (now - heartbeat) / 1000;
+
+  if (ageSeconds > staleAfterSeconds) {
+    return { status: 'stale', stale_after_seconds: staleAfterSeconds, heartbeat_age_seconds: Math.round(ageSeconds) };
+  }
+
+  return { status: 'running', stale_after_seconds: staleAfterSeconds, heartbeat_age_seconds: Math.round(ageSeconds) };
+}