@vellumai/assistant 0.3.0

package/src/work-items/work-item-store.ts

@@ -0,0 +1,325 @@
+import { eq, desc, asc } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { workItems } from '../memory/schema.js';
+import { getTask } from '../tasks/task-store.js';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export type WorkItemStatus = 'queued' | 'running' | 'awaiting_review' | 'failed' | 'cancelled' | 'done' | 'archived';
+
+export interface WorkItem {
+  id: string;
+  taskId: string;
+  title: string;
+  notes: string | null;
+  status: WorkItemStatus;
+  priorityTier: number;
+  sortIndex: number | null;
+  lastRunId: string | null;
+  lastRunConversationId: string | null;
+  lastRunStatus: string | null;
+  sourceType: string | null;
+  sourceId: string | null;
+  requiredTools: string | null;
+  approvedTools: string | null;
+  approvalStatus: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ── CRUD ─────────────────────────────────────────────────────────────
+
+export function createWorkItem(opts: {
+  taskId: string;
+  title: string;
+  notes?: string;
+  priorityTier?: number;
+  sortIndex?: number;
+  sourceType?: string;
+  sourceId?: string;
+  requiredTools?: string;
+}): WorkItem {
+  const db = getDb();
+  const now = Date.now();
+  const id = crypto.randomUUID();
+  const item: WorkItem = {
+    id,
+    taskId: opts.taskId,
+    title: opts.title,
+    notes: opts.notes ?? null,
+    status: 'queued',
+    priorityTier: opts.priorityTier ?? 1,
+    sortIndex: opts.sortIndex ?? null,
+    lastRunId: null,
+    lastRunConversationId: null,
+    lastRunStatus: null,
+    sourceType: opts.sourceType ?? null,
+    sourceId: opts.sourceId ?? null,
+    requiredTools: opts.requiredTools ?? null,
+    approvedTools: null,
+    approvalStatus: 'none',
+    createdAt: now,
+    updatedAt: now,
+  };
+  db.insert(workItems).values(item).run();
+  return item;
+}
+
+/**
+ * Create a work item without any pre-approved permissions. Items start
+ * with `approvalStatus: 'none'` and no `approvedTools` — approval
+ * happens only via the explicit preflight flow before execution.
+ */
+export function createWorkItemWithPermissions(opts: {
+  taskId: string;
+  title: string;
+  notes?: string;
+  priorityTier?: number;
+  sortIndex?: number;
+  sourceType?: string;
+  sourceId?: string;
+  requiredTools?: string;
+}): WorkItem {
+  return createWorkItem(opts);
+}
+
+export function getWorkItem(id: string): WorkItem | undefined {
+  const db = getDb();
+  return db.select().from(workItems).where(eq(workItems.id, id)).get() as WorkItem | undefined;
+}
+
+export function listWorkItems(opts?: { status?: WorkItemStatus }): WorkItem[] {
+  const db = getDb();
+  let query = db.select().from(workItems);
+  if (opts?.status) {
+    query = query.where(eq(workItems.status, opts.status)) as typeof query;
+  }
+  return query
+    .orderBy(asc(workItems.priorityTier), asc(workItems.sortIndex), desc(workItems.updatedAt))
+    .all() as WorkItem[];
+}
+
+export function updateWorkItem(
+  id: string,
+  updates: Partial<Pick<WorkItem, 'title' | 'notes' | 'status' | 'priorityTier' | 'sortIndex' | 'lastRunId' | 'lastRunConversationId' | 'lastRunStatus' | 'requiredTools' | 'approvedTools' | 'approvalStatus'>>,
+): WorkItem | undefined {
+  const db = getDb();
+  db.update(workItems)
+    .set({ ...updates, updatedAt: Date.now() })
+    .where(eq(workItems.id, id))
+    .run();
+  return getWorkItem(id);
+}
+
+export function deleteWorkItem(id: string): void {
+  const db = getDb();
+  db.delete(workItems).where(eq(workItems.id, id)).run();
+}
+
+// ── Queue Removal ───────────────────────────────────────────────────
+
+export interface RemoveWorkItemResult {
+  success: boolean;
+  title: string;
+  message: string;
+}
+
+/**
+ * Shared helper for removing a single work item from the queue by ID.
+ * Used by both task_delete (compat path) and task_list_remove so all
+ * single-item deletions follow one codepath.
+ */
+export function removeWorkItemFromQueue(id: string): RemoveWorkItemResult {
+  const item = getWorkItem(id);
+  if (!item) {
+    return { success: false, title: '', message: `No work item found with ID "${id}"` };
+  }
+  deleteWorkItem(item.id);
+  return { success: true, title: item.title, message: `Removed "${item.title}" from the task queue.` };
+}
+
+// ── Selectors / Helpers ─────────────────────────────────────────────
+
+export interface WorkItemSelector {
+  workItemId?: string;
+  taskId?: string;
+  title?: string;
+  /** Disambiguator: filter by priority tier (0 = high, 1 = medium, 2 = low) */
+  priorityTier?: number;
+  /** Disambiguator: filter by status (queued, running, etc.) */
+  status?: WorkItemStatus;
+  /** Disambiguator: 1-indexed creation order (1 = oldest, 2 = second oldest, etc.) */
+  createdOrder?: number;
+}
+
+export type ResolveWorkItemResult =
+  | { status: 'found'; workItem: WorkItem }
+  | { status: 'not_found'; message: string }
+  | { status: 'ambiguous'; matches: WorkItem[]; message: string };
+
+const PRIORITY_TIER_LABELS: Record<number, string> = { 0: 'high', 1: 'medium', 2: 'low' };
+
+function formatAmbiguityMessage(selectorLabel: string, matches: WorkItem[]): string {
+  const lines = matches.map(
+    m =>
+      `  - ID: ${m.id} | title: "${m.title}" | priority: ${PRIORITY_TIER_LABELS[m.priorityTier] ?? m.priorityTier} | status: ${m.status}`,
+  );
+  return `Multiple items match '${selectorLabel}'. Please specify which one:\n${lines.join('\n')}`;
+}
+
+/** Find all active work items for a given task ID */
+export function findActiveWorkItemsByTaskId(taskId: string): WorkItem[] {
+  return listWorkItems().filter(
+    i => i.taskId === taskId && i.status !== 'done' && i.status !== 'archived'
+  );
+}
+
+/** Find all active work items matching a title (case-insensitive exact match) */
+export function findActiveWorkItemsByTitle(title: string): WorkItem[] {
+  const normalized = title.trim().toLowerCase();
+  return listWorkItems().filter(
+    i => i.title.trim().toLowerCase() === normalized && i.status !== 'done' && i.status !== 'archived'
+  );
+}
+
+/**
+ * Apply disambiguator fields to narrow down a set of candidate matches.
+ * Filters by priorityTier, then status, then picks by createdOrder if provided.
+ * Returns the filtered list (may still contain multiple items if disambiguation
+ * fields are insufficient).
+ */
+function applyDisambiguators(items: WorkItem[], selector: WorkItemSelector): WorkItem[] {
+  let filtered = items;
+
+  if (selector.priorityTier !== undefined) {
+    filtered = filtered.filter(i => i.priorityTier === selector.priorityTier);
+  }
+
+  if (selector.status !== undefined) {
+    filtered = filtered.filter(i => i.status === selector.status);
+  }
+
+  if (selector.createdOrder !== undefined && filtered.length > 0) {
+    const sorted = [...filtered].sort((a, b) => a.createdAt - b.createdAt);
+    const idx = selector.createdOrder - 1; // convert 1-indexed to 0-indexed
+    if (idx >= 0 && idx < sorted.length) {
+      filtered = [sorted[idx]];
+    }
+    // If createdOrder is out of range, return the full filtered list so the
+    // caller can report ambiguity with the remaining candidates.
+  }
+
+  return filtered;
+}
+
+/**
+ * Given a list of candidate matches, apply disambiguators and return a resolution result.
+ * Centralises the disambiguate-or-return-ambiguous logic shared across selector branches.
+ */
+function resolveFromCandidates(items: WorkItem[], selectorLabel: string, selector: WorkItemSelector): ResolveWorkItemResult {
+  if (items.length === 0) {
+    return { status: 'not_found', message: `No active work item found for "${selectorLabel}"` };
+  }
+  if (items.length === 1) {
+    return { status: 'found', workItem: items[0] };
+  }
+
+  // Multiple matches — try to narrow down with disambiguator fields
+  const narrowed = applyDisambiguators(items, selector);
+
+  if (narrowed.length === 1) {
+    return { status: 'found', workItem: narrowed[0] };
+  }
+  if (narrowed.length === 0) {
+    // Disambiguators filtered out everything — report the original set so the
+    // caller sees what was available
+    return { status: 'ambiguous', matches: items, message: formatAmbiguityMessage(selectorLabel, items) };
+  }
+  return { status: 'ambiguous', matches: narrowed, message: formatAmbiguityMessage(selectorLabel, narrowed) };
+}
+
+/**
+ * Resolve a single active work item from a selector.
+ * Tries fields in priority order: workItemId > taskId > title.
+ * Only considers active items (status not 'done' or 'archived').
+ * Returns a discriminated union so callers can handle ambiguity explicitly
+ * instead of silently picking one match when multiple exist.
+ *
+ * When multiple items match, the optional disambiguator fields (priorityTier,
+ * status, createdOrder) are applied to narrow down the set.
+ */
+export function resolveWorkItem(selector: WorkItemSelector): ResolveWorkItemResult {
+  if (selector.workItemId) {
+    const item = getWorkItem(selector.workItemId);
+    if (!item) return { status: 'not_found', message: `No work item found with ID "${selector.workItemId}"` };
+    if (item.status === 'done' || item.status === 'archived') {
+      return { status: 'not_found', message: `Work item "${selector.workItemId}" is ${item.status}` };
+    }
+    return { status: 'found', workItem: item };
+  }
+
+  if (selector.taskId) {
+    const items = findActiveWorkItemsByTaskId(selector.taskId);
+    return resolveFromCandidates(items, selector.taskId, selector);
+  }
+
+  if (selector.title) {
+    const items = findActiveWorkItemsByTitle(selector.title);
+    return resolveFromCandidates(items, selector.title, selector);
+  }
+
+  return { status: 'not_found', message: 'At least one selector field (workItemId, taskId, or title) must be provided' };
+}
+
+// ── Entity Identification ───────────────────────────────────────────
+
+export type EntityType = 'task_template' | 'work_item' | 'unknown';
+
+export interface EntityIdentification {
+  type: EntityType;
+  id: string;
+  title?: string;
+}
+
+/**
+ * Determine whether an ID refers to a task template (tasks table) or
+ * a work item (work_items table). Used by tool error messages to give
+ * the model corrective guidance when the wrong entity type is provided.
+ */
+export function identifyEntityById(id: string): EntityIdentification {
+  const workItem = getWorkItem(id);
+  if (workItem) {
+    return { type: 'work_item', id: workItem.id, title: workItem.title };
+  }
+
+  const task = getTask(id);
+  if (task) {
+    return { type: 'task_template', id: task.id, title: task.title };
+  }
+
+  return { type: 'unknown', id };
+}
+
+/**
+ * Build a corrective error message when a work item ID is passed where
+ * a task template ID is expected.
+ */
+export function buildWorkItemMismatchError(id: string, title: string, expectedTool: string): string {
+  return [
+    `Entity mismatch: The ID "${id}" refers to a work item ("${title}"), not a task template.`,
+    `Corrective action: Use ${expectedTool} to operate on work items in the task queue.`,
+    `Selector fields: work_item_id: "${id}" or title: "${title}"`,
+  ].join('\n');
+}
+
+/**
+ * Build a corrective error message when a task template ID is passed where
+ * a work item ID is expected.
+ */
+export function buildTaskTemplateMismatchError(id: string, title: string, expectedTool: string): string {
+  return [
+    `Entity mismatch: The ID "${id}" refers to a task template ("${title}"), not a work item.`,
+    `Corrective action: Use ${expectedTool} to operate on task templates.`,
+    `Selector fields: task_id: "${id}" or task_name: "${title}"`,
+  ].join('\n');
+}

package/src/workspace/commit-message-enrichment-service.ts

@@ -0,0 +1,284 @@
+/**
+ * Non-blocking enrichment queue for post-commit message enhancement.
+ *
+ * After a synchronous commit succeeds, callers can enqueue enrichment jobs
+ * that run asynchronously without blocking the commit path. This is the
+ * scaffold for future LLM-powered commit message enrichment.
+ *
+ * Key properties:
+ * - Bounded queue with configurable max size (drops oldest on overflow)
+ * - Bounded concurrency (default 1 worker)
+ * - Per-job timeout with retry + exponential backoff
+ * - Graceful shutdown: drains in-flight jobs, discards pending jobs
+ * - Fire-and-forget: enqueue() never blocks or throws
+ */
+
+import { getLogger } from '../util/logger.js';
+import { getConfig } from '../config/loader.js';
+import type { WorkspaceGitService } from './git-service.js';
+import type { CommitContext } from './commit-message-provider.js';
+
+const log = getLogger('enrichment-queue');
+
+export interface EnrichmentJob {
+  workspaceDir: string;
+  commitHash: string;
+  context: CommitContext;
+  gitService: WorkspaceGitService;
+}
+
+interface InternalJob extends EnrichmentJob {
+  attempts: number;
+}
+
+export interface EnrichmentServiceOptions {
+  maxQueueSize?: number;
+  maxConcurrency?: number;
+  jobTimeoutMs?: number;
+  maxRetries?: number;
+}
+
+/**
+ * Non-blocking enrichment queue service.
+ *
+ * Enqueue jobs after successful commits. Each job runs the enrichment
+ * worker (currently a no-op placeholder) and writes the result as a
+ * git note on the commit.
+ */
+export class CommitEnrichmentService {
+  private readonly maxQueueSize: number;
+  private readonly maxConcurrency: number;
+  private readonly jobTimeoutMs: number;
+  private readonly maxRetries: number;
+
+  private queue: InternalJob[] = [];
+  private activeWorkers = 0;
+  private droppedCount = 0;
+  private succeededCount = 0;
+  private failedCount = 0;
+  private shuttingDown = false;
+  private inFlightPromises: Set<Promise<void>> = new Set();
+
+  constructor(options?: EnrichmentServiceOptions) {
+    const config = getConfig();
+    const gitConfig = config.workspaceGit;
+    this.maxQueueSize = options?.maxQueueSize ?? gitConfig?.enrichmentQueueSize ?? 50;
+    this.maxConcurrency = options?.maxConcurrency ?? gitConfig?.enrichmentConcurrency ?? 1;
+    this.jobTimeoutMs = options?.jobTimeoutMs ?? gitConfig?.enrichmentJobTimeoutMs ?? 30000;
+    this.maxRetries = options?.maxRetries ?? gitConfig?.enrichmentMaxRetries ?? 2;
+  }
+
+  /**
+   * Enqueue an enrichment job. Fire-and-forget — never blocks or throws.
+   */
+  enqueue(job: EnrichmentJob): void {
+    if (this.shuttingDown) {
+      log.debug({ commitHash: job.commitHash }, 'Enrichment queue shutting down, discarding job');
+      return;
+    }
+
+    const internalJob: InternalJob = { ...job, attempts: 0 };
+
+    // Drop oldest if queue is full
+    if (this.queue.length >= this.maxQueueSize) {
+      const dropped = this.queue.shift()!;
+      this.droppedCount++;
+      log.warn(
+        { droppedHash: dropped.commitHash, queueSize: this.queue.length, droppedCount: this.droppedCount },
+        'Enrichment queue full, dropping oldest job',
+      );
+    }
+
+    this.queue.push(internalJob);
+    log.debug(
+      { commitHash: job.commitHash, queueSize: this.queue.length },
+      'Enrichment job enqueued',
+    );
+
+    this.processNext();
+  }
+
+  /**
+   * Graceful shutdown: discard pending queue and wait for in-flight jobs only.
+   *
+   * Bounded shutdown time is more important than processing all pending
+   * enrichments. Enrichment is best-effort metadata and must never delay
+   * daemon shutdown materially. Pending jobs are counted as dropped.
+   */
+  async shutdown(): Promise<void> {
+    this.shuttingDown = true;
+
+    // Discard pending jobs — enrichment is best-effort and must not delay shutdown
+    if (this.queue.length > 0) {
+      const pendingCount = this.queue.length;
+      this.droppedCount += pendingCount;
+      this.queue = [];
+      log.info({ discarded: pendingCount, droppedCount: this.droppedCount }, 'Enrichment queue shutting down, discarded pending jobs');
+    }
+
+    // Wait for any in-flight workers to finish
+    if (this.inFlightPromises.size > 0) {
+      log.debug({ inFlight: this.inFlightPromises.size }, 'Waiting for in-flight enrichment jobs');
+      await Promise.all(this.inFlightPromises);
+    }
+
+    log.info(
+      { succeeded: this.succeededCount, failed: this.failedCount, dropped: this.droppedCount },
+      'Enrichment queue shut down',
+    );
+  }
+
+  /** @internal Test-only: get queue size */
+  _getQueueSize(): number {
+    return this.queue.length;
+  }
+
+  /** @internal Test-only: get dropped count */
+  _getDroppedCount(): number {
+    return this.droppedCount;
+  }
+
+  /** @internal Test-only: get succeeded count */
+  _getSucceededCount(): number {
+    return this.succeededCount;
+  }
+
+  /** @internal Test-only: get failed count */
+  _getFailedCount(): number {
+    return this.failedCount;
+  }
+
+  /** @internal Test-only: get active workers */
+  _getActiveWorkers(): number {
+    return this.activeWorkers;
+  }
+
+  private processNext(): void {
+    if (this.shuttingDown) return;
+    if (this.activeWorkers >= this.maxConcurrency) return;
+    if (this.queue.length === 0) return;
+
+    const job = this.queue.shift()!;
+    this.activeWorkers++;
+
+    const promise = this.executeJob(job).finally(() => {
+      this.activeWorkers--;
+      this.inFlightPromises.delete(promise);
+      // Try to process next job after this one completes
+      this.processNext();
+    });
+
+    this.inFlightPromises.add(promise);
+  }
+
+  private async executeJob(job: InternalJob): Promise<void> {
+    job.attempts++;
+
+    const controller = new AbortController();
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    try {
+      // Race the enrichment work against a timeout.
+      // When the timeout wins, controller.abort() kills in-progress work,
+      // causing doEnrichment to reject with an AbortError. Since Promise.race
+      // has already settled with the timeout error, that rejection is orphaned.
+      // The .catch() swallows it to prevent an unhandled promise rejection.
+      const enrichmentPromise = this.doEnrichment(job, controller.signal);
+      enrichmentPromise.catch(() => {
+        // Intentionally swallowed — the timeout branch already handled the error
+      });
+      await Promise.race([
+        enrichmentPromise,
+        new Promise<never>((_, reject) => {
+          timeoutHandle = setTimeout(() => {
+            controller.abort();
+            reject(new Error('Enrichment job timed out'));
+          }, this.jobTimeoutMs);
+        }),
+      ]);
+      this.succeededCount++;
+      log.debug(
+        { commitHash: job.commitHash, attempts: job.attempts },
+        'Enrichment job completed',
+      );
+    } catch (err) {
+      controller.abort();
+      const isTimeout = err instanceof Error && err.message === 'Enrichment job timed out';
+      if (job.attempts <= this.maxRetries) {
+        // Exponential backoff: 1s, 2s, 4s, ...
+        const backoffMs = 1000 * Math.pow(2, job.attempts - 1);
+        log.debug(
+          { commitHash: job.commitHash, attempts: job.attempts, backoffMs, timedOut: isTimeout, err },
+          isTimeout ? 'Enrichment job timed out, scheduling retry' : 'Enrichment job failed, scheduling retry',
+        );
+        await new Promise<void>((resolve) => setTimeout(resolve, backoffMs));
+
+        if (!this.shuttingDown) {
+          // Re-enqueue at front for retry (don't count against queue limit)
+          this.queue.unshift(job);
+          this.processNext();
+        } else {
+          // Can't retry during shutdown — count as failed
+          this.failedCount++;
+        }
+        return;
+      }
+
+      this.failedCount++;
+      log.warn(
+        { commitHash: job.commitHash, attempts: job.attempts, timedOut: isTimeout, err },
+        isTimeout ? 'Enrichment job timed out after max retries' : 'Enrichment job failed after max retries',
+      );
+    } finally {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+    }
+  }
+
+  /**
+   * Perform the actual enrichment work.
+   *
+   * Currently a no-op placeholder that writes a scaffold JSON note
+   * to prove the plumbing works. Future: call LLM to generate a
+   * rich commit description and write it as a git note.
+   *
+   * Accepts an AbortSignal so callers (e.g. timeout) can cancel
+   * in-progress work and prevent zombie enrichment jobs.
+   */
+  private async doEnrichment(job: InternalJob, signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) return;
+
+    const note = JSON.stringify({
+      enriched: true,
+      trigger: job.context.trigger,
+      filesChanged: job.context.changedFiles.length,
+      timestamp: job.context.timestampMs,
+      sessionId: job.context.sessionId,
+      turnNumber: job.context.turnNumber,
+    });
+
+    if (signal?.aborted) return;
+    await job.gitService.writeNote(job.commitHash, note, signal);
+  }
+}
+
+/** Singleton enrichment service instance. */
+let enrichmentService: CommitEnrichmentService | null = null;
+
+/**
+ * Get the global enrichment service singleton.
+ * Created lazily on first access.
+ */
+export function getEnrichmentService(): CommitEnrichmentService {
+  if (!enrichmentService) {
+    enrichmentService = new CommitEnrichmentService();
+  }
+  return enrichmentService;
+}
+
+/**
+ * @internal Test-only: reset the singleton
+ */
+export function _resetEnrichmentService(): void {
+  enrichmentService = null;
+}

