@link-assistant/hive-mind 2.7.1 → 2.7.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.7.2
+
+### Patch Changes
+
+- c6add61: Add experimental `--auto-resume-on-uncommitted-changes` flag (#1056) that complements the existing `--auto-restart-on-uncommitted-changes` by reusing the previous Claude Code session via `--resume <sessionId>` when uncommitted changes are detected, preserving the agent's accumulated context instead of starting a fresh session. The flag is disabled by default. A companion knob, `--auto-resume-on-uncommitted-changes-maximum-context-window-usage` (default 50%), bounds the worst-case peak usage of the usable pre-compaction context (respecting `--sub-session-size`); sessions at or above the threshold, or sessions whose usage cannot be verified, fall back to a fresh run.
+
 ## 2.7.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/auto-resume-uncommitted.lib.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-resume on uncommitted changes — decision helpers.
+ *
+ * Issue #1056: when uncommitted changes are detected and the user has
+ * enabled `--auto-resume-on-uncommitted-changes`, we want to call the
+ * agent again with `--resume <sessionId>` (preserving context) instead
+ * of starting a fresh session — but only when the previous session has
+ * not already filled most of its usable pre-compaction context. The threshold
+ * defaults to 50% of that usable limit and is configurable via
+ * `--auto-resume-on-uncommitted-changes-maximum-context-window-usage`.
+ *
+ * This module is intentionally tool-agnostic. It does not perform the
+ * resume itself — it just decides whether resuming is viable and
+ * computes the percentage that the caller can log.
+ */
+
+import { parseSubSessionSize } from './sub-session-size.lib.mjs';
+
+export const DEFAULT_MAX_CONTEXT_USAGE_PERCENT = 50;
+
+/**
+ * Read the configured max-context-usage threshold (in percent) from argv.
+ *
+ * Accepts both the camelCase form populated by yargs
+ * (`autoResumeOnUncommittedChangesMaximumContextWindowUsage`) and the
+ * dash-cased flag itself, so that programmatic callers and CLI users
+ * see the same default.
+ *
+ * @param {Object} argv - parsed CLI arguments
+ * @returns {number} threshold in [0, 100]
+ */
+export const getAutoResumeMaxContextUsage = (argv = {}) => {
+  const candidates = [argv.autoResumeOnUncommittedChangesMaximumContextWindowUsage, argv['auto-resume-on-uncommitted-changes-maximum-context-window-usage']];
+  for (const value of candidates) {
+    if (value === undefined || value === null || value === '') continue;
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (Number.isFinite(parsed)) return Math.max(0, Math.min(100, parsed));
+  }
+  return DEFAULT_MAX_CONTEXT_USAGE_PERCENT;
+};
+
+/**
+ * Whether `--auto-resume-on-uncommitted-changes` is enabled.
+ * @param {Object} argv
+ * @returns {boolean}
+ */
+export const isAutoResumeOnUncommittedChangesEnabled = (argv = {}) => {
+  return argv.autoResumeOnUncommittedChanges === true || argv['auto-resume-on-uncommitted-changes'] === true;
+};
+
+/**
+ * Pick the largest peak-context-input across all models in a token-usage map
+ * that has a known model context limit, and return both the peak and the
+ * matching limit. We use the worst (highest-utilisation) model so that
+ * resuming with multi-model sessions does not silently exceed the threshold
+ * for the model that has the smallest remaining headroom.
+ *
+ * @param {Object|null} tokenUsage - shape returned by calculateSessionTokens
+ * @returns {{peak: number, limit: number, contextLimit: number, ratio: number}|null} null when no model with verified usage and a known limit was found
+ */
+export const pickWorstContextUtilisation = (tokenUsage, argv = {}) => {
+  if (!tokenUsage || !tokenUsage.modelUsage) return null;
+  let worst = null;
+  for (const usage of Object.values(tokenUsage.modelUsage)) {
+    const contextLimit = usage?.modelInfo?.limit?.context;
+    if (!contextLimit || contextLimit <= 0) continue;
+    let limit = contextLimit;
+    try {
+      const configured = argv.subSessionSize ?? argv['sub-session-size'];
+      const subSession = parseSubSessionSize(configured, { contextWindow: contextLimit });
+      if (subSession.kind === 'tokens' && subSession.tokens > 0) {
+        limit = Math.min(contextLimit, subSession.tokens);
+      } else if (subSession.kind === 'percent' && subSession.tokens > 0) {
+        limit = Math.min(contextLimit, subSession.tokens);
+      }
+    } catch {
+      // Invalid values are reported by normal CLI validation. Programmatic
+      // callers still get a conservative decision against the model limit.
+    }
+    const peak = usage.peakContextUsage;
+    if (!Number.isFinite(peak) || peak <= 0) continue;
+    const ratio = peak / limit;
+    if (!worst || ratio > worst.ratio) worst = { peak, limit, contextLimit, ratio };
+  }
+  return worst;
+};
+
+/**
+ * Decide whether resuming is viable given a session ID and the previous
+ * session's token-usage data. Returns a structured result that the caller
+ * can log and act on.
+ *
+ * The decision tree is:
+ *   - no auto-resume flag → 'disabled'
+ *   - flag set, no session ID known → 'no_session_id'
+ *   - flag set, session id known, no usable context-stat data → 'no_context_data'
+ *     (fall back to a fresh run because available headroom cannot be verified)
+ *   - flag set, peak >= threshold → 'context_too_full'
+ *   - flag set, peak <  threshold → 'ok'
+ *
+ * @param {Object} params
+ * @param {Object} params.argv - parsed CLI arguments
+ * @param {string|null} params.sessionId - the session ID to resume, if any
+ * @param {Object|null} params.tokenUsage - result of calculateSessionTokens (may be null)
+ * @returns {{resume: boolean, reason: string, threshold: number, usedPercent: number|null, peak: number|null, limit: number|null}}
+ */
+export const decideAutoResumeOnUncommittedChanges = ({ argv = {}, sessionId = null, tokenUsage = null } = {}) => {
+  const threshold = getAutoResumeMaxContextUsage(argv);
+  if (!isAutoResumeOnUncommittedChangesEnabled(argv)) {
+    return { resume: false, reason: 'disabled', threshold, usedPercent: null, peak: null, limit: null };
+  }
+  if (!sessionId) {
+    return { resume: false, reason: 'no_session_id', threshold, usedPercent: null, peak: null, limit: null };
+  }
+  const worst = pickWorstContextUtilisation(tokenUsage, argv);
+  if (!worst) {
+    return { resume: false, reason: 'no_context_data', threshold, usedPercent: null, peak: null, limit: null };
+  }
+  const usedPercent = (worst.peak / worst.limit) * 100;
+  if (usedPercent >= threshold) {
+    return {
+      resume: false,
+      reason: 'context_too_full',
+      threshold,
+      usedPercent,
+      peak: worst.peak,
+      limit: worst.limit,
+    };
+  }
+  return {
+    resume: true,
+    reason: 'ok',
+    threshold,
+    usedPercent,
+    peak: worst.peak,
+    limit: worst.limit,
+  };
+};
+
+export default {
+  DEFAULT_MAX_CONTEXT_USAGE_PERCENT,
+  getAutoResumeMaxContextUsage,
+  isAutoResumeOnUncommittedChangesEnabled,
+  pickWorstContextUtilisation,
+  decideAutoResumeOnUncommittedChanges,
+};

package/src/option-suggestions.lib.mjs

@@ -197,6 +197,8 @@ const KNOWN_OPTION_NAMES = [
   'auto-pull-request-creation',
   'auto-commit-uncommitted-changes',
   'auto-restart-on-uncommitted-changes',
+  'auto-resume-on-uncommitted-changes',
+  'auto-resume-on-uncommitted-changes-maximum-context-window-usage',
   'continue-only-on-feedback',
   'claude-file',
   'gitkeep-file',

package/src/solve.config.lib.mjs

@@ -201,6 +201,16 @@ export const SOLVE_OPTION_DEFINITIONS = {
     description: 'Automatically restart when uncommitted changes are detected to allow the tool to handle them (default: true, use --no-auto-restart-on-uncommitted-changes to disable)',
     default: true,
   },
+  'auto-resume-on-uncommitted-changes': {
+    type: 'boolean',
+    description: 'EXPERIMENTAL: Automatically resume the previous Claude session when uncommitted changes are detected. Falls back to a fresh session when usable context headroom cannot be verified or is too low. Disabled by default; use --no-auto-resume-on-uncommitted-changes to switch it off explicitly.',
+    default: false,
+  },
+  'auto-resume-on-uncommitted-changes-maximum-context-window-usage': {
+    type: 'number',
+    description: 'Maximum usable pre-compaction context usage (percent) that still allows --auto-resume-on-uncommitted-changes to resume. The usable limit respects --sub-session-size. At or above this threshold the tool starts a fresh session (default: 50).',
+    default: 50,
+  },
   'auto-restart-max-iterations': {
     type: 'number',
     description: 'Maximum number of auto-restart iterations before stopping (default: 5, 0 = unlimited)',

package/src/solve.mjs

@@ -12,7 +12,6 @@ const { configureGitHubRateLimitLogging, wrapDollarWithGhRetry } = await import(
 const $ = wrapDollarWithGhRetry(__rawDollar$);
 const config = await import('./solve.config.lib.mjs');
 const { initializeConfig, parseArguments } = config;
-// Import Sentry integration
 const sentryLib = await import('./sentry.lib.mjs');
 const { initializeSentry, addBreadcrumb, reportError, closeSentry } = sentryLib;
 const { yargs, hideBin } = await initializeConfig(use);
@@ -1334,6 +1333,8 @@ try {
     prBranch,
     branchName,
     tempDir,
+    initialSessionId: sessionId,
+    initialResultModelUsage: resultModelUsage,
     argv: {
       ...argv,
       watch: argv.watch || shouldRestart, // Enable watch if uncommitted changes
@@ -1341,7 +1342,6 @@ try {
     },
   });
 
-  // Update session data with latest from watch mode for accurate pricing
   if (watchResult && watchResult.latestSessionId) {
     sessionId = watchResult.latestSessionId;
     anthropicTotalCostUSD = watchResult.latestAnthropicCost;

package/src/solve.watch.lib.mjs

@@ -65,6 +65,11 @@ const { trackAuthenticatedUserCommentsSince } = autoMergeHelpers;
 const resultsLib = await import('./solve.results.lib.mjs');
 const { maybeAttachWorkingSessionSummary, ensurePullRequestIssueLink } = resultsLib;
 
+// Issue #1056: Auto-resume on uncommitted changes — decide whether to call the
+// agent again with --resume <sessionId> instead of restarting from scratch.
+const autoResumeLib = await import('./auto-resume-uncommitted.lib.mjs');
+const { decideAutoResumeOnUncommittedChanges, isAutoResumeOnUncommittedChangesEnabled } = autoResumeLib;
+
 /**
  * Monitor for feedback in a loop and trigger restart when detected
  */
@@ -76,8 +81,12 @@ export const watchForFeedback = async params => {
   const maxAutoRestartIterations = normalizeAutoIterationLimit(argv.autoRestartMaxIterations);
 
   // Track latest session data across all iterations for accurate pricing
-  let latestSessionId = null;
+  // Issue #1056: Seed from the *initial* tool execution so the first auto-restart
+  // iteration can attempt --resume on the original session if the user opted in
+  // via --auto-resume-on-uncommitted-changes.
+  let latestSessionId = params.initialSessionId || null;
   let latestAnthropicCost = null;
+  let latestResultModelUsage = params.initialResultModelUsage || null;
 
   // Issue #1290: Track whether auto-restart iterations actually ran and whether logs were uploaded
   // This helps solve.mjs decide whether to upload final logs
@@ -323,16 +332,43 @@ export const watchForFeedback = async params => {
 
         let restartFeedbackLines = feedbackLines;
         let restartArgv = argv;
-        const shouldUseSessionResume = Boolean(isTemporaryWatch && (firstIterationInTemporaryMode || hasUncommittedInTempMode) && (argv.resumeOnAutoRestart || argv['resume-on-auto-restart']) && (argv.tool === 'claude' || !argv.tool) && global.previousSessionId);
+        const isUncommittedChangesRestart = isTemporaryWatch && (firstIterationInTemporaryMode || hasUncommittedInTempMode);
+        const isClaudeTool = argv.tool === 'claude' || !argv.tool;
+        const autoResumeOnUncommittedChanges = isUncommittedChangesRestart && isClaudeTool && isAutoResumeOnUncommittedChangesEnabled(argv);
+        let autoResumeDecision = null;
+
+        if (autoResumeOnUncommittedChanges) {
+          let tokenUsage = null;
+          if (latestSessionId && tempDir) {
+            try {
+              const { calculateSessionTokens } = await import('./claude.lib.mjs');
+              tokenUsage = await calculateSessionTokens(latestSessionId, tempDir, latestResultModelUsage);
+            } catch (tokenError) {
+              await log(`   ⚠️  Could not calculate token usage for auto-resume decision: ${tokenError.message}`, { verbose: true });
+            }
+          }
+          autoResumeDecision = decideAutoResumeOnUncommittedChanges({ argv, sessionId: latestSessionId, tokenUsage });
+        }
+
+        // Keep the older issue #661 experiment working independently. The issue
+        // #1056 option takes precedence when enabled because it adds the required
+        // context-headroom safety check.
+        const legacyResumeRequested = isUncommittedChangesRestart && isClaudeTool && (argv.resumeOnAutoRestart || argv['resume-on-auto-restart']);
+        const shouldUseSessionResume = autoResumeOnUncommittedChanges ? autoResumeDecision?.resume === true : Boolean(legacyResumeRequested && global.previousSessionId);
+        const resumeSessionId = autoResumeOnUncommittedChanges ? latestSessionId : global.previousSessionId;
 
         if (shouldUseSessionResume) {
           await log(formatAligned('', 'Experimental session resume: using minimal auto-restart prompt', '', 2));
-          await log(formatAligned('', `Resuming session: ${global.previousSessionId}`, '', 2));
+          await log(formatAligned('', `Resuming session: ${resumeSessionId}`, '', 2));
+
+          if (autoResumeDecision?.reason === 'ok') {
+            await log(formatAligned('', `Peak context usage: ${autoResumeDecision.peak.toLocaleString()} / ${autoResumeDecision.limit.toLocaleString()} usable tokens (${autoResumeDecision.usedPercent.toFixed(1)}%, threshold ${autoResumeDecision.threshold}%)`, '', 2));
+          }
 
-          if (argv.verbose) {
+          if (!autoResumeOnUncommittedChanges && argv.verbose) {
             try {
               const { calculateSessionTokens } = await import('./claude.lib.mjs');
-              const tokenUsage = await calculateSessionTokens(global.previousSessionId, tempDir);
+              const tokenUsage = await calculateSessionTokens(resumeSessionId, tempDir);
               if (tokenUsage?.totalTokens) {
                 await log(formatAligned('', `Previous session tokens: ${tokenUsage.totalTokens.toLocaleString()}`, '', 2));
               }
@@ -346,11 +382,14 @@ export const watchForFeedback = async params => {
           restartFeedbackLines = [minimalPrompt];
           restartArgv = {
             ...argv,
-            resume: global.previousSessionId,
+            resume: resumeSessionId,
             minimalRestartContext: true,
           };
 
           await log(formatAligned('', `Minimal restart prompt size: ${minimalPrompt.length} characters`, '', 2));
+        } else if (autoResumeOnUncommittedChanges) {
+          const skipReason = autoResumeDecision?.reason === 'context_too_full' ? `peak context usage ${autoResumeDecision.usedPercent.toFixed(1)}% reached the ${autoResumeDecision.threshold}% threshold` : autoResumeDecision?.reason === 'no_session_id' ? 'no previous session ID is available' : 'context usage could not be verified';
+          await log(formatAligned('', 'Auto-resume skipped:', `${skipReason}; starting a fresh session`, 2));
         }
 
         // Execute tool using shared utility
@@ -498,6 +537,12 @@ export const watchForFeedback = async params => {
             }
           }
 
+          // Issue #1056: Track latest model usage so the next auto-resume decision
+          // can re-evaluate context-window usage against the most recent peak.
+          if (toolResult.resultModelUsage) {
+            latestResultModelUsage = toolResult.resultModelUsage;
+          }
+
           // Issue #1508: Compute budget stats for auto-restart log comment
           let autoRestartBudgetStatsData = null;
           if (argv.tokensBudgetStats && latestSessionId && tempDir) {