create-walle 0.9.28 → 0.9.30

package/template/wall-e/loops/tasks.js

@@ -7,10 +7,22 @@ const runtimeHealth = require('../lib/runtime-health');
 const { retryOnWriteLockBusy } = require('../shared/sqlite-write-lock');
 
 const WALL_E_DIR = path.join(__dirname, '..');
+const SLACK_AUTO_RESUME_KV = 'tasks:slack_auto_resume_next_at';
+const DEFAULT_SLACK_AUTO_RESUME_COOLDOWN_MS = 15 * 60 * 1000;
+const DEFAULT_RECURRING_SCHEDULE_REPAIR_INTERVAL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_TASKS_PER_TICK = 1;
+const DEFAULT_MAX_TASK_TICK_MS = 5000;
+const DEFAULT_TASK_CONTINUE_DELAY_MS = 2000;
+const DEFAULT_TASK_MAINTENANCE_MIN_REMAINING_MS = 750;
+const DEFAULT_TASK_EXECUTION_TIMEOUT_MS = 120000;
+const DEFAULT_SCRIPT_TASK_EXECUTION_TIMEOUT_MS = 30000;
+const DEFAULT_TASK_KILL_GRACE_MS = 1500;
+const CALENDAR_ACCESS_QUESTION = 'Calendar access denied — WALL-E cannot sync Calendar until you grant macOS Calendar permission.';
 
 // ── Live log buffer — in-memory, keyed by task ID ──
 const taskLogs = new Map(); // task_id → { lines: string[], startedAt, status }
 const taskProcesses = new Map(); // task_id → child process (for stopping)
+let lastRecurringScheduleRepairMs = 0;
 
 function stopTask(taskId) {
   const child = taskProcesses.get(taskId);
@@ -77,6 +89,137 @@ async function safeUpdateTask(taskId, updates, options = {}) {
   }
 }
 
