macro-agent 0.2.4 → 0.2.6

package/src/workspace/git-cascade-adapter.ts

@@ -1,1213 +0,0 @@
-/**
- * git-cascade Adapter
- *
- * Wraps git-cascade's MultiAgentRepoTracker to integrate with macro-agent's
- * event system and provide a simplified interface for workspace management.
- *
- * @module workspace/git-cascade-adapter
- */
-
-import Database from 'better-sqlite3';
-import {
-  MultiAgentRepoTracker,
-  type TrackerOptions,
-  type Stream,
-  type StreamStatus,
-  type StreamNode,
-  type CreateStreamOptions,
-  type ForkStreamOptions,
-  type MergeStreamOptions,
-  type MergeResult,
-  type RebaseOntoStreamOptions,
-  type RebaseResult,
-  type ConflictStrategy,
-  type ConflictRecord,
-  type CreateConflictOptions,
-  type AgentWorktree,
-  type CreateWorktreeOptions,
-  type WorkerTask,
-  type CreateTaskOptions,
-  type StartTaskOptions,
-  type CompleteTaskOptions,
-  type StartTaskResult,
-  type CompleteTaskResult,
-  type ListTasksOptions,
-  type CleanupWorkerBranchesOptions,
-  type CleanupResult,
-  type Checkpoint,
-  type Change,
-  type ChangeStatus,
-  workerTasks,
-  diffStacks,
-  mergeQueue as mergeQueueModule,
-  reconcile as reconcileModule,
-  cascade as cascadeModule,
-  matchCascadeSuffix,
-  type StreamOpenedParams,
-  type StreamCommittedParams,
-  type StreamMergedParams,
-  type StreamConflictedParams,
-  type StreamAbandonedParams,
-  type CascadeRebasedParams,
-  type CascadeCompletedParams,
-  type QueueAddedParams,
-  type QueueReadyParams,
-  type QueueCancelledParams,
-  type QueueRemovedParams,
-} from 'git-cascade';
-// git-cascade 0.0.3+ exposes both events (via `emit` callback) and the
-// `cascade` namespace for cascadeRebase. All v3 primitives are now reachable.
-import type { GitCascadeConfig } from './config.js';
-import { DEFAULT_GIT_CASCADE_CONFIG } from './config.js';
-
-/**
- * Event types emitted by GitCascadeAdapter.
- *
- * Grouped by source:
- * - `stream:*` — from git-cascade `x-cascade/stream.*` events + local emits
- * - `worktree:*`, `task:*` — local emits (macro-agent-only concepts)
- * - `change:*` — change-id lifecycle from git-cascade
- * - `cascade:*` — cascadeRebase completion
- * - `conflict:*` — conflict lifecycle
- * - `mergeQueue:*` — built-in merge queue lifecycle
- */
-export type GitCascadeEventType =
-  | 'stream:created'        // mapped from git-cascade stream.opened
-  | 'stream:updated'        // local (updateStream)
-  | 'stream:forked'         // local (forkStream)
-  | 'stream:committed'      // mapped from git-cascade stream.committed
-  | 'stream:merged'         // mapped from git-cascade stream.merged
-  | 'stream:conflicted'     // mapped from git-cascade stream.conflicted
-  | 'stream:abandoned'      // mapped from git-cascade stream.abandoned
-  | 'stream:paused'         // local (pauseStream) + cascade emit
-  | 'stream:resumed'        // local (resumeStream) + cascade emit
-  | 'stream:rolled_back'    // cascade emit (rollbackN, rollbackToOperation, rollbackToForkPoint)
-  | 'worktree:created'
-  | 'worktree:deallocated'
-  | 'task:created'
-  | 'task:started'
-  | 'task:completed'
-  | 'task:abandoned'
-  | 'change:merged'
-  | 'change:dropped'
-  | 'stream:pushed'         // local — emitted by direct-push/optimistic-push landing strategies
-  | 'cascade:rebased'       // mapped from git-cascade cascade.rebased
-  | 'cascade:completed'     // mapped from git-cascade cascade.completed
-  | 'conflict:created'
-  | 'conflict:resolved'
-  | 'mergeQueue:added'
-  | 'mergeQueue:ready'
-  | 'mergeQueue:cancelled'
-  | 'mergeQueue:removed';
-
-/**
- * Event payload for git-cascade events
- */
-export interface GitCascadeEvent {
-  type: GitCascadeEventType;
-  timestamp: number;
-  data: Record<string, unknown>;
-}
-
-/**
- * Callback for git-cascade events
- */
-export type GitCascadeEventCallback = (event: GitCascadeEvent) => void;
-
-/**
- * GitCascadeAdapter wraps MultiAgentRepoTracker for macro-agent integration.
- *
- * Key responsibilities:
- * - Initialize tracker with shared or dedicated database
- * - Emit events on tracker operations
- * - Provide simplified API for workspace management
- */
-export class GitCascadeAdapter {
-  private readonly tracker: MultiAgentRepoTracker;
-  private readonly config: Required<
-    Pick<GitCascadeConfig, 'enabled' | 'tablePrefix' | 'verbose' | 'skipRecovery'>
-  > & { repoPath: string };
-  private readonly eventListeners: Set<GitCascadeEventCallback> = new Set();
-  private readonly ownsDb: boolean;
-
-  /**
-   * Create a new GitCascadeAdapter.
-   *
-   * @param config - git-cascade configuration
-   */
-  constructor(config: GitCascadeConfig) {
-    const mergedConfig = {
-      ...DEFAULT_GIT_CASCADE_CONFIG,
-      ...config,
-      repoPath: config.repoPath ?? process.cwd(),
-    };
-
-    this.config = {
-      enabled: mergedConfig.enabled ?? true,
-      repoPath: mergedConfig.repoPath,
-      tablePrefix: mergedConfig.tablePrefix ?? 'git_cascade_',
-      verbose: mergedConfig.verbose ?? false,
-      skipRecovery: mergedConfig.skipRecovery ?? false,
-    };
-
-    // Determine if we own the database connection
-    this.ownsDb = !config.db;
-
-    const trackerOptions: TrackerOptions = {
-      repoPath: this.config.repoPath,
-      tablePrefix: this.config.tablePrefix,
-      verbose: this.config.verbose,
-      skipRecovery: this.config.skipRecovery,
-      // Wire git-cascade's native event emitter (0.0.2+) so stream lifecycle
-      // events are re-published through our own onEvent channel.
-      emit: (method: string, params: unknown) => this.forwardCascadeEvent(method, params),
-    };
-
-    if (config.db) {
-      trackerOptions.db = config.db;
-    } else if (config.dbPath) {
-      trackerOptions.dbPath = config.dbPath;
-    }
-    // If neither db nor dbPath provided, tracker uses default path
-
-    this.tracker = new MultiAgentRepoTracker(trackerOptions);
-  }
-
-
-  /**
-   * Get whether the adapter is enabled.
-   */
-  get enabled(): boolean {
-    return this.config.enabled;
-  }
-
-  /**
-   * Get the repository path.
-   */
-  get repoPath(): string {
-    return this.config.repoPath;
-  }
-
-  /**
-   * Get the underlying database connection.
-   * Use with caution - prefer adapter methods for operations.
-   */
-  get db(): Database.Database {
-    return this.tracker.db;
-  }
-
-  /**
-   * Get the underlying tracker.
-   * Use with caution - prefer adapter methods for operations.
-   */
-  get rawTracker(): MultiAgentRepoTracker {
-    return this.tracker;
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Event System
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Subscribe to git-cascade events.
-   *
-   * @param callback - Function called when events occur
-   * @returns Unsubscribe function
-   */
-  onEvent(callback: GitCascadeEventCallback): () => void {
-    this.eventListeners.add(callback);
-    return () => this.eventListeners.delete(callback);
-  }
-
-  /**
-   * Emit an event to all listeners.
-   */
-  private emit(type: GitCascadeEventType, data: Record<string, unknown>): void {
-    const event: GitCascadeEvent = {
-      type,
-      timestamp: Date.now(),
-      data,
-    };
-    for (const listener of this.eventListeners) {
-      try {
-        listener(event);
-      } catch (error) {
-        console.error('[GitCascadeAdapter] Event listener error:', error);
-      }
-    }
-  }
-
-  /**
-   * Forward events emitted by git-cascade (`x-cascade/stream.*`) into our
-   * structured `GitCascadeEvent` stream. Called via the `emit` callback wired
-   * into the tracker constructor.
-   *
-   * Note: `stream.opened` is mapped to `stream:created`. The local
-   * wrapper methods still emit their own events so consumers don't miss out
-   * on operations that don't round-trip through git-cascade's emit (e.g.,
-   * updateStream, pauseStream, mergeQueue events).
-   */
-  private forwardCascadeEvent(method: string, params: unknown): void {
-    const suffix = matchCascadeSuffix(method);
-    if (!suffix) return;
-
-    // Widen to `string` so case labels for suffixes not yet in the installed
-    // git-cascade version (e.g. `stream.paused`, `stream.resumed`,
-    // `stream.rolled_back` — added after 0.0.7) still compile. The runtime
-    // value is always a string either way; this is a version-skew shim.
-    switch (suffix as string) {
-      case 'stream.opened': {
-        const p = params as StreamOpenedParams;
-        this.emit('stream:created', {
-          streamId: p.stream_id,
-          name: p.name,
-          agentId: p.agent_id,
-          baseCommit: p.base_commit,
-          parentStream: p.parent_stream,
-          branchName: p.branch_name,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'stream.committed': {
-        const p = params as StreamCommittedParams;
-        this.emit('stream:committed', {
-          streamId: p.stream_id,
-          commit: p.commit_hash,
-          changeId: p.change_id,
-          agentId: p.agent_id,
-          messageSummary: p.message_summary,
-          filesTouched: p.files_touched,
-          parentCommit: p.parent_commit,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'stream.merged': {
-        const p = params as StreamMergedParams;
-        this.emit('stream:merged', {
-          sourceStreamId: p.source_stream_id,
-          targetStreamId: p.target_stream_id,
-          mergeCommit: p.merge_commit,
-          agentId: p.agent_id,
-          strategy: p.strategy,
-          sourceCommit: p.source_commit,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'stream.conflicted': {
-        const p = params as StreamConflictedParams;
-        this.emit('stream:conflicted', {
-          streamId: p.stream_id,
-          conflictId: p.conflict_id,
-          conflictedFiles: p.conflicted_files,
-          agentId: p.agent_id,
-          conflictingCommit: p.conflicting_commit,
-          targetCommit: p.target_commit,
-          source: p.source,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'stream.conflict_resolved': {
-        const p = params as import('git-cascade').StreamConflictResolvedParams;
-        this.emit('conflict:resolved', {
-          streamId: p.stream_id,
-          conflictId: p.conflict_id,
-          resolutionMethod: p.resolution_method,
-          resolvedBy: p.resolved_by,
-          resolutionSummary: p.resolution_summary,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'stream.abandoned': {
-        const p = params as StreamAbandonedParams;
-        this.emit('stream:abandoned', {
-          streamId: p.stream_id,
-          reason: p.reason,
-          cascade: p.cascade,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'cascade.rebased': {
-        const p = params as CascadeRebasedParams;
-        this.emit('cascade:rebased', {
-          streamId: p.stream_id,
-          agentId: p.agent_id,
-          triggeredByStreamId: p.triggered_by_stream_id,
-          triggeredByAgentId: p.triggered_by_agent_id,
-          newBaseCommit: p.new_base_commit,
-          newHead: p.new_head,
-          newCommits: p.new_commits,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'cascade.completed': {
-        const p = params as CascadeCompletedParams;
-        this.emit('cascade:completed', {
-          rootStreamId: p.root_stream_id,
-          agentId: p.agent_id,
-          strategy: p.strategy,
-          updatedStreams: p.updated_streams,
-          failedStreams: p.failed_streams,
-          skippedStreams: p.skipped_streams,
-          deferredStreams: p.deferred_streams,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'queue.added': {
-        const p = params as QueueAddedParams;
-        this.emit('mergeQueue:added', {
-          entryId: p.entry_id,
-          streamId: p.stream_id,
-          targetBranch: p.target_branch,
-          metadata: p.metadata,
-        });
-        break;
-      }
-      case 'queue.ready': {
-        const p = params as QueueReadyParams;
-        this.emit('mergeQueue:ready', {
-          entryId: p.entry_id,
-          streamId: p.stream_id,
-          targetBranch: p.target_branch,
-        });
-        break;
-      }
-      case 'queue.cancelled': {
-        const p = params as QueueCancelledParams;
-        this.emit('mergeQueue:cancelled', {
-          entryId: p.entry_id,
-          streamId: p.stream_id,
-          targetBranch: p.target_branch,
-          reason: p.reason,
-        });
-        break;
-      }
-      case 'queue.removed': {
-        const p = params as QueueRemovedParams;
-        this.emit('mergeQueue:removed', {
-          entryId: p.entry_id,
-          streamId: p.stream_id,
-          targetBranch: p.target_branch,
-          outcome: p.outcome,
-        });
-        break;
-      }
-      case 'stream.paused': {
-        // Tracker fires stream.paused after pauseStream. The adapter also
-        // emits stream:paused locally in its pauseStream() wrapper — the
-        // bridge uses the local event (not this cascade-forwarded one) for
-        // the MAP translation, so this case is mainly to keep the switch
-        // exhaustive. No double-emit: the bridge deduplicates by event type.
-        break;
-      }
-      case 'stream.resumed': {
-        // Same as stream.paused — adapter.resumeStream() fires the local event.
-        break;
-      }
-      case 'stream.rolled_back': {
-        const p = params as { stream_id: string; strategy?: string; target?: string | number; new_head?: string };
-        this.emit('stream:rolled_back', {
-          streamId: p.stream_id,
-          strategy: p.strategy,
-          target: p.target,
-          newHead: p.new_head,
-        });
-        break;
-      }
-    }
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Stream Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Create a new stream (integration branch).
-   *
-   * Note: `stream:created` is emitted by the cascade event forwarder via
-   * git-cascade's `x-cascade/stream.opened`. We don't double-emit here.
-   *
-   * @param options - Stream creation options
-   * @returns Stream ID
-   */
-  createStream(options: CreateStreamOptions): string {
-    return this.tracker.createStream(options);
-  }
-
-  /**
-   * Get a stream by ID.
-   */
-  getStream(streamId: string): Stream | null {
-    return this.tracker.getStream(streamId);
-  }
-
-  /**
-   * List streams with optional filters.
-   */
-  listStreams(options?: { agentId?: string; status?: StreamStatus }): Stream[] {
-    return this.tracker.listStreams(options);
-  }
-
-  /**
-   * Update a stream.
-   */
-  updateStream(
-    streamId: string,
-    updates: Partial<Pick<Stream, 'name' | 'status' | 'metadata'>>
-  ): void {
-    this.tracker.updateStream(streamId, updates);
-    this.emit('stream:updated', { streamId, updates });
-  }
-
-  /**
-   * Abandon a stream.
-   *
-   * Note: `stream:abandoned` is emitted by the cascade event forwarder.
-   */
-  abandonStream(
-    streamId: string,
-    options?: { reason?: string; cascade?: boolean }
-  ): void {
-    this.tracker.abandonStream(streamId, options);
-  }
-
-  /**
-   * Get the git branch name for a stream.
-   */
-  getStreamBranchName(streamId: string): string {
-    return this.tracker.getStreamBranchName(streamId);
-  }
-
-  /**
-   * Get the HEAD commit of a stream.
-   */
-  getStreamHead(streamId: string): string {
-    return this.tracker.getStreamHead(streamId);
-  }
-
-  /**
-   * Fork a child stream off a parent.
-   */
-  forkStream(options: ForkStreamOptions): string {
-    const streamId = this.tracker.forkStream(options);
-    this.emit('stream:forked', {
-      streamId,
-      parentStreamId: options.parentStreamId,
-      name: options.name,
-      agentId: options.agentId,
-    });
-    return streamId;
-  }
-
-  /**
-   * Merge source stream into target stream.
-   *
-   * Note: `stream:merged` is emitted by the cascade event forwarder on success.
-   * On conflict, `stream:conflicted` is also forwarded.
-   */
-  mergeStream(options: MergeStreamOptions): MergeResult {
-    return this.tracker.mergeStream(options);
-  }
-
-  /**
-   * Rebase a stream onto its parent to pick up new commits.
-   */
-  syncWithParent(
-    streamId: string,
-    agentId: string,
-    worktree: string,
-    onConflict?: ConflictStrategy
-  ): RebaseResult {
-    return this.tracker.syncWithParent(streamId, agentId, worktree, onConflict);
-  }
-
-  /**
-   * Rebase a stream onto a specific target stream.
-   */
-  rebaseOntoStream(options: RebaseOntoStreamOptions): RebaseResult {
-    return this.tracker.rebaseOntoStream(options);
-  }
-
-  /**
-   * Async version of rebaseOntoStream — supports async conflict handlers.
-   */
-  rebaseOntoStreamAsync(options: RebaseOntoStreamOptions): Promise<RebaseResult> {
-    return this.tracker.rebaseOntoStreamAsync(options);
-  }
-
-  /**
-   * Pause a stream (halt work without abandoning).
-   */
-  pauseStream(streamId: string, reason?: string): void {
-    this.tracker.pauseStream(streamId, reason);
-    this.emit('stream:paused', { streamId, reason });
-  }
-
-  /**
-   * Resume a paused stream.
-   */
-  resumeStream(streamId: string): void {
-    this.tracker.resumeStream(streamId);
-    this.emit('stream:resumed', { streamId });
-  }
-
-  /**
-   * Track an existing branch as a stream (local mode — no new `stream/<id>` branch).
-   */
-  trackExistingBranch(options: Parameters<MultiAgentRepoTracker['trackExistingBranch']>[0]): string {
-    return this.tracker.trackExistingBranch(options);
-  }
-
-  /**
-   * Get stream hierarchy as a tree.
-   */
-  getStreamHierarchy(rootStreamId?: string): StreamNode | StreamNode[] {
-    return this.tracker.getStreamHierarchy(rootStreamId);
-  }
-
-  /**
-   * Get child streams (direct children only).
-   */
-  getChildStreams(streamId: string): Stream[] {
-    return this.tracker.getChildStreams(streamId);
-  }
-
-  /**
-   * Find the common ancestor of two streams.
-   */
-  findCommonAncestor(streamIdA: string, streamIdB: string): string {
-    return this.tracker.findCommonAncestor(streamIdA, streamIdB);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Stream Dependencies
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Declare that one stream depends on another.
-   */
-  addDependency(streamId: string, dependsOnId: string): void {
-    this.tracker.addDependency(streamId, dependsOnId);
-  }
-
-  /**
-   * Remove a dependency declaration.
-   */
-  removeDependency(streamId: string, dependsOnId: string): void {
-    this.tracker.removeDependency(streamId, dependsOnId);
-  }
-
-  /**
-   * Get direct dependencies of a stream.
-   */
-  getDependencies(streamId: string): string[] {
-    return this.tracker.getDependencies(streamId);
-  }
-
-  /**
-   * Get direct dependents of a stream.
-   */
-  getDependents(streamId: string): string[] {
-    return this.tracker.getDependents(streamId);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Cascade Rebase (git-cascade 0.0.3+)
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Cascade-rebase all dependents of a root stream.
-   *
-   * Propagates rebases through the dependency graph. Uses a callback-based
-   * worktree provider so not every dependent needs a pre-allocated worktree.
-   *
-   * @param options - Cascade options including root stream, agent id, and worktree provider
-   * @returns CascadeResult with updated/failed/skipped stream lists
-   */
-  cascadeRebase(
-    options: cascadeModule.CascadeRebaseOptions
-  ): ReturnType<typeof cascadeModule.cascadeRebase> {
-    // Use tracker.cascadeRebase which threads the tracker's emit + eventPrefix
-    // into the cascade walk so `cascade.rebased` (per dependent) and
-    // `cascade.completed` (at end) both round-trip through our
-    // forwardCascadeEvent. No manual emit needed — events are driven by
-    // git-cascade 0.0.4+ from inside the walk.
-    return this.tracker.cascadeRebase(options);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Worktree Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Create a worktree for an agent.
-   *
-   * @param options - Worktree creation options
-   * @returns Created worktree info
-   */
-  createWorktree(options: CreateWorktreeOptions): AgentWorktree {
-    const worktree = this.tracker.createWorktree(options);
-    this.emit('worktree:created', { ...worktree });
-    return worktree;
-  }
-
-  /**
-   * Get a worktree by agent ID.
-   */
-  getWorktree(agentId: string): AgentWorktree | null {
-    return this.tracker.getWorktree(agentId);
-  }
-
-  /**
-   * List all worktrees.
-   */
-  listWorktrees(): AgentWorktree[] {
-    return this.tracker.listWorktrees();
-  }
-
-  /**
-   * Update the stream associated with a worktree.
-   */
-  updateWorktreeStream(agentId: string, streamId: string | null): void {
-    this.tracker.updateWorktreeStream(agentId, streamId);
-  }
-
-  /**
-   * Deallocate a worktree.
-   */
-  deallocateWorktree(agentId: string): void {
-    this.tracker.deallocateWorktree(agentId);
-    this.emit('worktree:deallocated', { agentId });
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Worker Task Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Create a worker task under a stream.
-   *
-   * @param options - Task creation options
-   * @returns Task ID
-   */
-  createTask(options: CreateTaskOptions): string {
-    const taskId = this.tracker.createTask(options);
-    this.emit('task:created', { taskId, ...options });
-    return taskId;
-  }
-
-  /**
-   * Get a task by ID.
-   */
-  getTask(taskId: string): WorkerTask | null {
-    return this.tracker.getTask(taskId);
-  }
-
-  /**
-   * List tasks for a stream.
-   */
-  listTasks(streamId: string, options?: ListTasksOptions): WorkerTask[] {
-    return this.tracker.listTasks(streamId, options);
-  }
-
-  /**
-   * Start a task - assigns agent and creates worker branch.
-   *
-   * @param options - Start task options
-   * @returns Branch name and start commit
-   */
-  startTask(options: StartTaskOptions): StartTaskResult {
-    const result = this.tracker.startTask(options);
-    this.emit('task:started', {
-      taskId: options.taskId,
-      agentId: options.agentId,
-      branchName: result.branchName,
-      startCommit: result.startCommit,
-    });
-    return result;
-  }
-
-  /**
-   * Complete a task - merges worker branch to stream.
-   *
-   * @param options - Complete task options
-   * @returns Merge result
-   */
-  completeTask(options: CompleteTaskOptions): CompleteTaskResult {
-    const result = this.tracker.completeTask(options);
-    this.emit('task:completed', { taskId: options.taskId, ...result });
-    return result;
-  }
-
-  /**
-   * Abandon a task.
-   *
-   * @param taskId - Task ID
-   * @param options - Options
-   */
-  abandonTask(taskId: string, options?: { deleteBranch?: boolean }): void {
-    this.tracker.abandonTask(taskId, options);
-    this.emit('task:abandoned', { taskId, ...options });
-  }
-
-  /**
-   * Release a task back to 'open' status.
-   */
-  releaseTask(taskId: string): void {
-    this.tracker.releaseTask(taskId);
-  }
-
-  /**
-   * Detect conflicts for a task before completing.
-   *
-   * @param taskId - Task ID
-   * @param worktree - Worktree path
-   * @returns Array of conflicting file paths, empty if no conflicts
-   */
-  detectTaskConflicts(taskId: string, worktree: string): string[] {
-    return workerTasks.detectTaskConflicts(
-      this.tracker.db,
-      this.config.repoPath,
-      taskId,
-      worktree
-    );
-  }
-
-  /**
-   * Recover stale tasks that have been in_progress too long.
-   *
-   * @param thresholdMs - Tasks older than this are considered stale
-   * @returns Result with released task IDs
-   */
-  recoverStaleTasks(thresholdMs: number = 60 * 60 * 1000): { released: string[] } {
-    return workerTasks.recoverStaleTasks(this.tracker.db, thresholdMs);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Checkpoint Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Create checkpoints for commits made during a task.
-   *
-   * Creates a checkpoint for each commit between the task's startCommit and
-   * the current HEAD of the task's stream. This captures the work done during
-   * the task for future review and merge workflows.
-   *
-   * @param taskId - Task ID to create checkpoints for
-   * @param agentId - Agent ID (used as createdBy)
-   * @returns Array of created checkpoints
-   */
-  createCheckpointsForTask(taskId: string, agentId: string): Checkpoint[] {
-    const task = this.getTask(taskId);
-    if (!task) {
-      console.warn(`[GitCascadeAdapter] Task not found: ${taskId}`);
-      return [];
-    }
-
-    if (!task.streamId) {
-      console.warn(`[GitCascadeAdapter] Task ${taskId} has no streamId`);
-      return [];
-    }
-
-    if (!task.startCommit) {
-      console.warn(`[GitCascadeAdapter] Task ${taskId} has no startCommit`);
-      return [];
-    }
-
-    try {
-      // Create checkpoints from task's startCommit to stream's current HEAD
-      const checkpoints = diffStacks.createCheckpointsFromStream(
-        this.tracker.db,
-        this.config.repoPath,
-        task.streamId,
-        {
-          from: task.startCommit,
-          createdBy: agentId,
-        }
-      );
-
-      return checkpoints;
-    } catch (error) {
-      console.error(
-        `[GitCascadeAdapter] Failed to create checkpoints for task ${taskId}:`,
-        error
-      );
-      return [];
-    }
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Commit Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Commit changes in a worktree with Change tracking.
-   *
-   * @param options - Commit options
-   * @returns Commit hash and change ID
-   */
-  commitChanges(options: {
-    streamId: string;
-    agentId: string;
-    worktree: string;
-    message: string;
-    /**
-     * Optional metadata threaded verbatim to git-cascade's
-     * `x-cascade/stream.committed` event. Use `{ task_ref: { resource_id,
-     * node_id } }` to bind this commit to an external task (see
-     * `SpawnAgentOptions.taskRef`). Each commit can carry a distinct ref —
-     * useful for workers handling multiple sub-tasks within one session.
-     */
-    metadata?: Record<string, unknown>;
-  }): { commit: string; changeId: string } {
-    return this.tracker.commitChanges(options);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Maintenance Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Clean up old worker branches.
-   *
-   * Deletes branches for:
-   * - Completed tasks older than threshold (default 24h)
-   * - Abandoned tasks
-   * - Orphaned branches (no task record)
-   *
-   * @param options - Cleanup options
-   * @returns Deleted branches and any errors
-   */
-  cleanupWorkerBranches(options?: CleanupWorkerBranchesOptions): CleanupResult {
-    return workerTasks.cleanupWorkerBranches(
-      this.tracker.db,
-      this.config.repoPath,
-      options
-    );
-  }
-
-  /**
-   * Delete a specific worker branch.
-   *
-   * @param branchName - Branch name to delete
-   * @returns true if deleted, false if branch didn't exist
-   */
-  deleteWorkerBranch(branchName: string): boolean {
-    try {
-      const { execSync } = require('child_process');
-      execSync(`git branch -D "${branchName}"`, {
-        cwd: this.config.repoPath,
-        stdio: 'pipe',
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Change Operations (Change-Id tracking)
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Get a change by ID.
-   */
-  getChange(changeId: string): Change | null {
-    return this.tracker.getChange(changeId);
-  }
-
-  /**
-   * Get a change by its current commit hash.
-   */
-  getChangeByCommit(commit: string): Change | null {
-    return this.tracker.getChangeByCommit(commit);
-  }
-
-  /**
-   * Get a change by any of its historical commit hashes (survives rebases).
-   */
-  getChangeByHistoricalCommit(commit: string): Change | null {
-    return this.tracker.getChangeByHistoricalCommit(commit);
-  }
-
-  /**
-   * List changes for a stream, optionally filtered by status.
-   */
-  getChangesForStream(
-    streamId: string,
-    options?: { status?: ChangeStatus }
-  ): Change[] {
-    return this.tracker.getChangesForStream(streamId, options);
-  }
-
-  /**
-   * Mark changes as merged.
-   */
-  markChangesMerged(changeIds: string[]): void {
-    this.tracker.markChangesMerged(changeIds);
-    for (const id of changeIds) {
-      this.emit('change:merged', { changeId: id });
-    }
-  }
-
-  /**
-   * Mark a single change as dropped.
-   */
-  markChangeDropped(changeId: string): void {
-    this.tracker.markChangeDropped(changeId);
-    this.emit('change:dropped', { changeId });
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Merge Queue (git-cascade built-in)
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Add a stream to the merge queue. Local `mergeQueue:added` event fires
-   * via forwardCascadeEvent (git-cascade 0.0.7+ emits queue.added natively).
-   */
-  addToMergeQueue(options: mergeQueueModule.AddToQueueOptions): string {
-    return this.tracker.addToMergeQueue(options);
-  }
-
-  /**
-   * Get a merge queue entry by id.
-   */
-  getMergeQueueEntry(entryId: string): mergeQueueModule.MergeQueueEntry | null {
-    return this.tracker.getMergeQueueEntry(entryId);
-  }
-
-  /**
-   * List merge queue entries with optional filters.
-   */
-  listMergeQueue(
-    options?: {
-      targetBranch?: string;
-      status?: mergeQueueModule.MergeQueueStatus | mergeQueueModule.MergeQueueStatus[];
-    }
-  ): mergeQueueModule.MergeQueueEntry[] {
-    return this.tracker.getMergeQueue(options);
-  }
-
-  /**
-   * Mark a queue entry as ready to merge. Local `mergeQueue:ready` event
-   * fires via forwardCascadeEvent (git-cascade 0.0.7+).
-   */
-  markMergeQueueReady(entryId: string): void {
-    this.tracker.markMergeQueueReady(entryId);
-  }
-
-  /**
-   * Cancel a queue entry. Local `mergeQueue:cancelled` event fires via
-   * forwardCascadeEvent (git-cascade 0.0.7+).
-   */
-  cancelMergeQueueEntry(entryId: string): void {
-    this.tracker.cancelMergeQueueEntry(entryId);
-  }
-
-  /**
-   * Remove a queue entry. Local `mergeQueue:removed` event fires via
-   * forwardCascadeEvent (git-cascade 0.0.7+).
-   */
-  removeFromMergeQueue(entryId: string): void {
-    this.tracker.removeFromMergeQueue(entryId);
-  }
-
-  /**
-   * Get the next entry to process for a target branch.
-   */
-  getNextToMerge(targetBranch?: string): mergeQueueModule.MergeQueueEntry | null {
-    return this.tracker.getNextToMerge(targetBranch);
-  }
-
-  /**
-   * Process the merge queue — drains ready entries per provided handler.
-   */
-  processMergeQueue(
-    options: mergeQueueModule.ProcessQueueOptions
-  ): mergeQueueModule.ProcessQueueResult {
-    return this.tracker.processMergeQueue(options);
-  }
-
-  /**
-   * Get a stream's position in the queue (lower = sooner).
-   */
-  getMergeQueuePosition(streamId: string, targetBranch?: string): number | null {
-    return this.tracker.getMergeQueuePosition(streamId, targetBranch);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Conflict Operations
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Create a conflict record.
-   *
-   * Usually conflicts are created implicitly by merge/rebase operations.
-   * This is for explicit creation (e.g., an external process detected a
-   * conflict that git-cascade didn't).
-   */
-  createConflict(options: CreateConflictOptions): string {
-    const id = this.tracker.createConflict(options);
-    this.emit('conflict:created', {
-      conflictId: id,
-      streamId: options.streamId,
-    });
-    return id;
-  }
-
-  /**
-   * Get a conflict record by id.
-   */
-  getConflict(conflictId: string): ConflictRecord | null {
-    return this.tracker.getConflict(conflictId);
-  }
-
-  /**
-   * Get the active conflict record for a stream, if any.
-   */
-  getConflictForStream(streamId: string): ConflictRecord | null {
-    return this.tracker.getConflictForStream(streamId);
-  }
-
-  /**
-   * Emit a `stream:pushed` event for trunk-style landing strategies that push
-   * to a remote rather than merging into another stream. Strategies call this
-   * after a successful push so observers (the OpenHive cascade-bridge) can
-   * surface the push as `x-cascade/stream.pushed`.
-   */
-  notifyStreamPushed(args: {
-    streamId: string;
-    agentId: string;
-    pushedCommit: string;
-    remote: string;
-    remoteRef: string;
-    strategy?: string;
-    metadata?: Record<string, unknown>;
-  }): void {
-    this.emit('stream:pushed', {
-      streamId: args.streamId,
-      agentId: args.agentId,
-      pushedCommit: args.pushedCommit,
-      remote: args.remote,
-      remoteRef: args.remoteRef,
-      strategy: args.strategy,
-      metadata: args.metadata,
-    });
-  }
-
-  /**
-   * Mark a conflict as resolved. Routes through git-cascade's tracker so
-   * `x-cascade/stream.conflict_resolved` fires for hub observers (closes
-   * cascade_conflicts.status from pending → resolved on the OpenHive side).
-   */
-  resolveConflict(args: {
-    conflictId: string;
-    resolution: import('git-cascade').ConflictResolution & { summary?: string };
-    metadata?: Record<string, unknown>;
-  }): void {
-    this.tracker.resolveConflict(args.conflictId, args.resolution, {
-      metadata: args.metadata,
-    });
-  }
-
-  /**
-   * Abandon a conflict (stream-level give-up). Emits a
-   * `stream.conflict_resolved` event with method='abandoned' so observers
-   * see the conflict is no longer pending.
-   */
-  abandonConflict(args: {
-    conflictId: string;
-    agentId?: string;
-    reason?: string;
-    metadata?: Record<string, unknown>;
-  }): void {
-    this.tracker.abandonConflict(args.conflictId, {
-      agentId: args.agentId,
-      reason: args.reason,
-      metadata: args.metadata,
-    });
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Reconciliation
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Check if a stream's database state is in sync with its git branch.
-   */
-  checkStreamSync(streamId: string): reconcileModule.StreamSyncStatus {
-    return this.tracker.checkStreamSync(streamId);
-  }
-
-  /**
-   * Check all active streams for sync status.
-   */
-  checkAllStreamsSync(
-    options?: { streamIds?: string[] }
-  ): reconcileModule.ReconcileCheckResult {
-    return this.tracker.checkAllStreamsSync(options);
-  }
-
-  /**
-   * Reconcile database state with git state. Fixes missing branches, resets
-   * diverged HEAD (per options), etc. Does NOT handle orphan worktrees — the
-   * macro-agent-level reconcile wrapper covers that.
-   */
-  reconcile(
-    options?: reconcileModule.ReconcileOptions
-  ): reconcileModule.ReconcileResult {
-    return this.tracker.reconcile(options);
-  }
-
-  /**
-   * Ensure a stream is in sync before performing an operation.
-   * @throws DesyncError if out of sync unless `force: true`.
-   */
-  ensureStreamInSync(streamId: string, options?: { force?: boolean }): void {
-    this.tracker.ensureStreamInSync(streamId, options);
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Health & Recovery
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Check system health.
-   */
-  healthCheck(): ReturnType<MultiAgentRepoTracker['healthCheck']> {
-    return this.tracker.healthCheck();
-  }
-
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Lifecycle
-  // ─────────────────────────────────────────────────────────────────────────────
-
-  /**
-   * Close the adapter and release resources.
-   *
-   * Only closes the database if we created it (not if using shared DB).
-   */
-  close(): void {
-    this.eventListeners.clear();
-    this.tracker.close();
-  }
-}
-
-/**
- * Create a GitCascadeAdapter instance.
- *
- * @param config - Configuration options
- * @returns GitCascadeAdapter instance
- */
-export function createGitCascadeAdapter(config: GitCascadeConfig): GitCascadeAdapter {
-  return new GitCascadeAdapter(config);
-}