@goodandready/dsh-goal 0.2.9 → 0.2.10

package/lib/goal-engine.js

@@ -3,6 +3,12 @@ import { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, create
 import { EngineStore } from './engine-store.js';
 import { buildStatePromptInjection } from './engine-prompt.js';
 import { matchMilestone, parseMilestoneItems, applyMilestoneUpdate, toggleMilestoneChecklistItem } from './engine-milestones.js';
+import { applyIntervention, recordActivity, processTokenBudget } from './engine-intervention.js';
+import { createGoalBranch, sanitizeBranchSlug, getCurrentGitBranch, mergeGoalBranch, discardGoalBranch } from './engine-git-branch.js';
+import { parseIssueRef } from './engine-issue-sync.js';
+import { generateRetrospectiveData } from './engine-retrospective.js';
+import { generatePreplanDraft } from './engine-templates.js';
+import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget } from './engine-sessions.js';
 
 export { GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone };
 export { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
@@ -20,6 +26,15 @@ export class GoalEngine {
     this.maxTokenBudget = options.maxTokenBudget ?? 0;
     this.budgetWarningThreshold = options.budgetWarningThreshold ?? 80;
     this.autoCheckpointOnMilestone = options.autoCheckpointOnMilestone ?? false;
+    this.enableLiveActivityFeed = options.enableLiveActivityFeed ?? true;
+    this.enablePreplanning = options.enablePreplanning ?? true;
+    this.autoBranchOnGoalStart = options.autoBranchOnGoalStart ?? true;
+    this.enablePostGoalRetrospective = options.enablePostGoalRetrospective ?? true;
+    this.autoScaleBudgetNearCompletion = options.autoScaleBudgetNearCompletion ?? false;
+    this.enableTemplatesDrawer = options.enableTemplatesDrawer ?? true;
+    this.enableMilestoneDependencies = options.enableMilestoneDependencies ?? true;
+    this.soundScheme = options.soundScheme ?? 'default';
+    this.enableVoiceAnnouncements = options.enableVoiceAnnouncements ?? false;
     this.maxSessions = options.maxSessions ?? 100;
     this.goals = new Map();
     this.listeners = new Set();
@@ -58,14 +73,13 @@ export class GoalEngine {
       try {
         listener(snapshot, sid);
       } catch (err) {
-        console.error?.('[GoalEngine] Listener error:', err?.message || err);
+        console.error('[dsh-goal] Error in GoalEngine listener:', err);
       }
     }
   }
 
   recordProgress(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    this.stallCounters.set(sid, 0);
+    this.stallCounters.set(sessionId || 'default', 0);
   }
 
   incrementStallCount(sessionId = 'default') {
@@ -77,8 +91,7 @@ export class GoalEngine {
   }
 
   getStallCount(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    return this.stallCounters.get(sid) || 0;
+    return this.stallCounters.get(sessionId || 'default') || 0;
   }
 
   updateConfig(config = {}) {
@@ -86,32 +99,25 @@ export class GoalEngine {
       const prev = this.defaultMaxIterations;
       this.defaultMaxIterations = config.defaultMaxIterations;
       for (const [_, goal] of this.goals) {
-        if (goal && goal.maxIterations === prev) {
-          goal.maxIterations = config.defaultMaxIterations;
-        }
+        if (goal && goal.maxIterations === prev) goal.maxIterations = config.defaultMaxIterations;
       }
     }
-    if (typeof config.autoDrive === 'boolean') {
-      this.autoDrive = config.autoDrive;
-    }
-    if (typeof config.enableSound === 'boolean') {
-      this.enableSound = config.enableSound;
-    }
-    if (typeof config.showQuickLaunchButton === 'boolean') {
-      this.showQuickLaunchButton = config.showQuickLaunchButton;
-    }
-    if (typeof config.consecutiveToolFailureLimit === 'number') {
-      this.consecutiveToolFailureLimit = Math.max(0, config.consecutiveToolFailureLimit);
-    }
-    if (typeof config.maxTokenBudget === 'number') {
-      this.maxTokenBudget = Math.max(0, config.maxTokenBudget);
-    }
-    if (typeof config.budgetWarningThreshold === 'number') {
-      this.budgetWarningThreshold = Math.max(1, Math.min(100, config.budgetWarningThreshold));
-    }
-    if (typeof config.autoCheckpointOnMilestone === 'boolean') {
-      this.autoCheckpointOnMilestone = config.autoCheckpointOnMilestone;
-    }
+    if (typeof config.autoDrive === 'boolean') this.autoDrive = config.autoDrive;
+    if (typeof config.enableSound === 'boolean') this.enableSound = config.enableSound;
+    if (typeof config.showQuickLaunchButton === 'boolean') this.showQuickLaunchButton = config.showQuickLaunchButton;
+    if (typeof config.consecutiveToolFailureLimit === 'number') this.consecutiveToolFailureLimit = Math.max(0, config.consecutiveToolFailureLimit);
+    if (typeof config.maxTokenBudget === 'number') this.maxTokenBudget = Math.max(0, config.maxTokenBudget);
+    if (typeof config.budgetWarningThreshold === 'number') this.budgetWarningThreshold = Math.max(1, Math.min(100, config.budgetWarningThreshold));
+    if (typeof config.autoCheckpointOnMilestone === 'boolean') this.autoCheckpointOnMilestone = config.autoCheckpointOnMilestone;
+    if (typeof config.enableLiveActivityFeed === 'boolean') this.enableLiveActivityFeed = config.enableLiveActivityFeed;
+    if (typeof config.enablePreplanning === 'boolean') this.enablePreplanning = config.enablePreplanning;
+    if (typeof config.autoBranchOnGoalStart === 'boolean') this.autoBranchOnGoalStart = config.autoBranchOnGoalStart;
+    if (typeof config.enablePostGoalRetrospective === 'boolean') this.enablePostGoalRetrospective = config.enablePostGoalRetrospective;
+    if (typeof config.autoScaleBudgetNearCompletion === 'boolean') this.autoScaleBudgetNearCompletion = config.autoScaleBudgetNearCompletion;
+    if (typeof config.enableTemplatesDrawer === 'boolean') this.enableTemplatesDrawer = config.enableTemplatesDrawer;
+    if (typeof config.enableMilestoneDependencies === 'boolean') this.enableMilestoneDependencies = config.enableMilestoneDependencies;
+    if (typeof config.soundScheme === 'string') this.soundScheme = config.soundScheme;
+    if (typeof config.enableVoiceAnnouncements === 'boolean') this.enableVoiceAnnouncements = config.enableVoiceAnnouncements;
     this.emit();
   }
 
@@ -121,75 +127,39 @@ export class GoalEngine {
 
   incrementToolFailureCount(sessionId = 'default') {
     const sid = sessionId || 'default';
-    const current = this.toolFailureCounters.get(sid) || 0;
-    const next = current + 1;
+    const next = (this.toolFailureCounters.get(sid) || 0) + 1;
     this.toolFailureCounters.set(sid, next);
     return next;
   }
 
   resetToolFailureCount(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    this.toolFailureCounters.set(sid, 0);
+    this.toolFailureCounters.set(sessionId || 'default', 0);
   }
 
   getToolFailureCount(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    return this.toolFailureCounters.get(sid) || 0;
+    return this.toolFailureCounters.get(sessionId || 'default') || 0;
   }
 
   nudge(text, sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
     if (!goal) return this.getSnapshot(sid);
-
-    const clean = String(text || '').trim();
-    if (!clean) return this.getSnapshot(sid);
-
-    if (!Array.isArray(goal.nudges)) {
-      goal.nudges = [];
-    }
-    const now = Date.now();
-    goal.nudges.push({ text: clean, timestamp: now });
-    goal.pendingNudge = clean;
-    goal.logs.push({
-      timestamp: now,
-      type: 'info',
-      message: `User steering / clarification: "${clean}"`,
-    });
-    if (goal.logs.length > 100) {
-      goal.logs = goal.logs.slice(-100);
-    }
-
-    this.emit(sid, true);
+    const res = addNudgeToGoal(goal, text);
+    if (res) this.emit(sid, true);
     return this.getSnapshot(sid);
   }
 
   consumePendingNudge(sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || !goal.pendingNudge) return null;
-    const nudge = goal.pendingNudge;
-    goal.pendingNudge = null;
-    this.emit(sid);
+    if (!goal) return null;
+    const nudge = consumeGoalNudge(goal);
+    if (nudge) this.emit(sid);
     return nudge;
   }
 
   pruneInactiveSessions() {
-    if (this.goals.size < this.maxSessions) return;
-    const inactive = [];
-    for (const [sid, goal] of this.goals.entries()) {
-      if (sid === 'default') continue;
-      if (goal.state === GoalState.COMPLETED || goal.state === GoalState.CANCELLED || goal.state === GoalState.FAILED) {
-        inactive.push({ sid, completedAt: goal.completedAt || goal.startedAt || 0 });
-      }
-    }
-    inactive.sort((a, b) => a.completedAt - b.completedAt);
-    while (this.goals.size >= this.maxSessions && inactive.length > 0) {
-      const oldest = inactive.shift();
-      this.goals.delete(oldest.sid);
-      this.stallCounters.delete(oldest.sid);
-      this.toolFailureCounters.delete(oldest.sid);
-    }
+    pruneInactiveSessions(this.goals, this.stallCounters, this.toolFailureCounters, this.maxSessions);
   }
 
   clearSession(sessionId) {
@@ -207,18 +177,16 @@ export class GoalEngine {
     }
 
     this.pruneInactiveSessions();
-
     const cleanTitle = title.trim();
     const now = Date.now();
     const sid = sessionId || 'default';
     this.stallCounters.set(sid, 0);
+    this.toolFailureCounters.set(sid, 0);
 
     const gitCommit = options.gitStartCommit !== undefined
       ? options.gitStartCommit
       : getGitCurrentCommit(options.cwd);
 
-    this.toolFailureCounters.set(sid, 0);
-
     const goal = {
       id: `goal-${now}-${Math.random().toString(36).substring(2, 7)}`,
       sessionId: sid,
@@ -235,21 +203,41 @@ export class GoalEngine {
       maxIterations: options.maxIterations ?? this.defaultMaxIterations,
       maxTokenBudget: options.maxTokenBudget ?? this.maxTokenBudget,
       budgetWarningTriggered: false,
+      budgetAutoScaled: false,
       gitStartCommit: gitCommit || null,
+      gitBranch: null,
+      gitParentBranch: null,
       pendingNudge: null,
       nudges: [],
       milestones: [],
+      activityFeed: [],
+      userDirective: null,
+      userDirectiveConsumed: false,
+      preplan: null,
+      retrospective: null,
+      issueRef: parseIssueRef(cleanTitle),
       tokensUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-      logs: [
-        {
-          timestamp: now,
-          type: 'info',
-          message: `Goal initiated: "${cleanTitle}"` + (gitCommit ? ` (Git: ${gitCommit})` : ''),
-        },
-      ],
+      logs: [{
+        timestamp: now,
+        type: 'info',
+        message: `Goal initiated: "${cleanTitle}"` + (gitCommit ? ` (Git: ${gitCommit})` : ''),
+      }],
       resultSummary: '',
     };
 
+    if (this.autoBranchOnGoalStart && options.autoBranch !== false && this.storagePath !== null && process.env.NODE_ENV !== 'test') {
+      const slug = sanitizeBranchSlug(cleanTitle);
+      const parentBranch = getCurrentGitBranch(options.cwd);
+      if (createGoalBranch(options.cwd, slug)) {
+        goal.gitBranch = slug;
+        goal.gitParentBranch = parentBranch;
+      }
+    }
+
+    if (this.enablePreplanning && options.preplan !== false && (!options.milestones || options.milestones.length === 0)) {
+      goal.preplan = { active: true, draftMilestones: generatePreplanDraft(cleanTitle) };
+    }
+
     this.goals.set(sid, goal);
 
     if (Array.isArray(options.milestones) && options.milestones.length > 0) {
@@ -263,22 +251,13 @@ export class GoalEngine {
   pause(reason = 'User requested pause', sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.RUNNING) {
-      return this.getSnapshot(sid);
-    }
+    if (!goal || goal.state !== GoalState.RUNNING) return this.getSnapshot(sid);
 
     goal.state = GoalState.PAUSED;
     goal.pausedAt = Date.now();
-    goal.logs.push({
-      timestamp: Date.now(),
-      type: 'warning',
-      message: `Paused: ${reason}`,
-    });
-
-    if (goal.logs.length > 100) {
-      goal.logs = goal.logs.slice(-100);
-    }
-
+    recordActivity(goal, { type: 'control', tool: 'pause', status: 'warning', details: reason });
+    goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Paused: ${reason}` });
+    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -286,29 +265,18 @@ export class GoalEngine {
   resume(sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.PAUSED) {
-      return this.getSnapshot(sid);
-    }
+    if (!goal || goal.state !== GoalState.PAUSED) return this.getSnapshot(sid);
 
     const now = Date.now();
     if (goal.pausedAt) {
       goal.totalPausedDurationMs += now - goal.pausedAt;
       goal.pausedAt = null;
     }
-
     goal.state = GoalState.RUNNING;
     this.stallCounters.set(sid, 0);
-
-    goal.logs.push({
-      timestamp: now,
-      type: 'info',
-      message: 'Goal resumed',
-    });
-
-    if (goal.logs.length > 100) {
-      goal.logs = goal.logs.slice(-100);
-    }
-
+    recordActivity(goal, { type: 'control', tool: 'resume', status: 'info', details: 'Resumed by user' });
+    goal.logs.push({ timestamp: now, type: 'info', message: 'Goal resumed' });
+    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -320,16 +288,9 @@ export class GoalEngine {
 
     goal.state = GoalState.CANCELLED;
     goal.completedAt = Date.now();
-    goal.logs.push({
-      timestamp: Date.now(),
-      type: 'warning',
-      message: `Cancelled: ${reason}`,
-    });
-
-    if (goal.logs.length > 100) {
-      goal.logs = goal.logs.slice(-100);
-    }
-
+    recordActivity(goal, { type: 'control', tool: 'cancel', status: 'warning', details: reason });
+    goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Cancelled: ${reason}` });
+    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -352,38 +313,44 @@ export class GoalEngine {
     goal.state = GoalState.COMPLETED;
     goal.completedAt = now;
     goal.resultSummary = summary;
+    if (this.enablePostGoalRetrospective) {
+      goal.retrospective = generateRetrospectiveData(goal, goal.cwd || process.cwd());
+    }
+    recordActivity(goal, { type: 'goal', tool: 'completeGoal', status: 'success', details: summary || 'Completed' });
     goal.logs.push({
       timestamp: now,
       type: 'info',
       message: `Goal completed successfully: ${summary || 'All objectives met.'}`,
     });
-
-    if (goal.logs.length > 100) {
-      goal.logs = goal.logs.slice(-100);
-    }
-
     for (const m of goal.milestones) {
       if (m.status === MilestoneStatus.IN_PROGRESS || m.status === MilestoneStatus.PENDING) {
         m.status = MilestoneStatus.COMPLETED;
       }
     }
-
     this.stallCounters.delete(sid);
     this.toolFailureCounters.delete(sid);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
 
+  setMilestones(milestonesList, sessionId = 'default') {
+    this.addMilestones(milestonesList, true, sessionId);
+    return this.getSnapshot(sessionId);
+  }
+
   addMilestones(milestonesList, shouldEmit = true, sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || !Array.isArray(milestonesList)) return;
-
-    const newItems = parseMilestoneItems(milestonesList, goal.milestones.length);
-    goal.milestones.push(...newItems);
+    if (!goal || !Array.isArray(milestonesList)) return [];
 
+    const newMilestones = parseMilestoneItems(milestonesList, goal.milestones.length);
+    for (const item of newMilestones) {
+      goal.milestones.push(item);
+    }
     this.recordProgress(sid);
+    recordActivity(goal, { type: 'milestone', tool: 'addMilestones', status: 'success', details: `Added ${newMilestones.length} milestones` });
     if (shouldEmit) this.emit(sid);
+    return newMilestones;
   }
 
   updateMilestone(id, status, notes = '', sessionId = 'default', checklist = null) {
@@ -394,37 +361,33 @@ export class GoalEngine {
     const target = goal.milestones.find((m) => matchMilestone(m, id));
     if (!target) return false;
 
-    const { prevStatus } = applyMilestoneUpdate(
-      target,
-      status,
-      notes,
-      checklist,
-      Object.values(MilestoneStatus)
-    );
+    const res = applyMilestoneUpdate(target, status, notes, checklist, Object.values(MilestoneStatus), {
+      enforceDependencies: this.enableMilestoneDependencies,
+      allMilestones: goal.milestones,
+    });
+    if (res.blocked) {
+      recordActivity(goal, {
+        type: 'milestone',
+        tool: 'updateMilestone',
+        status: 'error',
+        details: `Milestone ${id} blocked by ${res.missingDependencies?.join(', ')}`,
+      });
+      return false;
+    }
+
+    const prevStatus = res.prevStatus;
+    recordActivity(goal, { type: 'milestone', tool: 'updateMilestone', status: 'success', details: `${id} -> ${status}` });
 
-    // Auto Git Checkpoint on milestone completion
     if (target.status === MilestoneStatus.COMPLETED && prevStatus !== MilestoneStatus.COMPLETED && this.autoCheckpointOnMilestone) {
       const commitHash = createMilestoneCheckpoint(target, sid);
       if (commitHash) {
         target.checkpointCommit = commitHash;
-        goal.logs.push({
-          timestamp: Date.now(),
-          type: 'info',
-          message: `Git checkpoint saved for [${target.title}]: ${commitHash}`,
-        });
+        goal.logs.push({ timestamp: Date.now(), type: 'info', message: `Git checkpoint saved for [${target.title}]: ${commitHash}` });
       }
     }
 
-    goal.logs.push({
-      timestamp: Date.now(),
-      type: 'milestone',
-      message: `Milestone [${target.title}] status -> ${target.status}`,
-    });
-
-    if (goal.logs.length > 100) {
-      goal.logs = goal.logs.slice(-100);
-    }
-
+    goal.logs.push({ timestamp: Date.now(), type: 'milestone', message: `Milestone [${target.title}] status -> ${target.status}` });
+    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
     this.recordProgress(sid);
     this.emit(sid);
     return true;
@@ -434,40 +397,22 @@ export class GoalEngine {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
     if (!goal) return false;
-
     const target = goal.milestones.find((m) => matchMilestone(m, milestoneId));
+    if (!target) return false;
     const ok = toggleMilestoneChecklistItem(target, itemIndex, done);
-    if (!ok) return false;
-
-    this.recordProgress(sid);
-    this.emit(sid);
-    return true;
+    if (ok) {
+      this.recordProgress(sid);
+      this.emit(sid);
+    }
+    return ok;
   }
 
   extendBudget(addTokens = 50000, sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
     if (!goal) return false;
-
-    const currentTotal = goal.tokensUsage?.totalTokens || 0;
-    const currentMax = goal.maxTokenBudget || this.maxTokenBudget || 0;
-    const newBudget = Math.max(currentTotal, currentMax) + Math.max(1000, Number(addTokens) || 50000);
-
-    goal.maxTokenBudget = newBudget;
-    goal.budgetWarningTriggered = false;
-
-    if (goal.state === GoalState.PAUSED && goal.logs?.some((l) => l.message?.includes('Token budget reached'))) {
-      goal.state = GoalState.RUNNING;
-      goal.pausedAt = null;
-    }
-
-    goal.logs.push({
-      timestamp: Date.now(),
-      type: 'info',
-      message: `Token budget extended to ${newBudget.toLocaleString('en-US')} tokens`,
-    });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
-
+    extendGoalBudget(goal, addTokens, this.maxTokenBudget);
+    recordActivity(goal, { type: 'budget', tool: 'extendBudget', status: 'info', details: `+${addTokens} tokens` });
     this.emit(sid, true);
     return true;
   }
@@ -475,22 +420,20 @@ export class GoalEngine {
   incrementIteration(sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.RUNNING) {
-      return false;
-    }
+    if (!goal || goal.state !== GoalState.RUNNING) return false;
 
     goal.iterationsCount += 1;
-
     if (goal.iterationsCount >= goal.maxIterations) {
       goal.state = GoalState.FAILED;
+      goal.failedAt = Date.now();
+      goal.failureReason = "Max iterations (" + goal.maxIterations + ") reached";
+      recordActivity(goal, { type: 'control', tool: 'incrementIteration', status: 'error', details: goal.failureReason });
       goal.logs.push({
         timestamp: Date.now(),
-        type: 'error',
-        message: `Safety limit reached: maximum ${goal.maxIterations} iterations exceeded.`,
+        type: 'warning',
+        message: `Max iterations (${goal.maxIterations}) reached. Pausing autonomous loop.`,
       });
-      if (goal.logs.length > 100) {
-        goal.logs = goal.logs.slice(-100);
-      }
+      if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
       this.emit(sid, true);
       return false;
     }
@@ -509,10 +452,7 @@ export class GoalEngine {
     const goal = this.goals.get(sid);
     if (!goal) return;
 
-    if (!goal.tokensUsage) {
-      goal.tokensUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
-    }
-
+    if (!goal.tokensUsage) goal.tokensUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
     const prompt = Number(usage.promptTokens ?? usage.input_tokens ?? usage.prompt_tokens ?? 0) || 0;
     const completion = Number(usage.completionTokens ?? usage.output_tokens ?? usage.completion_tokens ?? 0) || 0;
     const total = Number(usage.totalTokens ?? usage.total_tokens ?? (prompt + completion)) || (prompt + completion);
@@ -521,43 +461,22 @@ export class GoalEngine {
     goal.tokensUsage.completionTokens += completion;
     goal.tokensUsage.totalTokens += total;
 
-    // Token Budget Guard Check
-    const budget = goal.maxTokenBudget || this.maxTokenBudget || 0;
-    if (budget > 0) {
-      const currentTotal = goal.tokensUsage.totalTokens;
-      const warnThreshold = (budget * (this.budgetWarningThreshold || 80)) / 100;
-
-      if (currentTotal >= warnThreshold && !goal.budgetWarningTriggered) {
-        goal.budgetWarningTriggered = true;
-        goal.logs.push({
-          timestamp: Date.now(),
-          type: 'warning',
-          message: `Token budget warning: ${currentTotal.toLocaleString('en-US')}/${budget.toLocaleString('en-US')} tokens consumed (${Math.round((currentTotal / budget) * 100)}%)`,
-        });
-        if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
-      }
-
-      if (currentTotal >= budget && goal.state === GoalState.RUNNING) {
-        goal.state = GoalState.PAUSED;
-        goal.pausedAt = Date.now();
-        goal.logs.push({
-          timestamp: Date.now(),
-          type: 'warning',
-          message: `Token budget reached: ${currentTotal.toLocaleString('en-US')}/${budget.toLocaleString('en-US')} tokens. Pausing autonomous loop.`,
-        });
-        if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
-        this.emit(sid, true);
-        return;
-      }
+    const budgetCheck = processTokenBudget(goal, {
+      maxTokenBudget: this.maxTokenBudget,
+      budgetWarningThreshold: this.budgetWarningThreshold,
+      autoScaleBudgetNearCompletion: this.autoScaleBudgetNearCompletion,
+      GoalState,
+    });
+    if (budgetCheck.paused) {
+      this.emit(sid, true);
+      return;
     }
-
     this.emit(sid);
   }
 
   getEstimatedRemainingSeconds(sessionId = 'default') {
     const sid = sessionId || 'default';
-    const goal = this.goals.get(sid);
-    return calculateRemainingSeconds(goal, this.getElapsedSeconds(sid));
+    return calculateRemainingSeconds(this.goals.get(sid), this.getElapsedSeconds(sid));
   }
 
   getSnapshot(sessionId = 'default') {
@@ -572,17 +491,63 @@ export class GoalEngine {
   getStatePromptInjection(sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.RUNNING) {
-      return '';
+    if (!goal || goal.state !== GoalState.RUNNING) return '';
+
+    const snap = this.getSnapshot(sid);
+    const nudge = this.consumePendingNudge(sid);
+    const injection = buildStatePromptInjection(snap, nudge);
+    if (goal.userDirective) goal.userDirectiveConsumed = true;
+    return injection;
+  }
+
+  intervene(intervention = {}, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) return { ok: false, error: 'Goal not found' };
+    const res = applyIntervention(goal, intervention);
+    this.emit(sid, true);
+    return { ok: true, state: this.getSnapshot(sid) };
+  }
+
+  approvePreplan(sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal || !goal.preplan?.active) return this.getSnapshot(sid);
+    const drafts = goal.preplan.draftMilestones || [];
+    goal.preplan.active = false;
+    if (drafts.length > 0 && goal.milestones.length === 0) {
+      this.addMilestones(drafts, false, sid);
     }
+    this.emit(sid, true);
+    return this.getSnapshot(sid);
+  }
 
-    const snapshot = this.getSnapshot(sid);
-    let pendingNudge = null;
-    if (goal.pendingNudge) {
-      pendingNudge = goal.pendingNudge;
-      goal.pendingNudge = null;
+  mergeGoalBranch(targetBranch = 'main', sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal || !goal.gitBranch) return false;
+    const ok = mergeGoalBranch(goal.cwd || process.cwd(), goal.gitBranch, targetBranch);
+    if (ok) recordActivity(goal, { type: 'git', tool: 'mergeGoalBranch', status: 'success', details: `Merged ${goal.gitBranch}` });
+    this.emit(sid, true);
+    return ok;
+  }
+
+  discardGoalBranch(targetBranch = 'main', sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal || !goal.gitBranch) return false;
+    const ok = discardGoalBranch(goal.cwd || process.cwd(), goal.gitBranch, targetBranch);
+    if (ok) {
+      recordActivity(goal, { type: 'git', tool: 'discardGoalBranch', status: 'info', details: `Discarded ${goal.gitBranch}` });
+      goal.gitBranch = null;
     }
+    this.emit(sid, true);
+    return ok;
+  }
 
-    return buildStatePromptInjection(snapshot, pendingNudge);
+  recordToolActivity(tool, status, details, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (goal) recordActivity(goal, { type: 'tool', tool, status, details });
   }
 }