package/src/workspace/commit-message-provider.ts

@@ -0,0 +1,95 @@
+/**
+ * Abstraction for generating commit messages across different triggers.
+ *
+ * Provides a seam for future LLM-powered enrichment without changing
+ * the synchronous commit path.
+ */
+
+export interface CommitContext {
+  workspaceDir: string;
+  trigger: 'turn' | 'heartbeat' | 'shutdown';
+  sessionId?: string;
+  turnNumber?: number;
+  changedFiles: string[];
+  timestampMs: number;
+  /** Optional reason string (used by heartbeat to describe threshold exceeded). */
+  reason?: string;
+}
+
+export interface CommitMessageResult {
+  message: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CommitMessageProvider {
+  /** Build a commit message synchronously for immediate use. */
+  buildImmediateMessage(ctx: CommitContext): CommitMessageResult;
+  /** Optional: enqueue async enrichment after commit succeeds. */
+  enqueueEnrichment?(ctx: CommitContext & { commitHash: string }): Promise<void>;
+}
+
+/**
+ * Build a short summary of what changed from a list of file paths.
+ */
+export 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`;
+}
+
+/**
+ * Default deterministic commit message provider.
+ *
+ * Produces identical output to the pre-refactor inline logic in
+ * turn-commit.ts and heartbeat-service.ts.
+ */
+export class DefaultCommitMessageProvider implements CommitMessageProvider {
+  buildImmediateMessage(ctx: CommitContext): CommitMessageResult {
+    switch (ctx.trigger) {
+      case 'turn':
+        return this.buildTurnMessage(ctx);
+      case 'heartbeat':
+        return this.buildHeartbeatMessage(ctx);
+      case 'shutdown':
+        return this.buildShutdownMessage(ctx);
+    }
+  }
+
+  private buildTurnMessage(ctx: CommitContext): CommitMessageResult {
+    const summary = buildChangeSummary(ctx.changedFiles);
+    const timestamp = new Date(ctx.timestampMs).toISOString();
+    const message = [
+      `Turn: ${summary}`,
+      '',
+      `Session: ${ctx.sessionId}`,
+      `Turn: ${ctx.turnNumber}`,
+      `Timestamp: ${timestamp}`,
+      `Files: ${ctx.changedFiles.length} changed`,
+    ].join('\n');
+    return { message };
+  }
+
+  private buildHeartbeatMessage(ctx: CommitContext): CommitMessageResult {
+    const totalChanges = ctx.changedFiles.length;
+    const reason = ctx.reason ?? `${totalChanges} files`;
+    return {
+      message: `auto-commit: heartbeat safety net (${totalChanges} files, ${reason})`,
+      metadata: { trigger: 'heartbeat', timestamp: ctx.timestampMs },
+    };
+  }
+
+  private buildShutdownMessage(ctx: CommitContext): CommitMessageResult {
+    const totalChanges = ctx.changedFiles.length;
+    return {
+      message: `auto-commit: shutdown safety net (${totalChanges} files)`,
+      metadata: { trigger: 'shutdown', timestamp: ctx.timestampMs },
+    };
+  }
+}