@goodandready/dsh-goal 0.2.11 → 0.2.13

package/lib/index.js

@@ -1,14 +1,19 @@
 import path from 'node:path';
 import os from 'node:os';
 import z from '@deepseek-ai/schemastery';
-import { GoalEngine, GoalState, detectLanguage, sessionIdOf } from './goal-engine.js';
-import { parseGoalInput, executeGoalSlashCommand, createGoalUserMessage } from './command-handler.js';
+import { AddonStore } from './addon-store.js';
+import { TokenBudgetGuard } from './token-budget-guard.js';
+import { GitSnapshotManager } from './git-snapshot-manager.js';
+import { MilestoneManager } from './milestone-manager.js';
 import { registerRoutes } from './routes.js';
 import { registerTools } from './tools.js';
+import { saveGoalReportFile } from './engine-reports.js';
 import { registerPluginUpdater } from './updater.js';
+import { GoalEngine, GoalState } from './goal-engine.js';
+import { sessionIdOf } from './goal-engine-constants.js';
 
 export const name = '@goodandready/dsh-goal';
-export const inject = ['webServer', 'settings'];
+export const inject = ['webServer', 'settings', 'goals?'];
 
 const NS = 'dsh-goal';
 
@@ -36,10 +41,6 @@ export const Config = z.object({
 
 export function apply(ctx, config = {}) {
   let settingsScope = null;
-  let agentsService = null;
-  const runningAgents = new Set();
-  const sessionAgents = new Map();
-  let lastActiveAgent = null;
   const sseClients = new Map();
 
   let currentSettings = {
@@ -65,430 +66,250 @@ export function apply(ctx, config = {}) {
   };
 
   const defaultStorageDir = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
-  const storagePath = currentSettings.storagePath !== undefined && currentSettings.storagePath !== null
-    ? currentSettings.storagePath
-    : path.join(defaultStorageDir, 'dsh-goal-state.json');
-
-  const engine = new GoalEngine({
-    defaultMaxIterations: currentSettings.maxIterations,
-    autoDrive: currentSettings.autoDrive,
-    enableSound: currentSettings.enableSound,
-    showQuickLaunchButton: currentSettings.showQuickLaunchButton,
-    consecutiveToolFailureLimit: currentSettings.consecutiveToolFailureLimit,
+  const customStorage = typeof currentSettings.storagePath === 'string' && currentSettings.storagePath.trim()
+    ? currentSettings.storagePath.trim()
+    : null;
+  const isTest = process.env.NODE_ENV === 'test' || Boolean(process.env.NODE_TEST_CONTEXT);
+  const storagePath = customStorage || (isTest ? null : path.join(defaultStorageDir, 'dsh-goal-state.json'));
+  const logger = ctx.logger ? ctx.logger('goal') : console;
+
+  // Initialize addon modules
+  const addonStore = new AddonStore(storagePath, logger);
+  const gitSnapshotManager = new GitSnapshotManager(addonStore, { logger });
+  const milestoneManager = new MilestoneManager(addonStore, {
+    gitSnapshotManager,
+    enforceDependencies: currentSettings.enableMilestoneDependencies,
+    logger,
+  });
+  const tokenBudgetGuard = new TokenBudgetGuard({
     maxTokenBudget: currentSettings.maxTokenBudget,
-    budgetWarningThreshold: currentSettings.budgetWarningThreshold,
-    autoCheckpointOnMilestone: currentSettings.autoCheckpointOnMilestone,
-    enableLiveActivityFeed: currentSettings.enableLiveActivityFeed,
-    enablePreplanning: currentSettings.enablePreplanning,
-    autoBranchOnGoalStart: currentSettings.autoBranchOnGoalStart,
-    enablePostGoalRetrospective: currentSettings.enablePostGoalRetrospective,
-    autoScaleBudgetNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
-    enableTemplatesDrawer: currentSettings.enableTemplatesDrawer,
-    enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
-    soundScheme: currentSettings.soundScheme,
-    enableVoiceAnnouncements: currentSettings.enableVoiceAnnouncements,
-    storagePath,
+    warningThreshold: currentSettings.budgetWarningThreshold,
+    autoScaleNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
+    logger,
   });
 
-  // Track running agents through global DSH core event
-  ctx.inject(['agents'], (actx) => {
-    agentsService = actx.agents;
-  });
+  // Attempt migration of legacy state if present
+  try {
+    const firstAgent = ctx.agents?.get?.(ctx.agents?.keys?.()?.next()?.value);
+    addonStore.migrateLegacyState(storagePath, ctx.goals, firstAgent);
+  } catch (migErr) {
+    logger.warn?.('[dsh-goal] Legacy migration check failed:', migErr.message);
+  }
 
-  ctx.on?.('agent/status', ({ agent, status }) => {
-    if (status === 'running') {
-      runningAgents.add(agent);
-      lastActiveAgent = agent;
-      const sid = sessionIdOf(agent, null);
-      if (sid) {
-        sessionAgents.set(sid, agent);
-      }
-    } else {
-      runningAgents.delete(agent);
-      if (lastActiveAgent === agent && (status === 'stopped' || status === 'completed' || status === 'error')) {
-        lastActiveAgent = null;
-      }
-      const sid = sessionIdOf(agent, null);
-      if (sid && sessionAgents.get(sid) === agent && (status === 'stopped' || status === 'completed' || status === 'error')) {
-        sessionAgents.delete(sid);
-      }
-    }
+  // Register addon tools: goal_milestones and goal_checklist
+  registerTools(ctx, {
+    milestoneManager,
+    goalsService: ctx.goals,
+    logger,
   });
 
-  const stopRunningAgents = (sessionId = 'default') => {
-    const sid = sessionId || 'default';
-    const specificAgent = sessionAgents.get(sid);
-    if (specificAgent && typeof specificAgent.cancel === 'function') {
-      try {
-        specificAgent.cancel({ kind: 'user' });
-      } catch (err) {
-        console.warn('[dsh-goal] Failed to cancel specific agent for session:', err);
-      }
-    }
-
-    for (const ag of runningAgents) {
-      try {
-        const agSid = sessionIdOf(ag, null);
-        if (!agSid || agSid === sid || sid === 'default') {
-          if (typeof ag.cancel === 'function') {
-            ag.cancel({ kind: 'user' });
-          }
-        }
-      } catch (err) {
-        console.warn('[dsh-goal] Failed to cancel running agent:', err);
-      }
-    }
+  // Support fallback engine for tests or non-core environments
+  let fallbackEngine = null;
+  if (!ctx.goals) {
+    fallbackEngine = new GoalEngine({
+      storagePath,
+      defaultMaxIterations: currentSettings.maxIterations,
+      autoDrive: currentSettings.autoDrive,
+      consecutiveToolFailureLimit: currentSettings.consecutiveToolFailureLimit,
+      maxTokenBudget: currentSettings.maxTokenBudget,
+      budgetWarningThreshold: currentSettings.budgetWarningThreshold,
+      autoCheckpointOnMilestone: currentSettings.autoCheckpointOnMilestone,
+      enableLiveActivityFeed: currentSettings.enableLiveActivityFeed,
+      enablePreplanning: currentSettings.enablePreplanning,
+      autoBranchOnGoalStart: currentSettings.autoBranchOnGoalStart,
+      enablePostGoalRetrospective: currentSettings.enablePostGoalRetrospective,
+      autoScaleBudgetNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
+      enableTemplatesDrawer: currentSettings.enableTemplatesDrawer,
+      enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
+    });
+  }
 
-    if (lastActiveAgent && lastActiveAgent.status === 'running' && typeof lastActiveAgent.cancel === 'function') {
-      const lastSid = sessionIdOf(lastActiveAgent, null);
-      if (!lastSid || lastSid === sid || sid === 'default') {
+  // 1. One-click auto-updater registration (Issue #99)
+  if (ctx?.webServer?.register) {
+    if (typeof ctx?.effect === 'function') {
+      ctx.effect(() => {
+        let unreg = null;
         try {
-          lastActiveAgent.cancel({ kind: 'user' });
+          unreg = registerPluginUpdater(ctx, {
+            packageName: '@goodandready/dsh-goal',
+            endpoint: '/api/dsh-goal/update',
+            manifestUrl: new URL('../package.json', import.meta.url),
+          });
         } catch (err) {
-          console.warn('[dsh-goal] Failed to cancel lastActiveAgent:', err);
-        }
-      }
-    }
-  };
-
-  const resumeActiveAgent = (promptText, sessionId = 'default') => {
-    const sid = sessionId || 'default';
-    const snap = engine.getSnapshot(sid);
-    const lang = snap.lang || (snap.title ? detectLanguage(snap.title) : 'en');
-    const defaultResumePrompt = lang === 'zh'
-      ? '▶️ 用户已恢复目标。请继续执行工作计划，并通过 goal_update_progress 更新进度。'
-      : '▶️ Goal resumed by user. Continue executing the work plan from where you stopped. Update steps via goal_update_progress.';
-
-    const resumeMsg = createGoalUserMessage(promptText || defaultResumePrompt);
-
-    let target = sessionAgents.get(sid);
-    if (!target && lastActiveAgent && typeof lastActiveAgent.followup === 'function') {
-      const lastSid = sessionIdOf(lastActiveAgent, null);
-      if (!lastSid || lastSid === sid || sid === 'default') {
-        target = lastActiveAgent;
-      }
-    }
-
-    if (!target && agentsService && typeof agentsService.list === 'function') {
-      const list = agentsService.list();
-      if (list && list.length > 0) {
-        for (let i = list.length - 1; i >= 0; i--) {
-          const cand = list[i];
-          const candSid = sessionIdOf(cand, null);
-          if (candSid === sid) {
-            target = cand;
-            break;
-          }
-        }
-        if (!target && sid === 'default') {
-          target = list[list.length - 1];
-        }
-      }
-    }
-
-    if (target && typeof target.followup === 'function') {
-      try {
-        target.followup(resumeMsg);
-        lastActiveAgent = target;
-        sessionAgents.set(sid, target);
-        return true;
-      } catch (err) {
-        console.warn('[dsh-goal] Failed to resume agent:', err);
-      }
-    }
-    return false;
-  };
-
-  const getConfig = () => {
-    if (settingsScope) {
-      const snap = typeof settingsScope.getSnapshot === 'function' ? settingsScope.getSnapshot() : null;
-      let live = null;
-      if (snap) {
-        if (snap.status === 'ready' || snap.status === 'writable' || snap.status === undefined) {
-          live = snap.value || (typeof settingsScope.get === 'function' ? settingsScope.get() : null);
+          logger.warn?.('Failed to register plugin updater:', err.message);
         }
-      } else if (typeof settingsScope.get === 'function') {
-        live = settingsScope.get();
-      }
-      if (live && typeof live === 'object') {
-        return {
-          ...currentSettings,
-          ...live,
+        return () => {
+          if (typeof unreg === 'function') unreg();
         };
-      }
-    }
-    return currentSettings;
-  };
-
-  const applySettings = () => {
-    const live = getConfig();
-    engine.updateConfig({
-      defaultMaxIterations: live.maxIterations,
-      autoDrive: live.autoDrive,
-      enableSound: live.enableSound,
-      showQuickLaunchButton: live.showQuickLaunchButton,
-      consecutiveToolFailureLimit: live.consecutiveToolFailureLimit,
-      maxTokenBudget: live.maxTokenBudget,
-      budgetWarningThreshold: live.budgetWarningThreshold,
-      autoCheckpointOnMilestone: live.autoCheckpointOnMilestone,
-      enableLiveActivityFeed: live.enableLiveActivityFeed,
-      enablePreplanning: live.enablePreplanning,
-      autoBranchOnGoalStart: live.autoBranchOnGoalStart,
-      enablePostGoalRetrospective: live.enablePostGoalRetrospective,
-      autoScaleBudgetNearCompletion: live.autoScaleBudgetNearCompletion,
-      enableTemplatesDrawer: live.enableTemplatesDrawer,
-      enableMilestoneDependencies: live.enableMilestoneDependencies,
-      soundScheme: live.soundScheme,
-      enableVoiceAnnouncements: live.enableVoiceAnnouncements,
-    });
-  };
-
-  // 1. Settings registration
-  ctx.inject(['settings'], (sctx) => {
-    try {
-      const scope = sctx.settings?.register?.(NS, Config, { base: currentSettings });
-      if (scope) {
-        settingsScope = scope;
-        applySettings();
-        if (typeof scope.subscribe === 'function') {
-          sctx.effect(() => {
-            const off = scope.subscribe(() => {
-              applySettings();
-            });
-            return () => {
-              if (typeof off === 'function') off();
-              settingsScope = null;
-            };
-          }, 'dsh-goal: settings subscription');
-        }
-      }
-    } catch (err) {
-      console.warn('[dsh-goal] Settings register skipped:', err.message);
-    }
-  });
-
-  // 2. Chat slash command /goal registration
-  ctx.inject(['commands'], (cctx) => {
-    try {
-      if (typeof cctx.commands?.register !== 'function') return;
-      const unregister = cctx.commands.register({
-        name: 'goal',
-        description: 'Manage Goal Mode: activate, milestones, pause, resume, and clear',
-        input: { hint: '[<objective>|clear|pause|resume]' },
-        handler: async (invocation) => {
-          const sid = sessionIdOf(invocation, 'default');
-          if (invocation?.agent) {
-            lastActiveAgent = invocation.agent;
-            sessionAgents.set(sid, invocation.agent);
-          }
-          const parsed = parseGoalInput(invocation?.rawInput);
-          const liveConfig = getConfig();
-          return executeGoalSlashCommand(engine, parsed, liveConfig, invocation?.agent, sid);
-        },
-      });
-
-      if (typeof unregister === 'function') {
-        cctx.effect(() => () => unregister(), 'dsh-goal: /goal command unregister');
-      }
-    } catch (err) {
-      console.warn('[dsh-goal] Commands register skipped:', err.message);
-    }
-  });
-
-  // 3. System prompt context injection
-  ctx.inject(['systemPrompt'], (pctx) => {
-    try {
-      if (typeof pctx.systemPrompt?.section === 'function') {
-        const globalSections = pctx.systemPrompt.layers?.global?.sections;
-        let displacedPromptSection = null;
-        if (globalSections?.data instanceof Map && globalSections.data.has('tool:goal')) {
-          displacedPromptSection = globalSections.data.get('tool:goal');
-          globalSections.data.delete('tool:goal');
-        }
-
-        const order = typeof pctx.systemPrompt.getSectionOrder === 'function'
-          ? (pctx.systemPrompt.getSectionOrder('TOOL_GOAL') || 2400)
-          : 2400;
-
-        const unregisterSection = pctx.systemPrompt.section({
-          name: 'tool:dsh-goal',
-          order,
-          text: (sessionCtx) => {
-            const sid = sessionIdOf(sessionCtx, 'default');
-            return engine.getStatePromptInjection(sid);
-          },
-        });
-
-        if (typeof unregisterSection === 'function') {
-          pctx.effect(() => () => {
-            unregisterSection();
-            if (displacedPromptSection && globalSections?.data instanceof Map) {
-              globalSections.data.set('tool:goal', displacedPromptSection);
-            }
-          }, 'dsh-goal: system prompt section');
-        }
-      }
-    } catch (err) {
-      console.warn('[dsh-goal] SystemPrompt section register skipped:', err.message);
-    }
-  });
-
-  // 4. Tools registration
-  registerTools(ctx, { engine, resumeActiveAgent });
-
-  // 5. One-click auto-updater registration
-  if (ctx.webServer?.register) {
-    try {
+      }, 'dsh-goal: plugin auto-updater');
+    } else {
       registerPluginUpdater(ctx, {
         packageName: '@goodandready/dsh-goal',
         endpoint: '/api/dsh-goal/update',
         manifestUrl: new URL('../package.json', import.meta.url),
       });
-    } catch (err) {
-      console.warn('[dsh-goal] Failed to register plugin updater:', err.message);
     }
   }
 
-  // 6. WebServer HTTP & SSE routes
-  registerRoutes(ctx, {
-    engine,
-    getConfig,
-    stopRunningAgents,
-    resumeActiveAgent,
-    sessionAgents,
+  // 2. WebServer HTTP & SSE routes (registered after updater so it remains primary)
+  const { broadcastEvent } = registerRoutes(ctx, {
+    engine: fallbackEngine,
+    milestoneManager,
+    gitSnapshotManager,
+    tokenBudgetGuard,
+    addonStore,
+    goalsService: ctx.goals,
+    getConfig: () => currentSettings,
     sseClients,
+    logger,
   });
 
-  // 7. Turn coordinator & tool-failure breaker
-  ctx.effect(() => {
-    const onTurnEnd = (turn) => {
-      const liveConfig = getConfig();
-      if (!liveConfig.autoDrive) return;
-
-      const sid = sessionIdOf(turn, 'default');
-      const usage = turn?.usage || turn?.meta?.usage || turn?.response?.usage || turn?.turn?.usage;
-      if (usage) {
-        engine.addTokenUsage(usage, sid);
+  // 3. Listen to core goal/changed events if ctx.on exists
+  if (typeof ctx?.on === 'function') {
+    ctx.on('goal/changed', async ({ agent, change }) => {
+      if (!change) return;
+      const op = change.operation;
+      const goal = change.goal;
+      const goalId = goal?.id || change.ref?.id;
+
+      if (op === 'create' || op === 'resume') {
+        tokenBudgetGuard.resetGoal(goalId);
+        broadcastEvent('goal_status', { op, goalId, goal });
       }
 
-      const snap = engine.getSnapshot(sid);
-      if (snap.hasActiveGoal && snap.state === GoalState.RUNNING) {
-        const steps = turn?.steps || turn?.turn?.steps || [];
-        const hasStepError = Array.isArray(steps) && steps.some((s) => {
-          return s?.status === 'error' || s?.error || s?.toolResult?.isError;
-        });
-        const hasTurnError = Boolean(turn?.error || turn?.reason?.kind === 'error');
-        const isToolFailure = hasStepError || hasTurnError;
-
-        if (isToolFailure) {
-          const failCount = engine.incrementToolFailureCount(sid);
-          const limit = liveConfig.consecutiveToolFailureLimit;
-          if (limit > 0 && failCount >= limit) {
-            const lang = snap.lang || (snap.title ? detectLanguage(snap.title) : 'en');
-            const pauseReason = lang === 'zh'
-              ? `工具重复出错（连续 ${failCount} 次）— 目标已暂停以防止死循环`
-              : `Repeated tool failure (${failCount} consecutive) — goal paused to prevent token burn`;
-            engine.pause(pauseReason, sid);
-            return;
+      if (op === 'complete' || op === 'clear') {
+        try {
+          const milestones = milestoneManager.getMilestones(goalId);
+          const snapshots = addonStore.getSnapshots(goalId);
+          const savedPath = saveGoalReportFile(goal || { id: goalId, objective: 'Completed Goal' }, {
+            milestones,
+            snapshots,
+          });
+          if (savedPath) {
+            logger.info?.(`[dsh-goal] Saved goal report to "${savedPath}"`);
           }
-        } else {
-          engine.resetToolFailureCount(sid);
-        }
-
-        if (turn?.reason?.kind === 'aborted' || turn?.reason?.kind === 'error' || turn?.error) {
-          return;
-        }
-
-        const lang = snap.lang || (snap.title ? detectLanguage(snap.title) : 'en');
-        const stallCount = engine.incrementStallCount(sid);
-        if (stallCount >= 2) {
-          const stallReason = lang === 'zh'
-            ? '智能体在过去 2 次迭代中未推进工作计划 — 需要操作员关注'
-            : 'Agent made no progress on work plan in the last 2 iterations — operator attention required';
-          engine.pause(stallReason, sid);
-          return;
+        } catch (err) {
+          logger.warn?.('[dsh-goal] Failed to save goal report on completion:', err.message);
         }
+        broadcastEvent('goal_status', { op, goalId, goal });
+      }
 
-        const canContinue = engine.incrementIteration(sid);
-        if (!canContinue) return;
-
-        const triggerNextTurn = () => {
-          const currentSnap = engine.getSnapshot(sid);
-          if (currentSnap.hasActiveGoal && currentSnap.state === GoalState.RUNNING) {
-            const currentLang = currentSnap.lang || (currentSnap.title ? detectLanguage(currentSnap.title) : 'en');
-            let promptText = currentLang === 'zh'
-              ? '请按照工作计划继续自主执行目标。每完成一步请通过 goal_update_progress 记录，所有任务完成后调用 goal_finish。'
-              : 'Continue autonomous goal execution according to the work plan. Mark each completed step via goal_update_progress, and when all tasks are complete, call goal_finish.';
-
-            if (currentSnap.pendingNudge) {
-              const userNudge = engine.consumePendingNudge(sid);
-              if (userNudge) {
-                promptText = (currentLang === 'zh'
-                  ? `🚨 用户紧急说明/指导方向：\n"${userNudge}"\n请根据此反馈调整执行。\n\n`
-                  : `🚨 URGENT USER CLARIFICATION / STEERING:\n"${userNudge}"\nAdjust execution adhering to this feedback.\n\n`) + promptText;
-              }
-            }
-
-            const promptMsg = createGoalUserMessage(promptText);
-            let target = sessionAgents.get(sid);
-            if (!target && lastActiveAgent && typeof lastActiveAgent.followup === 'function') {
-              const lastSid = sessionIdOf(lastActiveAgent, null);
-              if (!lastSid || lastSid === sid || sid === 'default') {
-                target = lastActiveAgent;
-              }
-            }
+      if (op === 'block') {
+        logger.info?.(`[dsh-goal] Goal "${goalId}" blocked: ${goal?.blockedReason?.message || 'Policy block'}`);
+        broadcastEvent('goal_status', { op, goalId, goal });
+      }
+    });
 
-            if (!target && agentsService && typeof agentsService.list === 'function') {
-              const list = agentsService.list();
-              if (list && list.length > 0) {
-                for (let i = list.length - 1; i >= 0; i--) {
-                  const cand = list[i];
-                  if (sessionIdOf(cand, null) === sid) {
-                    target = cand;
-                    break;
-                  }
-                }
-                if (!target && sid === 'default') target = list[list.length - 1];
-              }
-            }
+    // Inject milestone prompts and check budget during agent turns
+    ctx.on('agent/pre-step', async ({ agent, messages, step, signal }, next) => {
+      if (ctx.goals && typeof ctx.goals.get === 'function' && agent) {
+        try {
+          const currentGoal = ctx.goals.get(agent);
+          if (currentGoal && currentGoal.phase === 'active') {
+            const goalId = currentGoal.id;
+
+            // 1. Budget check
+            const milestones = milestoneManager.getMilestones(goalId);
+            const budgetCheck = tokenBudgetGuard.checkBudget({
+              agent,
+              goal: currentGoal,
+              tokenMeter: ctx.tokenMeter,
+              goalsService: ctx.goals,
+              milestones,
+            });
 
-            if (target && typeof target.followup === 'function' && target.status !== 'stopped') {
-              try {
-                target.followup(promptMsg);
-                sessionAgents.set(sid, target);
-              } catch (err) {
-                console.warn('[dsh-goal] Failed auto-drive followup:', err);
+            // 2. Active milestone prompt guidance
+            const milestonePrompt = milestoneManager.getActiveMilestonePrompt(goalId);
+            if (milestonePrompt && Array.isArray(messages)) {
+              let promptText = milestonePrompt;
+              if (budgetCheck.status === 'warning') {
+                promptText += `\n${budgetCheck.message}`;
+              } else if (budgetCheck.status === 'auto_scaled') {
+                promptText += `\n${budgetCheck.message}`;
               }
+              messages.push({
+                role: 'system',
+                content: promptText,
+              });
             }
           }
-        };
-
-        if (typeof setImmediate === 'function') {
-          setImmediate(triggerNextTurn);
-        } else {
-          setTimeout(triggerNextTurn, 0);
+        } catch (err) {
+          logger.warn?.('[dsh-goal] agent/pre-step error:', err.message);
         }
       }
-    };
+      return next ? next() : undefined;
+    });
+
+    // Compatibility events for turn/end and approval/asked
+    ctx.on('turn/end', (event) => {
+      // noop or session isolation
+    });
 
-    const onApprovalAsked = (event) => {
+    ctx.on('approval/asked', (event) => {
+      if (!fallbackEngine) return;
       const sid = sessionIdOf(event, 'default');
-      const snap = engine.getSnapshot(sid);
-      if (snap.hasActiveGoal && snap.state === GoalState.RUNNING) {
-        const lang = snap.lang || (snap.title ? detectLanguage(snap.title) : 'en');
-        const pauseReason = lang === 'zh'
-          ? '等待操作员确认/批准操作'
-          : 'Waiting for operator confirmation/approval';
-        engine.pause(pauseReason, sid);
+      const snap = fallbackEngine.getSnapshot(sid);
+      if (snap && snap.hasActiveGoal && snap.state === GoalState.RUNNING) {
+        fallbackEngine.pause('Waiting for operator confirmation/approval', sid);
+      }
+    });
+  }
+
+  // Settings synchronization
+  const applySettings = (patch) => {
+    if (!patch || typeof patch !== 'object') return;
+    currentSettings = { ...currentSettings, ...patch };
+    tokenBudgetGuard.updateConfig({
+      maxTokenBudget: currentSettings.maxTokenBudget,
+      warningThreshold: currentSettings.budgetWarningThreshold,
+      autoScaleNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
+    });
+    milestoneManager.enforceDependencies = Boolean(currentSettings.enableMilestoneDependencies);
+    if (typeof patch.storagePath === 'string' && patch.storagePath.trim()) {
+      addonStore.setStoragePath(patch.storagePath.trim());
+    }
+  };
+
+  if (typeof ctx?.inject === 'function') {
+    ctx.inject(['settings'], (sctx) => {
+      try {
+        const scope = sctx.settings?.register?.(NS, Config, { base: currentSettings });
+        if (scope) {
+          settingsScope = scope;
+          if (typeof scope.get === 'function') {
+            applySettings(scope.get());
+          }
+          if (typeof scope.subscribe === 'function') {
+            sctx.effect?.(() => {
+              const off = scope.subscribe(() => {
+                if (typeof scope.get === 'function') applySettings(scope.get());
+              });
+              return () => {
+                if (typeof off === 'function') off();
+                settingsScope = null;
+              };
+            }, 'dsh-goal: settings subscription');
+          }
+        }
+      } catch (err) {
+        logger.warn?.('Settings register skipped:', err.message);
       }
-    };
+    });
+  }
 
-    ctx.on?.('turn/end', onTurnEnd);
-    ctx.on?.('approval/asked', onApprovalAsked);
+  if (typeof ctx?.effect === 'function') {
+    ctx.effect(() => () => {
+      try {
+        addonStore.flushSync();
+      } catch (e) { /* ignore */ }
+    }, 'dsh-goal: teardown');
+  }
 
-    return () => {
-      ctx.off?.('turn/end', onTurnEnd);
-      ctx.off?.('approval/asked', onApprovalAsked);
-    };
-  }, 'dsh-goal: Session & Turn Coordinator');
+  return {
+    addonStore,
+    milestoneManager,
+    tokenBudgetGuard,
+    gitSnapshotManager,
+    engine: fallbackEngine,
+  };
 }