+function positiveIntEnv(name, fallback) {
+  const n = Number.parseInt(process.env[name] || '', 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function positiveIntValue(value, fallback, max = Number.POSITIVE_INFINITY) {
+  const n = Number.parseInt(String(value || ''), 10);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.min(max, Math.max(1, n));
+}
+
+function nonNegativeIntValue(value, fallback, max = Number.POSITIVE_INFINITY) {
+  const n = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(n) || n < 0) return fallback;
+  return Math.min(max, Math.max(0, n));
+}
+
+function createTaskTimeoutError(task, timeoutMs) {
+  const title = task?.title ? ` "${String(task.title).slice(0, 120)}"` : '';
+  const err = new Error(`Task${title} timed out after ${timeoutMs}ms`);
+  err.code = 'WALL_E_TASK_TIMEOUT';
+  err.timeoutMs = timeoutMs;
+  err.taskId = task?.id || null;
+  err.taskTitle = task?.title || null;
+  return err;
+}
+
+function slackAutoResumeCooldownMs() {
+  return positiveIntEnv('WALL_E_SLACK_AUTO_RESUME_COOLDOWN_MS', DEFAULT_SLACK_AUTO_RESUME_COOLDOWN_MS);
+}
+
+function recurringScheduleRepairIntervalMs() {
+  return positiveIntEnv('WALL_E_RECURRING_TASK_REPAIR_INTERVAL_MS', DEFAULT_RECURRING_SCHEDULE_REPAIR_INTERVAL_MS);
+}
+
+function getSlackAutoResumeNextProbeMs() {
+  try {
+    const raw = brain.getKv(SLACK_AUTO_RESUME_KV);
+    const next = Date.parse(raw || '');
+    return Number.isFinite(next) ? next : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function shouldRunSlackAutoResumeProbe(nowMs = Date.now()) {
+  const nextProbeAt = getSlackAutoResumeNextProbeMs();
+  return !nextProbeAt || nowMs >= nextProbeAt;
+}
+
+function setSlackAutoResumeCooldown(nowMs = Date.now()) {
+  const next = new Date(nowMs + slackAutoResumeCooldownMs()).toISOString();
+  try {
+    brain.setKv(SLACK_AUTO_RESUME_KV, next);
+  } catch (err) {
+    console.warn(`[tasks] Failed to persist Slack auto-resume cooldown: ${err.message}`);
+  }
+  return next;
+}
+
+function clearSlackAutoResumeCooldown() {
+  try {
+    brain.setKv(SLACK_AUTO_RESUME_KV, null);
+  } catch (err) {
+    console.warn(`[tasks] Failed to clear Slack auto-resume cooldown: ${err.message}`);
+  }
+}
+
+function isCalendarAccessDeniedError(task = {}, errMsg = '') {
+  const skill = String(task.skill || '').toLowerCase();
+  const title = String(task.title || '').toLowerCase();
+  const text = String(errMsg || '');
+  const isCalendarTask = skill.includes('calendar') || title.includes('calendar');
+  return isCalendarTask && /access_denied|calendar access(?: (?:was|still))? denied/i.test(text);
+}
+
+function classifyNonRetryableTaskBlocker(task = {}) {
+  if (task.type === 'recurring' && isCalendarAccessDeniedError(task, task.error || '')) {
+    return {
+      type: 'calendar_permission',
+      question: CALENDAR_ACCESS_QUESTION,
+      error: 'Calendar access denied. Grant macOS Calendar access to Wall-E, then resume this task.',
+      instructions: 'Grant Calendar access to the Wall-E/terminal process in System Settings > Privacy & Security > Calendars, then resume the Calendar task.',
+    };
+  }
+  return null;
+}
+
+async function pauseBlockedRecurringTask(task, blocker, reason = 'non-retryable-task-blocker') {
+  if (!task || !blocker) return false;
+  const pausedAt = new Date().toISOString();
+  ensureActionQuestionOnce({
+    question: blocker.question,
+    match: q => String(q.question || '').includes('Calendar access denied'),
+    context: {
+      action: blocker.type,
+      failed_task: task.title,
+      error: task.error || blocker.error,
+      instructions: blocker.instructions,
+    },
+    priority: 'high',
+  });
+  const ok = await safeUpdateTask(task.id, {
+    status: 'paused',
+    error: blocker.error,
+    completed_at: pausedAt,
+    last_run_at: task.last_run_at || pausedAt,
+    next_run_at: null,
+  }, { reason });
+  if (ok) console.log(`[tasks] Auto-paused: ${task.title} (${blocker.type})`);
+  return ok;
+}
+
+function ensureActionQuestionOnce({ question, context, priority = 'high', match }) {
+  try {
+    const existing = brain
+      .listQuestions({ status: 'pending', question_type: 'action_required' })
+      .find(q => typeof match === 'function' ? match(q) : q.question === question);
+    if (existing) return existing;
+    return brain.insertQuestion({
+      question_type: 'action_required',
+      question,
+      context: context ? JSON.stringify(context) : null,
+      priority,
+    });
+  } catch (err) {
+    console.error('[tasks] Failed to create action question:', err.message);
+    return null;
+  }
+}
+
 /**
  * On daemon startup, recover tasks that were interrupted (stuck in 'running').
  * Resets them to 'pending' so they get re-picked up.
@@ -98,6 +241,64 @@ function recoverInterruptedTasks() {
   return stuck.length;
 }
 
+/**
+ * Recurring tasks must have an explicit next_run_at. A null next_run_at on a
+ * recurring task used to make it eligible every scheduler tick, so a blocked
+ * external sync (Calendar/Gmail/Slack) could create a permanent 10s task loop.
+ * Repair the malformed rows on a low-frequency cadence; unparseable schedules
+ * are paused so the UI can surface them instead of spinning silently.
+ */
+async function repairRecurringTaskSchedules(nowMs = Date.now()) {
+  const intervalMs = recurringScheduleRepairIntervalMs();
+  if (intervalMs > 0 && nowMs - lastRecurringScheduleRepairMs < intervalMs) {
+    return { repaired: 0, paused: 0, skipped: true };
+  }
+  lastRecurringScheduleRepairMs = nowMs;
+
+  let rows = [];
+  try {
+    rows = brain.getDb().prepare(`
+      SELECT id, title, schedule
+      FROM tasks
+      WHERE status = 'pending'
+        AND type = 'recurring'
+        AND (next_run_at IS NULL OR trim(next_run_at) = '')
+      ORDER BY updated_at ASC
+      LIMIT 25
+    `).all();
+  } catch (err) {
+    console.warn(`[tasks] Recurring schedule repair skipped: ${err.message}`);
+    return { repaired: 0, paused: 0, error: err.message };
+  }
+
+  let repaired = 0;
+  let paused = 0;
+  for (const row of rows) {
+    const nextRunAt = computeNextDue(row.schedule);
+    if (nextRunAt) {
+      const ok = await safeUpdateTask(row.id, {
+        next_run_at: nextRunAt,
+        error: null,
+      }, { bestEffort: true, reason: 'recurring-schedule-repair' });
+      if (ok) repaired++;
+      continue;
+    }
+
+    const ok = await safeUpdateTask(row.id, {
+      status: 'paused',
+      error: 'Recurring task has no next run time and its schedule could not be parsed. Edit the schedule or run it manually.',
+      completed_at: new Date(nowMs).toISOString(),
+      next_run_at: null,
+    }, { bestEffort: true, reason: 'recurring-schedule-invalid' });
+    if (ok) paused++;
+  }
+
+  if (repaired > 0 || paused > 0) {
+    console.log(`[tasks] Repaired recurring task schedule state: ${repaired} rescheduled, ${paused} paused`);
+  }
+  return { repaired, paused, skipped: false };
+}
+
 /**
  * Try to auto-resume Slack tasks that were paused due to token expiry.
  * Runs at the start of each task loop cycle.
@@ -110,10 +311,22 @@ async function tryResumeSlackTasks() {
       (t.error && t.error.includes('Slack token expired'))
     ));
     if (pausedSlack.length === 0) return;
+    if (!shouldRunSlackAutoResumeProbe()) return;
 
-    // Try refreshing the Slack token
-    const slackMcp = require('../tools/slack-mcp');
-    const valid = await slackMcp.ensureValidToken();
+    // Token refresh can hit network/auth paths. Cool it down persistently so
+    // paused Slack tasks do not make every scheduler tick expensive.
+    setSlackAutoResumeCooldown();
+    const op = runtimeHealth.beginOperation('tasks.slackAutoResumeProbe', { paused: pausedSlack.length });
+    let valid = false;
+    try {
+      const slackMcp = require('../tools/slack-mcp');
+      valid = await slackMcp.ensureValidToken();
+      op.end({ meta: { valid } });
+    } catch (err) {
+      op.end({ ok: false, error: err, meta: { valid: false } });
+      console.warn(`[tasks] Slack auto-resume probe failed; retrying after cooldown: ${err.message}`);
+      return;
+    }
     if (!valid) return;
 
     // Token is valid — un-pause all Slack tasks
@@ -125,23 +338,189 @@ async function tryResumeSlackTasks() {
       }, { reason: 'slack-auto-resume' });
       console.log(`[tasks] Auto-resumed: ${t.title} (Slack token refreshed)`);
     }
-  } catch {}
+    clearSlackAutoResumeCooldown();
+  } catch (err) {
+    console.warn(`[tasks] Slack auto-resume skipped: ${err.message}`);
+  }
 }
 
 /**
  * Task executor loop — picks up due tasks and runs them.
  */
-async function runDueTasks() {
-  // Try to auto-resume Slack tasks paused due to token expiry
-  await tryResumeSlackTasks();
+async function runDueTasks(options = {}) {
+  const maxTasks = positiveIntValue(
+    options.maxTasks ?? process.env.WALL_E_TASKS_MAX_PER_TICK ?? process.env.WALLE_TASKS_MAX_PER_TICK,
+    DEFAULT_MAX_TASKS_PER_TICK,
+    25,
+  );
+  const maxTickMs = positiveIntValue(
+    options.maxTickMs ?? process.env.WALL_E_TASKS_MAX_TICK_MS ?? process.env.WALLE_TASKS_MAX_TICK_MS,
+    DEFAULT_MAX_TASK_TICK_MS,
+    120000,
+  );
+  const continueDelayMs = positiveIntValue(
+    options.continueDelayMs ?? process.env.WALL_E_TASKS_CONTINUE_DELAY_MS ?? process.env.WALLE_TASKS_CONTINUE_DELAY_MS,
+    DEFAULT_TASK_CONTINUE_DELAY_MS,
+    60000,
+  );
+  const maintenanceMinRemainingMs = nonNegativeIntValue(
+    options.maintenanceMinRemainingMs
+      ?? process.env.WALL_E_TASKS_MAINTENANCE_MIN_REMAINING_MS
+      ?? process.env.WALLE_TASKS_MAINTENANCE_MIN_REMAINING_MS,
+    DEFAULT_TASK_MAINTENANCE_MIN_REMAINING_MS,
+    30000,
+  );
+  const taskExecutionTimeoutMs = nonNegativeIntValue(
+    options.taskExecutionTimeoutMs
+      ?? process.env.WALL_E_TASK_EXECUTION_TIMEOUT_MS
+      ?? process.env.WALLE_TASK_EXECUTION_TIMEOUT_MS,
+    DEFAULT_TASK_EXECUTION_TIMEOUT_MS,
+    240000,
+  );
+  const scriptTimeoutFallbackMs = taskExecutionTimeoutMs === 0
+    ? 0
+    : Math.min(taskExecutionTimeoutMs, DEFAULT_SCRIPT_TASK_EXECUTION_TIMEOUT_MS);
+  const scriptTaskExecutionTimeoutMs = nonNegativeIntValue(
+    options.scriptTaskExecutionTimeoutMs
+      ?? process.env.WALL_E_SCRIPT_TASK_EXECUTION_TIMEOUT_MS
+      ?? process.env.WALLE_SCRIPT_TASK_EXECUTION_TIMEOUT_MS,
+    scriptTimeoutFallbackMs,
+    120000,
+  );
+  const chatTaskExecutionTimeoutMs = nonNegativeIntValue(
+    options.chatTaskExecutionTimeoutMs
+      ?? process.env.WALL_E_CHAT_TASK_EXECUTION_TIMEOUT_MS
+      ?? process.env.WALLE_CHAT_TASK_EXECUTION_TIMEOUT_MS,
+    taskExecutionTimeoutMs,
+    240000,
+  );
+  const startedAt = Date.now();
+  const phaseDurations = [];
+  const maintenance = {};
+  const elapsedMs = () => Date.now() - startedAt;
+  const remainingMs = () => Math.max(0, maxTickMs - elapsedMs());
+  const runPhase = async (name, fn, extraMeta = {}) => {
+    const phaseStart = Date.now();
+    try {
+      const value = await fn();
+      const durationMs = Date.now() - phaseStart;
+      phaseDurations.push({ name, durationMs, ok: true, ...extraMeta });
+      runtimeHealth.recordOperation(`tasks.phase.${name}`, durationMs, {
+        meta: { remainingMs: remainingMs(), maxTickMs, ...extraMeta },
+      });
+      return value;
+    } catch (err) {
+      const durationMs = Date.now() - phaseStart;
+      phaseDurations.push({
+        name,
+        durationMs,
+        ok: false,
+        error: String(err?.message || err).slice(0, 120),
+        ...extraMeta,
+      });
+      runtimeHealth.recordOperation(`tasks.phase.${name}`, durationMs, {
+        ok: false,
+        error: err?.code || err?.name || 'error',
+        meta: { remainingMs: remainingMs(), maxTickMs, ...extraMeta },
+      });
+      throw err;
+    }
+  };
+
+  if (options.runMaintenance !== false) {
+    maintenance.repair = await runPhase(
+      'maintenance.repairRecurringSchedules',
+      () => repairRecurringTaskSchedules(),
+    );
+
+    if (remainingMs() >= maintenanceMinRemainingMs) {
+      maintenance.slackAutoResume = await runPhase(
+        'maintenance.slackAutoResume',
+        () => tryResumeSlackTasks(),
+      );
+    } else {
+      maintenance.slackAutoResume = { skipped: true, reason: 'tick_budget_low' };
+      phaseDurations.push({
+        name: 'maintenance.slackAutoResume',
+        durationMs: 0,
+        ok: true,
+        skipped: true,
+        reason: 'tick_budget_low',
+      });
+    }
+  }
+
+  if (elapsedMs() >= maxTickMs) {
+    return {
+      processed: 0,
+      reconciled: 0,
+      considered: 0,
+      fetched: 0,
+      maxTasks,
+      maxTickMs,
+      taskExecutionTimeoutMs,
+      scriptTaskExecutionTimeoutMs,
+      chatTaskExecutionTimeoutMs,
+      maintenance,
+      phaseDurations,
+      budgetExhausted: true,
+      _continue: true,
+      _continueDelayMs: continueDelayMs,
+    };
+  }
+
+  const fetched = await runPhase('scanDueTasks', () => brain.getDueTasks({ limit: maxTasks + 1 }));
+  if (fetched.length === 0) {
+    return {
+      processed: 0,
+      reconciled: 0,
+      considered: 0,
+      fetched: 0,
+      maxTasks,
+      maxTickMs,
+      taskExecutionTimeoutMs,
+      scriptTaskExecutionTimeoutMs,
+      chatTaskExecutionTimeoutMs,
+      maintenance,
+      phaseDurations,
+      budgetExhausted: false,
+      _continue: false,
+    };
+  }
 
-  const tasks = brain.getDueTasks();
-  if (tasks.length === 0) return { processed: 0 };
+  const tasks = fetched.slice(0, maxTasks);
+  const hadMore = fetched.length > maxTasks;
 
   let processed = 0;
+  let reconciled = 0;
+  let budgetExhausted = false;
   for (const task of tasks) {
+    if (elapsedMs() >= maxTickMs && (processed > 0 || reconciled > 0)) {
+      budgetExhausted = true;
+      break;
+    }
+
+    const taskPhaseStart = Date.now();
+    const taskPhase = {
+      name: `task.${task.execution || (task.skill ? 'skill' : 'chat')}`,
+      durationMs: 0,
+      ok: true,
+      taskId: task.id,
+      taskType: task.type || '',
+    };
+
     if (task.status === 'running') continue;
 
+    const blocker = classifyNonRetryableTaskBlocker(task);
+    if (blocker) {
+      await pauseBlockedRecurringTask(task, blocker, 'stored-task-blocker-reconcile');
+      reconciled++;
+      taskPhase.name = 'task.reconcileBlocked';
+      taskPhase.durationMs = Date.now() - taskPhaseStart;
+      phaseDurations.push(taskPhase);
+      continue;
+    }
+
     const now = new Date().toISOString();
     const hasCheckpoint = task.checkpoint ? ' (resuming from checkpoint)' : '';
     await safeUpdateTask(task.id, { status: 'running', started_at: now }, { reason: 'task-start' });
@@ -151,11 +530,18 @@ async function runDueTasks() {
       let resultText;
 
       if (task.skill) {
-        resultText = await executeSkill(task.id, task);
+        resultText = await executeSkill(task.id, task, {
+          timeoutMs: taskExecutionTimeoutMs,
+          scriptTimeoutMs: scriptTaskExecutionTimeoutMs,
+          chatTimeoutMs: chatTaskExecutionTimeoutMs,
+        });
       } else if (task.execution === 'script' && task.script) {
-        resultText = await executeScript(task.id, task.script, task.checkpoint);
+        resultText = await executeScript(task.id, task.script, task.checkpoint, null, {
+          timeoutMs: scriptTaskExecutionTimeoutMs,
+          taskTitle: task.title,
+        });
       } else {
-        resultText = await executeChat(task.id, task);
+        resultText = await executeChat(task.id, task, { timeoutMs: chatTaskExecutionTimeoutMs });
       }
 
       const completedAt = new Date().toISOString();
@@ -230,7 +616,13 @@ async function runDueTasks() {
 
       processed++;
       console.log(`[tasks] Completed: ${task.title} (${task.execution || 'chat'})`);
+      taskPhase.durationMs = Date.now() - taskPhaseStart;
+      phaseDurations.push(taskPhase);
     } catch (err) {
+      taskPhase.ok = false;
+      taskPhase.durationMs = Date.now() - taskPhaseStart;
+      taskPhase.error = String(err?.message || err).slice(0, 120);
+      phaseDurations.push(taskPhase);
       console.error('[tasks] Failed:', task.title, err.message);
       appendLog(task.id, `[ERROR] ${err.message}`);
 
@@ -252,6 +644,7 @@ async function runDueTasks() {
       // Detect actionable errors and create pending questions
       const errMsg = err.message || '';
       const isSlackAuth = errMsg.includes('Slack token expired') || errMsg.includes('invalid_auth') || errMsg.includes('401') || errMsg.includes('not authenticated');
+      const isCalendarDenied = isCalendarAccessDeniedError(task, errMsg);
 
       // For Slack auth errors, try auto-refresh before pausing
       let slackRefreshSucceeded = false;
@@ -301,6 +694,22 @@ async function runDueTasks() {
         }
       }
 
+      if (isCalendarDenied && task.type === 'recurring') {
+        await pauseBlockedRecurringTask({
+          ...task,
+          error: errMsg,
+          last_run_at: new Date().toISOString(),
+        }, classifyNonRetryableTaskBlocker({
+          ...task,
+          error: errMsg,
+        }), 'calendar-access-denied-pause');
+        await safeUpdateTask(task.id, {
+          run_count: (task.run_count || 0) + 1,
+        }, { bestEffort: true, reason: 'calendar-access-denied-count' });
+        appendLog(task.id, 'Paused recurring task until Calendar access is granted.');
+        continue;
+      }
+
       await safeUpdateTask(task.id, {
         status: task.type === 'recurring' ? 'pending' : 'failed',
         error: isSlackAuth
@@ -319,12 +728,28 @@ async function runDueTasks() {
     }
   }
 
-  return { processed };
+  const shouldContinue = hadMore || budgetExhausted;
+  return {
+    processed,
+    reconciled,
+    considered: tasks.length,
+    fetched: fetched.length,
+    maxTasks,
+    maxTickMs,
+    taskExecutionTimeoutMs,
+    scriptTaskExecutionTimeoutMs,
+    chatTaskExecutionTimeoutMs,
+    maintenance,
+    phaseDurations,
+    budgetExhausted,
+    _continue: shouldContinue,
+    ...(shouldContinue ? { _continueDelayMs: continueDelayMs } : {}),
+  };
 }
 
 // ── Skill execution ──
 
-async function executeSkill(taskId, task) {
+async function executeSkill(taskId, task, options = {}) {
   const skill = findSkill(task.skill);
   if (!skill) throw new Error(`Skill "${task.skill}" not found`);
 
@@ -334,6 +759,8 @@ async function executeSkill(taskId, task) {
     const { runScriptSkill } = require('../skills/script-skill-runner');
     return runScriptSkill(skill, task, {
       log: line => appendLog(taskId, line),
+      timeoutMs: options.scriptTimeoutMs ?? options.timeoutMs,
+      killGraceMs: options.killGraceMs,
       onCheckpoint: checkpoint => {
         void safeUpdateTask(taskId, { checkpoint }, {
           bestEffort: true,
@@ -355,7 +782,10 @@ async function executeSkill(taskId, task) {
       description: skill.instructions || skill.description,
     };
     appendLog(taskId, `Agent skill: sending instructions to Claude...`);
-    return executeChat(taskId, agentTask);
+    return executeChat(taskId, agentTask, {
+      ...options,
+      timeoutMs: options.chatTimeoutMs ?? options.timeoutMs,
+    });
   }
 
   throw new Error(`Unknown skill execution mode: ${skill.execution}`);
@@ -363,7 +793,7 @@ async function executeSkill(taskId, task) {
 
 // ── Script execution with live log streaming ──
 
-function executeScript(taskId, script, checkpoint, extraEnv) {
+function executeScript(taskId, script, checkpoint, extraEnv, options = {}) {
   return new Promise((resolve, reject) => {
     // Pass checkpoint as env var so scripts can resume from where they left off
     const env = { ...process.env, HOME: process.env.HOME };
@@ -379,7 +809,37 @@ function executeScript(taskId, script, checkpoint, extraEnv) {
 
     let stdout = '';
     let stderr = '';
-    // No timeout — tasks run until completion. User can stop via UI.
+    let timedOut = false;
+    let settled = false;
+    let timeoutTimer = null;
+    let killTimer = null;
+    const timeoutMs = nonNegativeIntValue(options.timeoutMs, 0, 240000);
+    const killGraceMs = nonNegativeIntValue(options.killGraceMs, DEFAULT_TASK_KILL_GRACE_MS, 10000);
+    const clearTimers = () => {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      timeoutTimer = null;
+      killTimer = null;
+    };
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      taskProcesses.delete(taskId);
+      fn(value);
+    };
+    if (timeoutMs > 0) {
+      timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        appendLog(taskId, `[timeout] Task exceeded ${timeoutMs}ms; stopping script process...`);
+        try { child.kill('SIGTERM'); } catch {}
+        killTimer = setTimeout(() => {
+          try { child.kill('SIGKILL'); } catch {}
+        }, killGraceMs);
+        killTimer.unref?.();
+      }, timeoutMs);
+      timeoutTimer.unref?.();
+    }
 
     child.stdout.on('data', (chunk) => {
       const text = chunk.toString();
@@ -405,28 +865,31 @@ function executeScript(taskId, script, checkpoint, extraEnv) {
     });
 
     child.on('close', (code) => {
-      taskProcesses.delete(taskId);
+      if (timedOut) {
+        finish(reject, createTaskTimeoutError({ id: taskId, title: options.taskTitle || 'script task' }, timeoutMs));
+        return;
+      }
       if (code !== 0 && code !== null) {
-        reject(new Error(`Exit code ${code}: ${stderr.slice(0, 500)}`));
+        finish(reject, new Error(`Exit code ${code}: ${stderr.slice(0, 500)}`));
       } else {
         let output = stdout.trim();
         if (stderr.trim()) output += '\n[stderr] ' + stderr.trim();
-        resolve(output);
+        finish(resolve, output);
       }
     });
 
     child.on('error', (err) => {
-      reject(err);
+      finish(reject, err);
     });
   });
 }
 
 // ── Chat execution with log streaming ──
 
-async function executeChat(taskId, task) {
+async function executeChat(taskId, task, options = {}) {
   // Use multi-turn for complex tasks
   if (task.execution === 'multi-turn') {
-    return executeMultiTurnChat(taskId, task);
+    return executeMultiTurnChat(taskId, task, options);
   }
 
   // Single-turn (existing behavior)
@@ -438,6 +901,8 @@ async function executeChat(taskId, task) {
   const result = await chatModule.chat(prompt, {
     channel: 'task',
     session_id: `task-${task.id}`,
+    ...(options.timeoutMs > 0 ? { timeoutMs: options.timeoutMs } : {}),
+    ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
     onProgress: (event) => {
       if (event.type === 'tool_call') appendLog(taskId, event.summary);
       else if (event.type === 'tool_done') appendLog(taskId, `Done: ${event.summary}`);
@@ -452,13 +917,19 @@ async function executeChat(taskId, task) {
  * Execute a task using multiple chat turns, maintaining session state.
  * Each turn can use tools, and progress is checkpointed between turns.
  */
-async function executeMultiTurnChat(taskId, task) {
+async function executeMultiTurnChat(taskId, task, options = {}) {
   const chatModule = require('../chat');
   const sessionId = `task-${task.id}`;
   const MAX_TASK_TURNS = 5;
+  const timeoutMs = nonNegativeIntValue(options.timeoutMs, 0, 240000);
+  const deadlineMs = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
   let lastReply = '';
 
   for (let turn = 0; turn < MAX_TASK_TURNS; turn++) {
+    const remainingMs = deadlineMs > 0 ? deadlineMs - Date.now() : 0;
+    if (deadlineMs > 0 && remainingMs <= 0) {
+      throw createTaskTimeoutError(task, timeoutMs);
+    }
     const prompt = turn === 0
       ? buildTaskPrompt(task)
       : 'Continue working on this task. Review your progress so far and take the next step. If you are done, include [TASK COMPLETE] in your response.';
@@ -468,6 +939,8 @@ async function executeMultiTurnChat(taskId, task) {
     const result = await chatModule.chat(prompt, {
       channel: 'task',
       session_id: sessionId,
+      ...(remainingMs > 0 ? { timeoutMs: remainingMs } : {}),
+      ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
       onProgress: (event) => {
         if (event.type === 'tool_call') appendLog(taskId, event.summary);
         else if (event.type === 'tool_done') appendLog(taskId, `Done: ${event.summary}`);
@@ -762,4 +1235,27 @@ async function retrySlackDelivery(task, resultText) {
   }
 }
 
-module.exports = { runDueTasks, runTaskById, recoverInterruptedTasks, buildTaskPrompt, computeNextDue, getTaskLogs, clearTaskLogs, stopTask, executeSkill, executeMultiTurnChat, consolidateBriefingItems, taskLogs };
+module.exports = {
+  runDueTasks,
+  runTaskById,
+  recoverInterruptedTasks,
+  buildTaskPrompt,
+  computeNextDue,
+  getTaskLogs,
+  clearTaskLogs,
+  stopTask,
+  executeSkill,
+  executeMultiTurnChat,
+  consolidateBriefingItems,
+  taskLogs,
+  _internals: {
+    isCalendarAccessDeniedError,
+    repairRecurringTaskSchedules,
+    tryResumeSlackTasks,
+    shouldRunSlackAutoResumeProbe,
+    setSlackAutoResumeCooldown,
+    clearSlackAutoResumeCooldown,
+    positiveIntValue,
+    nonNegativeIntValue,
+  },
+};