vellum 0.2.0 → 0.2.1

package/src/workspace/git-service.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { getLogger } from '../util/logger.js';
+import { getConfig } from '../config/loader.js';
 
 const execFileAsync = promisify(execFile);
 const log = getLogger('workspace-git');
@@ -142,12 +143,50 @@ export class WorkspaceGitService {
   private readonly mutex: Mutex;
   private initialized = false;
   private initPromise: Promise<void> | null = null;
+  private consecutiveFailures = 0;
+  private nextAllowedAttemptMs = 0;
 
   constructor(workspaceDir: string) {
     this.workspaceDir = workspaceDir;
     this.mutex = new Mutex();
   }
 
+  /**
+   * Check if the circuit breaker is open (too many recent failures).
+   * When open, commit attempts are skipped until the backoff window expires.
+   */
+  private isBreakerOpen(): boolean {
+    if (this.consecutiveFailures === 0) return false;
+    return Date.now() < this.nextAllowedAttemptMs;
+  }
+
+  private recordSuccess(): void {
+    if (this.consecutiveFailures > 0) {
+      log.info(
+        { workspaceDir: this.workspaceDir, previousFailures: this.consecutiveFailures },
+        'Circuit breaker closed: commit succeeded after failures',
+      );
+    }
+    this.consecutiveFailures = 0;
+    this.nextAllowedAttemptMs = 0;
+  }
+
+  private recordFailure(): void {
+    const config = getConfig();
+    const failureBackoffBaseMs = config.workspaceGit?.failureBackoffBaseMs ?? 2000;
+    const failureBackoffMaxMs = config.workspaceGit?.failureBackoffMaxMs ?? 60000;
+    this.consecutiveFailures++;
+    const delay = Math.min(
+      failureBackoffBaseMs * Math.pow(2, this.consecutiveFailures - 1),
+      failureBackoffMaxMs,
+    );
+    this.nextAllowedAttemptMs = Date.now() + delay;
+    log.warn(
+      { workspaceDir: this.workspaceDir, consecutiveFailures: this.consecutiveFailures, backoffMs: delay },
+      'Circuit breaker opened: commit failed, backing off',
+    );
+  }
+
   /**
    * Ensure the git repository is initialized.
    * Idempotent: safe to call multiple times.
@@ -344,47 +383,119 @@ export class WorkspaceGitService {
    *
    * @param decide - Called with the current status. Return an object with `message`
    *   (and optional `metadata`) to commit, or `null` to skip.
+   * @param options.bypassBreaker - Skip circuit breaker checks (used for shutdown commits).
+   * @param options.deadlineMs - Absolute timestamp (Date.now()) after which the commit
+   *   should be skipped. Checked before lock acquisition, after lock acquisition, and
+   *   before git add/commit to prevent stale queued attempts from doing expensive work.
    * @returns Whether a commit was created and the status at check time.
    */
   async commitIfDirty(
     decide: (status: GitStatus) => { message: string; metadata?: GitCommitMetadata } | null,
+    options?: { bypassBreaker?: boolean; deadlineMs?: number },
   ): Promise<{ committed: boolean; status: GitStatus }> {
+    const emptyStatus: GitStatus = { staged: [], modified: [], untracked: [], clean: false };
+
+    // Circuit breaker: skip expensive git work if recent attempts have been failing.
+    // Shutdown commits bypass the breaker because the process is about to exit and
+    // this is the last chance to persist workspace state.
+    if (!options?.bypassBreaker && this.isBreakerOpen()) {
+      log.debug(
+        { workspaceDir: this.workspaceDir, consecutiveFailures: this.consecutiveFailures },
+        'Circuit breaker open, skipping commit attempt',
+      );
+      return { committed: false, status: emptyStatus };
+    }
+
+    // Deadline fast-path: bail before acquiring the lock if already past deadline.
+    if (isDeadlineExpired(options?.deadlineMs)) {
+      log.debug(
+        { workspaceDir: this.workspaceDir },
+        'Deadline expired before lock acquisition, skipping commit',
+      );
+      return { committed: false, status: emptyStatus };
+    }
+
     await this.ensureInitialized();
 
-    return this.mutex.withLock(async () => {
-      const status = await this.getStatusInternal();
-      if (status.clean) {
-        return { committed: false, status };
-      }
+    try {
+      const result = await this.mutex.withLock(async () => {
+        // Re-check breaker under lock: a queued call that started before the
+        // breaker opened should not proceed with expensive git work now that
+        // the breaker is open.
+        if (!options?.bypassBreaker && this.isBreakerOpen()) {
+          log.debug(
+            { workspaceDir: this.workspaceDir, consecutiveFailures: this.consecutiveFailures },
+            'Circuit breaker open after lock acquisition, skipping commit',
+          );
+          return { committed: false, status: emptyStatus, didRunGit: false as const };
+        }
 
-      const decision = decide(status);
-      if (!decision) {
-        return { committed: false, status };
-      }
+        // Re-check deadline after lock acquisition: the call may have waited
+        // in the mutex queue past its deadline.
+        if (isDeadlineExpired(options?.deadlineMs)) {
+          log.debug(
+            { workspaceDir: this.workspaceDir },
+            'Deadline expired after lock acquisition, skipping commit',
+          );
+          return { committed: false, status: emptyStatus, didRunGit: false as const };
+        }
 
-      await this.execGit(['add', '-A']);
+        const status = await this.getStatusInternal();
+        if (status.clean) {
+          return { committed: false, status, didRunGit: true as const };
+        }
 
-      // Verify something was actually staged. Another service instance
-      // (or external process) could have committed between our status
-      // check and the add, leaving the index clean.
-      try {
-        await this.execGit(['diff', '--cached', '--quiet']);
-        // Exit code 0 means nothing staged — nothing to commit
-        return { committed: false, status };
-      } catch {
-        // Exit code 1 means there ARE staged changes — proceed
-      }
+        const decision = decide(status);
+        if (!decision) {
+          return { committed: false, status, didRunGit: true as const };
+        }
 
-      let fullMessage = decision.message;
-      if (decision.metadata && Object.keys(decision.metadata).length > 0) {
-        fullMessage += '\n\n' + Object.entries(decision.metadata)
-          .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
-          .join('\n');
-      }
+        // Check deadline before expensive git add/commit operations.
+        if (isDeadlineExpired(options?.deadlineMs)) {
+          log.debug(
+            { workspaceDir: this.workspaceDir },
+            'Deadline expired before git add/commit, skipping commit',
+          );
+          return { committed: false, status, didRunGit: true as const };
+        }
 
-      await this.execGit(['commit', '-m', fullMessage]);
-      return { committed: true, status };
-    });
+        await this.execGit(['add', '-A']);
+
+        // Verify something was actually staged. Another service instance
+        // (or external process) could have committed between our status
+        // check and the add, leaving the index clean.
+        try {
+          await this.execGit(['diff', '--cached', '--quiet']);
+          // Exit code 0 means nothing staged — nothing to commit
+          return { committed: false, status, didRunGit: true as const };
+        } catch (err) {
+          // git diff --cached --quiet exits with code 1 when there are staged changes.
+          // Any other error (timeout, permission, etc.) should be treated as a failure.
+          const execErr = err as ExecError;
+          if (execErr.code !== 1) {
+            throw err;
+          }
+          // Exit code 1 = staged changes exist — proceed with commit
+        }
+
+        let fullMessage = decision.message;
+        if (decision.metadata && Object.keys(decision.metadata).length > 0) {
+          fullMessage += '\n\n' + Object.entries(decision.metadata)
+            .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
+            .join('\n');
+        }
+
+        await this.execGit(['commit', '-m', fullMessage]);
+        return { committed: true, status, didRunGit: true as const };
+      });
+      if (result.didRunGit) {
+        this.recordSuccess();
+      }
+      return { committed: result.committed, status: result.status };
+    } catch (err) {
+      this.recordFailure();
+      throw err;
+    }
   }
 
   /**
@@ -532,15 +643,19 @@ export class WorkspaceGitService {
 
   /**
    * Execute a git command in the workspace directory.
-   * Includes a 30-second timeout to prevent hung operations
-   * (e.g. stale git lock files).
+   * Uses the configurable interactiveGitTimeoutMs (default 10 000 ms) to
+   * prevent hung operations (e.g. stale git lock files). The timeout is
+   * intentionally short for interactive workspace operations — background
+   * enrichment jobs use their own dedicated timeout.
    */
   private async execGit(args: string[]): Promise<{ stdout: string; stderr: string }> {
+    const config = getConfig();
+    const timeoutMs = config.workspaceGit?.interactiveGitTimeoutMs ?? 10_000;
     try {
       const { stdout, stderr } = await execFileAsync('git', args, {
         cwd: this.workspaceDir,
         encoding: 'utf-8',
-        timeout: 30_000,
+        timeout: timeoutMs,
         env: cleanGitEnv(this.workspaceDir),
       });
       return { stdout, stderr };
@@ -567,6 +682,23 @@ export class WorkspaceGitService {
     }
   }
 
+  /**
+   * Get the commit hash of the current HEAD.
+   * This is a lightweight read-only operation that does not require the mutex.
+   */
+  async getHeadHash(): Promise<string> {
+    const { stdout } = await this.execGit(['rev-parse', 'HEAD']);
+    return stdout.trim();
+  }
+
+  /**
+   * Write a git note to a specific commit.
+   * Uses the 'vellum' notes ref to avoid conflicts with default notes.
+   */
+  async writeNote(commitHash: string, noteContent: string): Promise<void> {
+    await this.execGit(['notes', '--ref=vellum', 'add', '-f', '-m', noteContent, commitHash]);
+  }
+
   /**
    * Check if the workspace has a git repository initialized.
    * This is a non-blocking check that doesn't trigger initialization.
@@ -583,6 +715,14 @@ export class WorkspaceGitService {
   }
 }
 
+/**
+ * Check whether a deadline has expired.
+ * Returns true when `deadlineMs` is provided and `Date.now()` has reached or passed it.
+ */
+export function isDeadlineExpired(deadlineMs?: number): boolean {
+  return deadlineMs !== undefined && Date.now() >= deadlineMs;
+}
+
 /**
  * Singleton registry for workspace git services.
  * Ensures one service instance per workspace directory.
@@ -618,3 +758,18 @@ export function getAllWorkspaceGitServices(): ReadonlyMap<string, WorkspaceGitSe
 export function _resetGitServiceRegistry(): void {
   serviceRegistry.clear();
 }
+
+/**
+ * @internal Test-only: reset circuit breaker state for a service instance
+ */
+export function _resetBreaker(service: WorkspaceGitService): void {
+  (service as unknown as { consecutiveFailures: number }).consecutiveFailures = 0;
+  (service as unknown as { nextAllowedAttemptMs: number }).nextAllowedAttemptMs = 0;
+}
+
+/**
+ * @internal Test-only: get consecutive failure count
+ */
+export function _getConsecutiveFailures(service: WorkspaceGitService): number {
+  return (service as unknown as { consecutiveFailures: number }).consecutiveFailures;
+}

package/src/workspace/heartbeat-service.ts

@@ -1,5 +1,11 @@
 import { getLogger } from '../util/logger.js';
 import { getAllWorkspaceGitServices, type WorkspaceGitService } from './git-service.js';
+import {
+  DefaultCommitMessageProvider,
+  type CommitContext,
+  type CommitMessageProvider,
+} from './commit-message-provider.js';
+import { getEnrichmentService } from './commit-message-enrichment-service.js';
 
 const log = getLogger('heartbeat');
 
@@ -23,6 +29,8 @@ export interface HeartbeatServiceOptions {
   getServices?: () => ReadonlyMap<string, WorkspaceGitService>;
   /** Override for getting the current timestamp (for testing). */
   now?: () => number;
+  /** Custom commit message provider. */
+  commitMessageProvider?: CommitMessageProvider;
 }
 
 /**
@@ -61,6 +69,7 @@ export class HeartbeatService {
   private readonly intervalMs: number;
   private readonly getServices: () => ReadonlyMap<string, WorkspaceGitService>;
   private readonly now: () => number;
+  private readonly commitMessageProvider: CommitMessageProvider;
   private timer: ReturnType<typeof setInterval> | null = null;
   /** Tracks the currently in-flight check to prevent overlapping runs and allow clean shutdown. */
   private activeCheck: Promise<HeartbeatCheckResult> | null = null;
@@ -71,6 +80,7 @@ export class HeartbeatService {
     this.intervalMs = options?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
     this.getServices = options?.getServices ?? getAllWorkspaceGitServices;
     this.now = options?.now ?? Date.now;
+    this.commitMessageProvider = options?.commitMessageProvider ?? new DefaultCommitMessageProvider();
   }
 
   /**
@@ -139,7 +149,7 @@ export class HeartbeatService {
         result.checked++;
 
         try {
-          const committed = await this.checkWorkspace(workspaceDir, service, 'heartbeat');
+          const committed = await this.checkWorkspace(workspaceDir, service);
           if (committed) {
             result.committed++;
           } else {
@@ -189,18 +199,39 @@ export class HeartbeatService {
 
       try {
         const now = this.now();
-        const { committed } = await service.commitIfDirty((status) => {
-          const totalChanges = new Set([...status.staged, ...status.modified, ...status.untracked]).size;
-          log.info({ workspaceDir, totalChanges }, 'Committing pending changes on shutdown');
-          return {
-            message: `auto-commit: shutdown safety net (${totalChanges} files)`,
-            metadata: { trigger: 'shutdown', timestamp: now },
+        let shutdownFiles: string[] = [];
+        const { committed } = await service.commitIfDirty((st) => {
+          const uniqueFiles = [...new Set([...st.staged, ...st.modified, ...st.untracked])];
+          shutdownFiles = uniqueFiles;
+          log.info({ workspaceDir, totalChanges: uniqueFiles.length }, 'Committing pending changes on shutdown');
+
+          const ctx: CommitContext = {
+            workspaceDir,
+            trigger: 'shutdown',
+            changedFiles: uniqueFiles,
+            timestampMs: now,
           };
-        });
+
+          return this.commitMessageProvider.buildImmediateMessage(ctx);
+        }, { bypassBreaker: true });
 
         if (committed) {
           firstSeenDirty.delete(workspaceDir);
           result.committed++;
+
+          // Fire-and-forget enrichment
+          try {
+            const commitHash = await service.getHeadHash();
+            const shutdownCtx: CommitContext = {
+              workspaceDir,
+              trigger: 'shutdown',
+              changedFiles: shutdownFiles,
+              timestampMs: this.now(),
+            };
+            getEnrichmentService().enqueue({ workspaceDir, commitHash, context: shutdownCtx, gitService: service });
+          } catch (enrichErr) {
+            log.debug({ enrichErr }, 'Failed to enqueue shutdown enrichment (non-fatal)');
+          }
         } else {
           result.skipped++;
         }
@@ -225,13 +256,15 @@ export class HeartbeatService {
   private async checkWorkspace(
     workspaceDir: string,
     service: WorkspaceGitService,
-    trigger: string,
   ): Promise<boolean> {
     const now = this.now();
+    let heartbeatFiles: string[] = [];
+    let heartbeatReason: string | undefined;
 
     // Atomic status check + conditional commit within a single mutex lock.
     const { committed, status } = await service.commitIfDirty((st) => {
-      const totalChanges = new Set([...st.staged, ...st.modified, ...st.untracked]).size;
+      const uniqueFiles = [...new Set([...st.staged, ...st.modified, ...st.untracked])];
+      const totalChanges = uniqueFiles.length;
 
       // Track when we first saw this workspace as dirty
       if (!firstSeenDirty.has(workspaceDir)) {
@@ -256,19 +289,43 @@ export class HeartbeatService {
         ? `changes older than ${Math.round(dirtyAge / 1000)}s`
         : `${totalChanges} files changed (threshold: ${this.fileThreshold})`;
 
+      heartbeatFiles = uniqueFiles;
+      heartbeatReason = reason;
+
       log.info(
         { workspaceDir, totalChanges, dirtyAgeMs: dirtyAge, reason },
         'Heartbeat auto-committing workspace changes',
       );
 
-      return {
-        message: `auto-commit: ${trigger} safety net (${totalChanges} files, ${reason})`,
-        metadata: { trigger, timestamp: now },
+      const ctx: CommitContext = {
+        workspaceDir,
+        trigger: 'heartbeat',
+        changedFiles: uniqueFiles,
+        timestampMs: now,
+        reason,
       };
+
+      return this.commitMessageProvider.buildImmediateMessage(ctx);
     });
 
     if (committed) {
       firstSeenDirty.delete(workspaceDir);
+
+      // Fire-and-forget enrichment
+      try {
+        const commitHash = await service.getHeadHash();
+        const hbCtx: CommitContext = {
+          workspaceDir,
+          trigger: 'heartbeat',
+          changedFiles: heartbeatFiles,
+          timestampMs: now,
+          reason: heartbeatReason,
+        };
+        getEnrichmentService().enqueue({ workspaceDir, commitHash, context: hbCtx, gitService: service });
+      } catch (enrichErr) {
+        log.debug({ enrichErr }, 'Failed to enqueue heartbeat enrichment (non-fatal)');
+      }
+
       return true;
     }
 

package/src/workspace/turn-commit.ts

@@ -11,6 +11,12 @@
 
 import { getWorkspaceGitService } from './git-service.js';
 import { getLogger } from '../util/logger.js';
+import {
+  DefaultCommitMessageProvider,
+  type CommitContext,
+  type CommitMessageProvider,
+} from './commit-message-provider.js';
+import { getEnrichmentService } from './commit-message-enrichment-service.js';
 
 const log = getLogger('turn-commit');
 
@@ -25,46 +31,6 @@ export interface TurnCommitMetadata {
   filesChanged: number;
 }
 
-/**
- * Build a commit message with structured metadata for a turn boundary commit.
- *
- * Format:
- * ```
- * Turn: <summary>
- *
- * Session: sess_xyz
- * Turn: 5
- * Timestamp: 2026-02-18T15:30:00Z
- * Files: 3 changed
- * ```
- */
-function buildCommitMessage(summary: string, metadata: TurnCommitMetadata): string {
-  return [
-    `Turn: ${summary}`,
-    '',
-    `Session: ${metadata.sessionId}`,
-    `Turn: ${metadata.turnNumber}`,
-    `Timestamp: ${metadata.timestamp}`,
-    `Files: ${metadata.filesChanged} changed`,
-  ].join('\n');
-}
-
-/**
- * Build a short summary of what changed from a list of file paths.
- */
-function buildChangeSummary(files: string[]): string {
-  if (files.length === 0) {
-    return 'workspace changes';
-  }
-  if (files.length === 1) {
-    return files[0];
-  }
-  if (files.length <= 3) {
-    return files.join(', ');
-  }
-  return `${files.slice(0, 2).join(', ')} and ${files.length - 2} more`;
-}
-
 /**
  * Attempt a turn-boundary commit for the workspace.
  *
@@ -77,40 +43,64 @@ function buildChangeSummary(files: string[]): string {
  * @param workspaceDir - Absolute path to the workspace directory
  * @param sessionId - Session/conversation identifier
  * @param turnNumber - 1-based turn number within the session
+ * @param provider - Optional commit message provider (defaults to deterministic)
+ * @param deadlineMs - Optional absolute deadline (Date.now()) after which the commit should be skipped
  */
 export async function commitTurnChanges(
   workspaceDir: string,
   sessionId: string,
   turnNumber: number,
+  provider?: CommitMessageProvider,
+  deadlineMs?: number,
 ): Promise<void> {
+  const messageProvider = provider ?? new DefaultCommitMessageProvider();
   try {
     const gitService = getWorkspaceGitService(workspaceDir);
+    const commitStartMs = Date.now();
 
     // Atomic status check + commit within a single mutex lock to prevent
     // TOCTOU races with heartbeat commits.
     const { committed, status } = await gitService.commitIfDirty((st) => {
       const uniqueFiles = [...new Set([...st.staged, ...st.modified, ...st.untracked])];
-      const timestamp = new Date().toISOString();
-      const summary = buildChangeSummary(uniqueFiles);
 
-      const metadata: TurnCommitMetadata = {
+      const ctx: CommitContext = {
+        workspaceDir,
+        trigger: 'turn',
         sessionId,
         turnNumber,
-        timestamp,
-        filesChanged: uniqueFiles.length,
+        changedFiles: uniqueFiles,
+        timestampMs: Date.now(),
       };
 
-      return { message: buildCommitMessage(summary, metadata) };
-    });
+      return messageProvider.buildImmediateMessage(ctx);
+    }, deadlineMs !== undefined ? { deadlineMs } : undefined);
+
+    const commitDurationMs = Date.now() - commitStartMs;
 
     if (committed) {
       const uniqueFiles = [...new Set([...status.staged, ...status.modified, ...status.untracked])];
       log.info(
-        { sessionId, turnNumber, filesChanged: uniqueFiles.length },
+        { sessionId, turnNumber, filesChanged: uniqueFiles.length, durationMs: commitDurationMs },
         'Turn-boundary commit created',
       );
+
+      // Fire-and-forget enrichment — never blocks turn completion
+      try {
+        const commitHash = await gitService.getHeadHash();
+        const ctx: CommitContext = {
+          workspaceDir,
+          trigger: 'turn',
+          sessionId,
+          turnNumber,
+          changedFiles: uniqueFiles,
+          timestampMs: Date.now(),
+        };
+        getEnrichmentService().enqueue({ workspaceDir, commitHash, context: ctx, gitService });
+      } catch (enrichErr) {
+        log.debug({ enrichErr }, 'Failed to enqueue enrichment (non-fatal)');
+      }
     } else {
-      log.debug({ sessionId, turnNumber }, 'No workspace changes to commit for turn');
+      log.debug({ sessionId, turnNumber, durationMs: commitDurationMs }, 'No workspace changes to commit for turn');
     }
   } catch (err) {
     // Never let commit failures propagate — they must not affect the turn