@goodandready/dsh-goal 0.2.1 → 0.2.3

package/lib/command-handler.js

@@ -3,11 +3,9 @@ import { GoalState, detectLanguage } from './goal-engine.js';
 
 export const USAGE_EN = 'Usage: /goal [<goal>|clear|pause|resume]';
 export const USAGE_ZH = '用法: /goal [<目标描述>|clear|pause|resume]';
-export const USAGE_RU = 'Использование: /goal [<цель>|clear|pause|resume]';
-export const USAGE = USAGE_EN;
 
 /**
- * Парсинг строки ввода для команды /goal
+ * Parse input string for /goal command
  * @param {string} rawInput
  * @returns {{ action: string, text?: string }}
  */
@@ -26,7 +24,7 @@ export function parseGoalInput(rawInput = '') {
 }
 
 /**
- * Создание валидного identified сообщения пользователя для отправки агенту через followup
+ * Create a valid identified user message for agent followup
  * @param {string} text
  * @returns {Object}
  */
@@ -40,7 +38,7 @@ export function createGoalUserMessage(text) {
 }
 
 /**
- * Формирование стартового промпта с жестким требованием составить план работ
+ * Format goal start prompt with mandatory milestone contract
  * @param {string} goalText
  * @param {string} [explicitLang]
  * @returns {string}
@@ -55,14 +53,6 @@ export function formatGoalStartPrompt(goalText, explicitLang) {
       `3. 第三步：完成某一步骤后，通过 goal_update_progress(milestone_id, "completed", "阶段简要成果") 标记为已完成。\n` +
       `4. 第四步：当所有里程碑全部完成后，调用 goal_finish(summary) 工具并附带详尽的最终成果总结。`;
   }
-  if (lang === 'ru') {
-    return `🎯 Активирован режим цели (Goal Mode): "${goalText}"\n\n` +
-      `СТРОГИЙ КОНТРАКТ АВТОНОМНОГО РЕЖИМА:\n` +
-      `1. ОБЯЗАТЕЛЬНЫЙ ШАГ №1: Твоим ПЕРВЫМ действием ДО выполнения любой другой работы или ответа должен быть вызов инструмента goal_set_milestones с массивом из 3-7 конкретных, последовательных пунктов плана работ. Пользователь видит этот план в интерфейсе в реальном времени.\n` +
-      `2. ШАГ №2: После установки плана переходи к выполнению шагов. Перед началом работы над каждым шагом отметь его статус как in_progress через goal_update_progress(milestone_id, "in_progress").\n` +
-      `3. ШАГ №3: После успешного завершения шага отметь его статус как completed через goal_update_progress(milestone_id, "completed", "краткие итоги шага").\n` +
-      `4. ШАГ №4: Когда все пункты плана выполнены, вызови инструмент goal_finish(summary) с подробным резюме достигнутых результатов.`;
-  }
 
   return `🎯 Goal Mode activated: "${goalText}"\n\n` +
     `STRICT AUTONOMOUS CONTRACT:\n` +
@@ -73,54 +63,54 @@ export function formatGoalStartPrompt(goalText, explicitLang) {
 }
 
 /**
- * Форматирование текстового ответа для UI и постановка/управление задачей агента
+ * Format response for UI and manage agent task execution
  * @param {import('./goal-engine.js').GoalEngine} engine
  * @param {{ action: string, text?: string }} parsed
  * @param {Object} [config]
  * @param {Object} [agent]
  * @param {string} [sessionId='default']
- * @returns {{ kind: 'success' | 'error', text: string }}
+ * @returns {{ kind: string, text: string }}
  */
 export function executeGoalSlashCommand(engine, parsed, config = {}, agent = null, sessionId = 'default') {
   const sid = sessionId || 'default';
-  const snap = engine.getSnapshot(sid);
-
-  const lang = (parsed.text ? detectLanguage(parsed.text) : (snap.lang || (snap.title ? detectLanguage(snap.title) : 'en'))) || 'en';
-  const isRu = lang === 'ru';
-  const usage = isRu ? USAGE_RU : USAGE_EN;
+  const snap = engine.getGoalSnapshot(sid);
+  const lang = snap.lang || (parsed.text ? detectLanguage(parsed.text) : 'en');
+  const isZh = lang === 'zh';
+  const usage = isZh ? USAGE_ZH : USAGE_EN;
 
   switch (parsed.action) {
     case 'show': {
       if (!snap.hasActiveGoal) {
         return {
           kind: 'success',
-          text: isRu
-            ? `🎯 Режим цели (Goal Mode): цель не установлена.\n${usage}`
-            : `🎯 Goal Mode: no active goal set.\n${usage}`,
+          text: isZh ? `目标模式: 当前未设置活动目标。\n${usage}` : `Goal Mode: no active goal set.\n${usage}`,
         };
       }
 
-      const milestonesInfo = snap.milestones.length > 0
-        ? (isRu ? `\nПлан работ:\n` : `\nWork plan:\n`) + snap.milestones.map((m, i) => `  ${i + 1}. [${m.status}] ${m.title}`).join('\n')
+      const milestonesInfo = snap.milestones && snap.milestones.length > 0
+        ? `\n\n${isZh ? '工作计划' : 'Work Plan'}:\n` +
+          snap.milestones
+            .map((m, i) => `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`)
+            .join('\n')
         : '';
 
       const etaText = snap.formattedETA ? ` (ETA: ${snap.formattedETA})` : '';
       const tokensInfo = (snap.tokensUsage && snap.tokensUsage.totalTokens > 0)
-        ? (isRu
-            ? `\nТокены: ${snap.tokensUsage.totalTokens.toLocaleString()} (in: ${snap.tokensUsage.promptTokens.toLocaleString()}, out: ${snap.tokensUsage.completionTokens.toLocaleString()})`
+        ? (isZh
+            ? `\nToken: ${snap.tokensUsage.totalTokens.toLocaleString()} (输入: ${snap.tokensUsage.promptTokens.toLocaleString()}, 输出: ${snap.tokensUsage.completionTokens.toLocaleString()})`
             : `\nTokens: ${snap.tokensUsage.totalTokens.toLocaleString()} (in: ${snap.tokensUsage.promptTokens.toLocaleString()}, out: ${snap.tokensUsage.completionTokens.toLocaleString()})`)
         : '';
 
       return {
         kind: 'success',
-        text: isRu
-          ? `🎯 Цель: «${snap.title}»\n` +
-            `Статус: ${snap.state}\n` +
-            `Время: ${snap.formattedElapsed}${etaText}\n` +
-            `Итераций: ${snap.iterationsCount}/${snap.maxIterations}` +
+        text: isZh
+          ? `🎯 目标: "${snap.title}"\n` +
+            `状态: ${snap.state}\n` +
+            `耗时: ${snap.formattedElapsed}${etaText}\n` +
+            `迭代轮次: ${snap.iterationsCount}/${snap.maxIterations}` +
             tokensInfo +
             milestonesInfo +
-            `\n\nКоманды: /goal pause, /goal resume, /goal clear, /goal <новая цель>`
+            `\n\n快捷指令: /goal pause, /goal resume, /goal clear, /goal <新目标>`
           : `🎯 Goal: "${snap.title}"\n` +
             `Status: ${snap.state}\n` +
             `Duration: ${snap.formattedElapsed}${etaText}\n` +
@@ -135,7 +125,7 @@ export function executeGoalSlashCommand(engine, parsed, config = {}, agent = nul
       if (!snap.hasActiveGoal) {
         return {
           kind: 'success',
-          text: isRu ? 'Цель не была установлена.' : 'No active goal set.',
+          text: isZh ? '当前未设置目标。' : 'No active goal set.',
         };
       }
       engine.clear(sid);
@@ -143,12 +133,12 @@ export function executeGoalSlashCommand(engine, parsed, config = {}, agent = nul
         try {
           agent.cancel({ kind: 'user', reason: 'Goal cleared by user' });
         } catch (err) {
-          console.warn('[dsh-goal] Failed to cancel agent on clear:', err);
+          // agent cancellation error handled defensively
         }
       }
       return {
         kind: 'success',
-        text: isRu ? '🎯 Цель сброшена.' : '🎯 Goal cleared.',
+        text: isZh ? '🎯 目标已清除。' : '🎯 Goal cleared.',
       };
     }
 
@@ -156,29 +146,29 @@ export function executeGoalSlashCommand(engine, parsed, config = {}, agent = nul
       if (!snap.hasActiveGoal) {
         return {
           kind: 'error',
-          text: isRu
-            ? `Нельзя приостановить: активная цель отсутствует.\n${usage}`
+          text: isZh
+            ? `无法暂停：未设置活动目标。\n${usage}`
             : `Cannot pause: no active goal.\n${usage}`,
         };
       }
       if (snap.state === GoalState.PAUSED) {
         return {
           kind: 'success',
-          text: isRu ? '⏸ Цель уже на паузе.' : '⏸ Goal is already paused.',
+          text: isZh ? '⏸ 目标当前已处于暂停状态。' : '⏸ Goal is already paused.',
         };
       }
-      engine.pause(isRu ? 'Пауза по команде пользователя (/goal pause)' : 'Paused by user command (/goal pause)', sid);
+      engine.pause(isZh ? '用户命令暂停 (/goal pause)' : 'Paused by user command (/goal pause)', sid);
       if (agent && typeof agent.cancel === 'function') {
         try {
           agent.cancel({ kind: 'user', reason: 'Goal paused by user' });
         } catch (err) {
-          console.warn('[dsh-goal] Failed to cancel agent on pause:', err);
+          // agent cancellation error handled defensively
         }
       }
       return {
         kind: 'success',
-        text: isRu
-          ? `⏸ Цель приостановлена: «${snap.title}». Работа агента остановлена. Используйте /goal resume или кнопку ▶️ для продолжения.`
+        text: isZh
+          ? `⏸ 目标已暂停: "${snap.title}"。智能体已停止，使用 /goal resume 或 ▶️ 按钮继续。`
           : `⏸ Goal paused: "${snap.title}". Agent stopped. Use /goal resume or ▶️ button to continue.`,
       };
     }
@@ -187,55 +177,57 @@ export function executeGoalSlashCommand(engine, parsed, config = {}, agent = nul
       if (!snap.hasActiveGoal) {
         return {
           kind: 'error',
-          text: isRu
-            ? `Нельзя возобновить: активная цель отсутствует.\n${usage}`
+          text: isZh
+            ? `无法恢复：未设置活动目标。\n${usage}`
             : `Cannot resume: no active goal.\n${usage}`,
         };
       }
       if (snap.state === GoalState.RUNNING) {
         return {
           kind: 'success',
-          text: isRu ? '▶️ Цель уже выполняется.' : '▶️ Goal is already running.',
+          text: isZh ? '▶️ 目标已在运行中。' : '▶️ Goal is already running.',
         };
       }
       engine.resume(sid);
       if (agent && typeof agent.followup === 'function') {
         try {
-          const resumePrompt = isRu
-            ? `▶️ Цель возобновлена пользователем. Продолжай выполнение плана работ с того места, где остановился. Отмечай шаги через goal_update_progress.`
+          const resumePrompt = isZh
+            ? `▶️ 用户已恢复目标运行。请继续推进工作计划中尚未完成的步骤。通过 goal_update_progress 实时更新进度。`
             : `▶️ Goal resumed by user. Continue executing the work plan from where you stopped. Update steps via goal_update_progress.`;
           agent.followup(createGoalUserMessage(resumePrompt));
         } catch (err) {
-          console.warn('[dsh-goal] Failed to followup agent on resume:', err);
+          // agent followup error handled defensively
         }
       }
       return {
         kind: 'success',
-        text: isRu
-          ? `▶️ Цель возобновлена: «${snap.title}». Агент продолжает работу.`
+        text: isZh
+          ? `▶️ 目标已恢复: "${snap.title}"。智能体继续工作中。`
           : `▶️ Goal resumed: "${snap.title}". Agent continues working.`,
       };
     }
 
     case 'start': {
+      const goalLang = detectLanguage(parsed.text);
+      const isZhStart = goalLang === 'zh';
       const maxIterations = config.maxIterations ?? snap.maxIterations ?? 25;
-      const newSnap = engine.startGoal(parsed.text, { maxIterations, lang }, sid);
+      const cwd = config.cwd;
+      const newSnap = engine.startGoal(parsed.text, { maxIterations, lang: goalLang, cwd }, sid);
 
-      // Если команда вызвана в контексте агента, отправляем цель в очередь модели
       if (agent && typeof agent.followup === 'function') {
         try {
-          const userMsg = createGoalUserMessage(formatGoalStartPrompt(parsed.text, lang));
+          const userMsg = createGoalUserMessage(formatGoalStartPrompt(parsed.text, goalLang));
           agent.followup(userMsg);
         } catch (err) {
-          console.warn('[dsh-goal] Failed to dispatch goal to agent followup:', err);
+          // agent dispatch error handled defensively
         }
       }
 
       return {
         kind: 'success',
-        text: isRu
-          ? `🎯 Активирована цель: «${newSnap.title}» (макс. ${newSnap.maxIterations} итераций).\n` +
-            `Для паузы: /goal pause | Для сброса: /goal clear`
+        text: isZhStart
+          ? `🎯 目标已激活: "${newSnap.title}" (上限 ${newSnap.maxIterations} 轮迭代)。\n` +
+            `暂停: /goal pause | 清除: /goal clear`
           : `🎯 Goal activated: "${newSnap.title}" (max ${newSnap.maxIterations} iterations).\n` +
             `To pause: /goal pause | To clear: /goal clear`,
       };
@@ -244,7 +236,7 @@ export function executeGoalSlashCommand(engine, parsed, config = {}, agent = nul
     default:
       return {
         kind: 'error',
-        text: isRu ? `Неизвестная команда. ${usage}` : `Unknown command. ${usage}`,
+        text: isZh ? `未知指令。${usage}` : `Unknown command. ${usage}`,
       };
   }
 }

package/lib/engine-prompt.js

@@ -0,0 +1,57 @@
+/**
+ * Prompt generation for DSH Goal Mode
+ */
+export function buildStatePromptInjection(snapshot, pendingNudge) {
+  const lang = snapshot.lang || 'en';
+  const hasMilestones = snapshot.milestones && snapshot.milestones.length > 0;
+  const etaText = snapshot.formattedETA ? ` (ETA: ${snapshot.formattedETA})` : '';
+
+  let nudgeText = '';
+  if (pendingNudge) {
+    if (lang === 'zh') {
+      nudgeText = `\n\n🚨 用户紧急补充说明 / 调整方向:\n"${pendingNudge}"\n你必须根据此说明调整近期的具体执行步骤！\n`;
+    } else {
+      nudgeText = `\n\n🚨 URGENT USER CLARIFICATION / STEERING:\n"${pendingNudge}"\nYou must adjust your immediate actions according to this guidance!\n`;
+    }
+  }
+
+  if (lang === 'zh') {
+    const milestonesText = hasMilestones
+      ? snapshot.milestones
+          .map((m, i) => `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`)
+          .join('\n')
+      : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
+
+    return (
+      nudgeText +
+      `\n\n[DSH GOAL MODE ACTIVE]\n` +
+      `目标: "${snapshot.title}"\n` +
+      `运行时间: ${snapshot.formattedElapsed}${etaText} | 迭代轮次: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
+      `工作计划:\n` +
+      `${milestonesText}\n\n` +
+      `Goal Mode 执行契约 (必须严格遵循):\n` +
+      `1. ${hasMilestones ? '按部就班推进当前进行中的里程碑。' : '第一步核心指令: 立即调用 goal_set_milestones 制定 3-7 个具体里程碑。在完成此工具调用前严禁执行其他操作！'}\n` +
+      `2. 推进里程碑时，必须通过 goal_update_progress 工具更新状态（开始前标为 in_progress，完成后标为 completed 并附简要说明）。\n` +
+      `3. 当所有里程碑全部完成后，调用 goal_finish 工具提交详细成果总结。`
+    );
+  }
+
+  const milestonesText = hasMilestones
+    ? snapshot.milestones
+        .map((m, i) => `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`)
+        .join('\n')
+    : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
+
+  return (
+    nudgeText +
+    `\n\n[DSH GOAL MODE ACTIVE]\n` +
+    `Goal: "${snapshot.title}"\n` +
+    `Elapsed Time: ${snapshot.formattedElapsed}${etaText} | Iteration: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
+    `Work Plan:\n` +
+    `${milestonesText}\n\n` +
+    `Goal Mode Instructions (MANDATORY TO FOLLOW):\n` +
+    `1. ${hasMilestones ? 'Execute the current active milestone from the work plan.' : 'YOUR FIRST STEP: Immediately call tool goal_set_milestones with the list of milestones (3-7 concrete steps). You must not execute work or finish turn without calling goal_set_milestones!'}\n` +
+    `2. As each milestone progresses, update its status via tool goal_update_progress (status: "in_progress" before starting, status: "completed" upon completion with brief notes).\n` +
+    `3. When all milestones are completed, call tool goal_finish with a detailed summary of achieved results.`
+  );
+}

package/lib/engine-reports.js

@@ -0,0 +1,114 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Safely get current short git commit hash
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function getGitCurrentCommit(cwd) {
+  try {
+    return execSync('git rev-parse --short HEAD', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000,
+      cwd: cwd || undefined,
+    }).trim();
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Generate Markdown report for goal results
+ * @param {Object} state
+ * @returns {string}
+ */
+export function exportReportMarkdown(state) {
+  if (!state) return '';
+  const title = state.title || 'Goal Report';
+  const status = state.state === 'COMPLETED' ? 'COMPLETED' : state.state;
+  const elapsed = state.formattedElapsed || '0s';
+  const iter = `${state.iterationsCount || 0}/${state.maxIterations || 25}`;
+  const totalTokens = state.tokensUsage?.totalTokens || 0;
+  const promptTokens = state.tokensUsage?.promptTokens || 0;
+  const compTokens = state.tokensUsage?.completionTokens || 0;
+  const gitCommit = state.gitStartCommit ? ` | **Git Start:** \`${state.gitStartCommit}\`` : '';
+
+  let md = `# 🎯 Goal Report: ${title}\n\n`;
+  md += `**Status:** \`${status}\` | **Duration:** \`${elapsed}\` | **Iterations:** \`${iter}\`${gitCommit}\n`;
+  if (totalTokens > 0) {
+    md += `**Tokens:** \`${totalTokens.toLocaleString('en-US')}\` (Prompt: \`${promptTokens.toLocaleString('en-US')}\`, Completion: \`${compTokens.toLocaleString('en-US')}\`)\n`;
+  }
+  md += '\n';
+
+  if (state.description) {
+    md += `### Description\n${state.description}\n\n`;
+  }
+
+  if (state.resultSummary) {
+    md += `### Summary & Deliverables\n${state.resultSummary}\n\n`;
+  }
+
+  const milestones = state.milestones || [];
+  if (milestones.length > 0) {
+    md += `### Milestones\n| # | Status | Title | Notes |\n|---|---|---|---|\n`;
+    milestones.forEach((m, idx) => {
+      const mark = m.status === 'completed' ? '✅ Done' : m.status === 'in_progress' ? '🔄 In Progress' : '⏳ Pending';
+      const cleanTitle = (m.title || '').replace(/\|/g, '\\|');
+      const cleanNotes = (m.notes || '').replace(/\|/g, '\\|');
+      md += `| ${idx + 1} | ${mark} | ${cleanTitle} | ${cleanNotes || '—'} |\n`;
+    });
+    md += '\n';
+  }
+
+  md += `*Generated by DSH Goal Engine at ${new Date().toISOString()}*\n`;
+  return md;
+}
+
+/**
+ * Generate GitHub / Gitea PR comment report with collapsible details
+ * @param {Object} state
+ * @returns {string}
+ */
+export function exportReportGitHubPR(state) {
+  if (!state) return '';
+  const title = state.title || 'Goal Report';
+  const status = state.state === 'COMPLETED' ? 'COMPLETED' : state.state;
+  const elapsed = state.formattedElapsed || '0s';
+  const iter = `${state.iterationsCount || 0}/${state.maxIterations || 25}`;
+  const totalTokens = state.tokensUsage?.totalTokens || 0;
+  const promptTokens = state.tokensUsage?.promptTokens || 0;
+  const compTokens = state.tokensUsage?.completionTokens || 0;
+  const gitCommit = state.gitStartCommit ? `  |  **Git Start:** \`${state.gitStartCommit}\` 📌` : '';
+
+  let md = `## 🎯 Autonomous Goal Resolution: ${title}\n\n`;
+  md += `> **Status:** \`${status}\` 🚀  |  **Duration:** \`${elapsed}\` ⏱️  |  **Iterations:** \`${iter}\` 🔄${gitCommit}\n\n`;
+
+  if (totalTokens > 0) {
+    md += `### 📊 Telemetry & Token Usage\n`;
+    md += `- **Total Tokens:** \`${totalTokens.toLocaleString('en-US')}\` (Prompt: \`${promptTokens.toLocaleString('en-US')}\`, Completion: \`${compTokens.toLocaleString('en-US')}\`)\n\n`;
+  }
+
+  if (state.resultSummary) {
+    md += `### 📦 Deliverables & Achievements\n${state.resultSummary}\n\n`;
+  } else if (state.description) {
+    md += `### 📝 Objective\n${state.description}\n\n`;
+  }
+
+  const milestones = state.milestones || [];
+  if (milestones.length > 0) {
+    const completedCount = milestones.filter((m) => m.status === 'completed').length;
+    md += `<details>\n<summary><b>📋 Milestones Breakdown (${completedCount}/${milestones.length} Completed)</b></summary>\n\n`;
+    md += `| # | Status | Milestone | Notes |\n|---|---|---|---|\n`;
+    milestones.forEach((m, idx) => {
+      const mark = m.status === 'completed' ? '✅ Done' : m.status === 'in_progress' ? '🔄 In Progress' : '⏳ Pending';
+      const cleanTitle = (m.title || '').replace(/\|/g, '\\|');
+      const cleanNotes = (m.notes || '').replace(/\|/g, '\\|');
+      md += `| ${idx + 1} | ${mark} | ${cleanTitle} | ${cleanNotes || '—'} |\n`;
+    });
+    md += `\n</details>\n\n`;
+  }
+
+  md += `*Automated by [@goodandready/dsh-goal](https://github.com/GooDAnDReaDY/dsh-goal)*\n`;
+  return md;
+}

package/lib/engine-store.js

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { GoalState } from './goal-engine-constants.js';
+
+/**
+ * Storage manager for goal engine disk state persistence
+ */
+export class EngineStore {
+  constructor(engine, storagePath) {
+    this.engine = engine;
+    this.storagePath = storagePath || null;
+    this.saveTimer = null;
+  }
+
+  setStoragePath(storagePath) {
+    this.storagePath = storagePath || null;
+  }
+
+  loadStateFromDisk() {
+    if (!this.storagePath) return;
+    try {
+      if (fs.existsSync(this.storagePath)) {
+        const raw = fs.readFileSync(this.storagePath, 'utf8');
+        const data = JSON.parse(raw);
+        if (data && typeof data === 'object') {
+          let dirty = false;
+          if (data.sessions && typeof data.sessions === 'object') {
+            for (const [sid, goal] of Object.entries(data.sessions)) {
+              if (goal && goal.id && goal.title) {
+                // Crash Hydration: transition leftover RUNNING goals to PAUSED
+                if (goal.state === GoalState.RUNNING) {
+                  goal.state = GoalState.PAUSED;
+                  goal.pausedAt = Date.now();
+                  if (!Array.isArray(goal.logs)) goal.logs = [];
+                  goal.logs.push({
+                    timestamp: Date.now(),
+                    type: 'warning',
+                    message: 'Harness was restarted — click ▶️ to resume',
+                  });
+                  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+                  dirty = true;
+                }
+                if (!goal.tokensUsage) {
+                  goal.tokensUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+                }
+                if (!goal.lang) {
+                  goal.lang = 'en';
+                }
+                this.engine.goals.set(sid, goal);
+              }
+            }
+          } else if (data.id && data.title) {
+            if (data.state === GoalState.RUNNING) {
+              data.state = GoalState.PAUSED;
+              data.pausedAt = Date.now();
+              if (!Array.isArray(data.logs)) data.logs = [];
+              data.logs.push({
+                timestamp: Date.now(),
+                type: 'warning',
+                message: 'Harness was restarted — click ▶️ to resume',
+              });
+              if (data.logs.length > 100) data.logs = data.logs.slice(-100);
+              dirty = true;
+            }
+            if (!data.tokensUsage) {
+              data.tokensUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            }
+            if (!data.lang) {
+              data.lang = 'en';
+            }
+            this.engine.goals.set('default', data);
+          }
+          if (dirty) {
+            this.scheduleSave(true);
+          }
+        }
+      }
+    } catch (err) {
+      // best-effort load failure logged defensively
+      console.warn?.('[GoalEngine] Failed to load state from disk:', err?.message || err);
+    }
+  }
+
+  scheduleSave(immediate = false) {
+    if (!this.storagePath) return;
+    if (immediate) {
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
+      this.writeStateToDiskSync();
+      return;
+    }
+    if (!this.saveTimer) {
+      this.saveTimer = setTimeout(() => {
+        this.saveTimer = null;
+        this.writeStateToDiskSync();
+      }, 250);
+      if (typeof this.saveTimer.unref === 'function') {
+        this.saveTimer.unref();
+      }
+    }
+  }
+
+  writeStateToDiskSync() {
+    if (!this.storagePath) return;
+    try {
+      if (this.engine.goals.size === 0) {
+        if (fs.existsSync(this.storagePath)) {
+          fs.unlinkSync(this.storagePath);
+        }
+        return;
+      }
+      const sessionsObj = {};
+      for (const [sid, goal] of this.engine.goals.entries()) {
+        sessionsObj[sid] = goal;
+      }
+      const payload = {
+        version: 2,
+        sessions: sessionsObj,
+        ...(this.engine.goals.has('default') ? this.engine.goals.get('default') : {}),
+      };
+      const dir = path.dirname(this.storagePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      const tmp = `${this.storagePath}.tmp.${Date.now()}`;
+      fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+      fs.renameSync(tmp, this.storagePath);
+    } catch (err) {
+      console.warn?.('[GoalEngine] Failed to write state to disk:', err?.message || err);
+    }
+  }
+
+  flushSync() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.writeStateToDiskSync();
+  }
+}