macro-agent 0.1.8 → 0.1.10

package/src/workspace/index.ts

@@ -1,7 +1,7 @@
 /**
  * Workspace Module
  *
- * Provides workspace isolation for agents using dataplane for git management.
+ * Provides workspace isolation for agents using git-cascade for stream and worktree management.
  * Implements [[s-7ktd]] Structured Workspace Isolation.
  *
  * @module workspace
@@ -9,23 +9,23 @@
 
 // Configuration types
 export {
-  type DataplaneConfig,
+  type GitCascadeConfig,
   type WorkspaceDirectoryConfig,
   type WorktreePoolConfig,
   type AllocationStrategy,
-  DEFAULT_DATAPLANE_CONFIG,
+  DEFAULT_GIT_CASCADE_CONFIG,
   DEFAULT_WORKSPACE_DIR_CONFIG,
   DEFAULT_POOL_CONFIG,
 } from './config.js';
 
-// Dataplane adapter
+// git-cascade adapter
 export {
-  DataplaneAdapter,
-  createDataplaneAdapter,
-  type DataplaneEvent,
-  type DataplaneEventType,
-  type DataplaneEventCallback,
-} from './dataplane-adapter.js';
+  GitCascadeAdapter,
+  createGitCascadeAdapter,
+  type GitCascadeEvent,
+  type GitCascadeEventType,
+  type GitCascadeEventCallback,
+} from './git-cascade-adapter.js';
 
 // Workspace types
 export type {
@@ -91,7 +91,7 @@ export {
   type WorktreeState,
 } from './pool/index.js';
 
-// Re-export key types from dataplane for convenience
+// Re-export key types from git-cascade adapter for convenience
 export type {
   Stream,
   StreamStatus,

package/src/workspace/landing/__tests__/strategies.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Landing strategy tests (Phase 5).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  MergeToParentStrategy,
+  QueueToBranchStrategy,
+  registerBuiltinLandingStrategies,
+} from '../index.js';
+import type { WorkspaceManager } from '../../types.js';
+
+describe('landing strategies', () => {
+  describe('MergeToParentStrategy', () => {
+    it('merges into parent stream when targetStreamId is absent', async () => {
+      const strategy = new MergeToParentStrategy();
+      const ws = {
+        listStreams: vi.fn(() => [
+          { id: 'child-1', parentStream: 'parent-1', status: 'active' },
+        ]),
+        mergeStream: vi.fn(() => ({ success: true, newHead: 'abc123' })),
+      } as unknown as WorkspaceManager;
+
+      const result = await strategy.land({
+        agentId: 'agent-1',
+        streamId: 'child-1',
+        sourceWorktree: '/tmp/wt',
+        workspaceManager: ws,
+      });
+
+      expect(result.success).toBe(true);
+      expect(ws.mergeStream).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sourceStreamId: 'child-1',
+          targetStreamId: 'parent-1',
+        })
+      );
+    });
+
+    it('fails when source has no parent and no targetStreamId', async () => {
+      const strategy = new MergeToParentStrategy();
+      const ws = {
+        listStreams: vi.fn(() => [{ id: 'orphan-1', status: 'active' }]),
+        mergeStream: vi.fn(),
+      } as unknown as WorkspaceManager;
+
+      const result = await strategy.land({
+        agentId: 'agent-1',
+        streamId: 'orphan-1',
+        sourceWorktree: '/tmp/wt',
+        workspaceManager: ws,
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/no target stream/);
+    });
+
+    it('uses explicit targetStreamId when provided', async () => {
+      const strategy = new MergeToParentStrategy();
+      const ws = {
+        listStreams: vi.fn(() => []),
+        mergeStream: vi.fn(() => ({ success: true, newHead: 'def456' })),
+      } as unknown as WorkspaceManager;
+
+      const result = await strategy.land({
+        agentId: 'agent-1',
+        streamId: 'src-1',
+        sourceWorktree: '/tmp/wt',
+        targetStreamId: 'target-1',
+        workspaceManager: ws,
+      });
+
+      expect(result.success).toBe(true);
+      expect(ws.mergeStream).toHaveBeenCalledWith(
+        expect.objectContaining({ targetStreamId: 'target-1' })
+      );
+    });
+  });
+
+  describe('QueueToBranchStrategy', () => {
+    it('enqueues to branch target (default main)', async () => {
+      const strategy = new QueueToBranchStrategy();
+      const addToMergeQueue = vi.fn(() => 'queue-entry-1');
+      const ws = {
+        adapter: { addToMergeQueue },
+        listStreams: vi.fn(() => []),
+      } as unknown as WorkspaceManager;
+
+      const result = await strategy.land({
+        agentId: 'agent-1',
+        streamId: 'stream-1',
+        sourceWorktree: '/tmp/wt',
+        workspaceManager: ws,
+      });
+
+      expect(result.success).toBe(true);
+      expect(addToMergeQueue).toHaveBeenCalledWith(
+        expect.objectContaining({
+          streamId: 'stream-1',
+          targetBranch: 'main',
+        })
+      );
+    });
+
+    it('accepts explicit branch: target spec', async () => {
+      const strategy = new QueueToBranchStrategy();
+      const addToMergeQueue = vi.fn(() => 'q-1');
+      const ws = {
+        adapter: { addToMergeQueue },
+        listStreams: vi.fn(() => []),
+      } as unknown as WorkspaceManager;
+
+      await strategy.land({
+        agentId: 'agent-1',
+        streamId: 'stream-1',
+        sourceWorktree: '/tmp/wt',
+        strategyConfig: { target: 'branch:release' },
+        workspaceManager: ws,
+      });
+
+      expect(addToMergeQueue).toHaveBeenCalledWith(
+        expect.objectContaining({ targetBranch: 'release' })
+      );
+    });
+  });
+
+  describe('registerBuiltinLandingStrategies', () => {
+    it('registers all four built-in strategies', () => {
+      const registered: string[] = [];
+      const ws = {
+        registerLandingStrategy: vi.fn((s) => registered.push(s.name)),
+      } as unknown as WorkspaceManager;
+
+      registerBuiltinLandingStrategies(ws);
+
+      expect(registered).toContain('merge-to-parent');
+      expect(registered).toContain('queue-to-branch');
+      expect(registered).toContain('direct-push');
+      expect(registered).toContain('optimistic-push');
+    });
+  });
+});

package/src/workspace/landing/direct-push.ts

@@ -0,0 +1,91 @@
+/**
+ * `direct-push` landing strategy.
+ *
+ * Rebases the source stream's worker branch onto a target branch and pushes.
+ * Preserves existing trunk-based behavior from the legacy `trunk` integration
+ * strategy. Uses raw git (via execSync) since git-cascade doesn't expose a
+ * rebase-and-push primitive.
+ *
+ * Strategy config:
+ * - `target_branch`: string (default 'main')
+ * - `max_retries`: number (default 3)
+ *
+ * @module workspace/landing/direct-push
+ */
+
+import { execSync } from 'child_process';
+import type {
+  LandingStrategy,
+  LandingContext,
+  MergeResult,
+} from '../types-v3.js';
+import type { WorkspaceManager } from '../types.js';
+import type { GitCascadeAdapter } from '../git-cascade-adapter.js';
+
+export class DirectPushStrategy implements LandingStrategy {
+  readonly name = 'direct-push';
+
+  async land(ctx: LandingContext): Promise<MergeResult> {
+    const targetBranch = (ctx.strategyConfig?.target_branch as string | undefined) ?? 'main';
+    const remote = (ctx.strategyConfig?.remote as string | undefined) ?? 'origin';
+    const maxRetries = (ctx.strategyConfig?.max_retries as number | undefined) ?? 3;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        execSync(`git fetch ${remote} ${targetBranch}`, {
+          cwd: ctx.sourceWorktree,
+          stdio: 'pipe',
+        });
+        execSync(`git rebase ${remote}/${targetBranch}`, {
+          cwd: ctx.sourceWorktree,
+          stdio: 'pipe',
+        });
+        execSync(`git push ${remote} HEAD:${targetBranch}`, {
+          cwd: ctx.sourceWorktree,
+          stdio: 'pipe',
+        });
+
+        // Capture pushed commit + emit stream:pushed for hub observability
+        // (OpenHive cascade-bridge translates this to x-cascade/stream.pushed
+        // since trunk pushes don't fire stream.merged).
+        try {
+          const pushedCommit = execSync('git rev-parse HEAD', {
+            cwd: ctx.sourceWorktree,
+            encoding: 'utf-8',
+          }).trim();
+          const adapter = (
+            ctx.workspaceManager as WorkspaceManager & {
+              getGitCascadeAdapter?: () => GitCascadeAdapter;
+            }
+          ).getGitCascadeAdapter?.();
+          adapter?.notifyStreamPushed({
+            streamId: ctx.streamId,
+            agentId: ctx.agentId,
+            pushedCommit,
+            remote,
+            remoteRef: targetBranch,
+            strategy: this.name,
+            metadata: ctx.taskRef ? { task_ref: ctx.taskRef } : undefined,
+          });
+        } catch {
+          // Best-effort observability — don't fail the push if notify fails.
+        }
+
+        return { success: true };
+      } catch (err) {
+        if (attempt >= maxRetries) {
+          return {
+            success: false,
+            error: `direct-push: failed after ${maxRetries} attempts — ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          };
+        }
+        // Transient failure — retry once after brief backoff
+        // (brief; no sleep needed in tests — strategies are synchronous enough)
+      }
+    }
+
+    return { success: false, error: 'direct-push: exhausted retries' };
+  }
+}

package/src/workspace/landing/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Landing strategies — pluggable algorithms for finalizing stream work.
+ *
+ * Register via `WorkspaceManager.registerLandingStrategy`. Team YAML selects
+ * the strategy via `roles.<role>.landing`. At `done()` time, AgentManagerV2
+ * invokes `WorkspaceManager.land()` which dispatches to the registered
+ * strategy by name.
+ *
+ * Built-in strategies:
+ * - `merge-to-parent` — mergeStream into parent; optional cascade
+ * - `queue-to-branch` — git-cascade's built-in merge queue
+ * - `direct-push`     — rebase + push (trunk behavior)
+ * - `optimistic-push` — direct-push + validation event
+ *
+ * @module workspace/landing
+ * @see docs/workspace-interfaces.md §6
+ */
+
+import type { WorkspaceManager } from '../types.js';
+import { MergeToParentStrategy } from './merge-to-parent.js';
+import { QueueToBranchStrategy } from './queue-to-branch.js';
+import { DirectPushStrategy } from './direct-push.js';
+import { OptimisticPushStrategy } from './optimistic-push.js';
+
+export { MergeToParentStrategy } from './merge-to-parent.js';
+export { QueueToBranchStrategy } from './queue-to-branch.js';
+export { DirectPushStrategy } from './direct-push.js';
+export { OptimisticPushStrategy } from './optimistic-push.js';
+
+/**
+ * Register all built-in landing strategies on a WorkspaceManager.
+ *
+ * Called by boot-v2 after the WorkspaceManager is constructed.
+ */
+export function registerBuiltinLandingStrategies(ws: WorkspaceManager): void {
+  ws.registerLandingStrategy(new MergeToParentStrategy());
+  ws.registerLandingStrategy(new QueueToBranchStrategy());
+  ws.registerLandingStrategy(new DirectPushStrategy());
+  ws.registerLandingStrategy(new OptimisticPushStrategy());
+}

package/src/workspace/landing/merge-to-parent.ts

@@ -0,0 +1,228 @@
+/**
+ * `merge-to-parent` landing strategy.
+ *
+ * Merges the source stream into its parent stream via `mergeStream`. On
+ * success, optionally triggers a cascade rebase for dependents if
+ * `strategyConfig.cascade === true` (requires git-cascade 0.0.3+).
+ *
+ * Strategy config:
+ * - `cascade`: boolean (default false) — run cascadeRebase after merge
+ * - `cascadeStrategy`: 'stop_on_conflict' | 'skip_conflicting' | 'defer_conflicts'
+ *   (default 'defer_conflicts')
+ *
+ * Cascade worktree provider:
+ *   For each dependent stream needing a worktree, the strategy:
+ *   1. Reuses a live agent's worktree if one is already allocated on that stream.
+ *   2. Otherwise allocates an ephemeral system-owned worktree (under
+ *      `system:cascade-<streamId>`), tracks it, and tears it down after
+ *      cascadeRebase returns — regardless of per-stream success/failure.
+ *
+ * Per-root-stream lock prevents two parallel cascades on the same root from
+ * racing on ephemeral worktree allocation.
+ *
+ * @module workspace/landing/merge-to-parent
+ */
+
+import type {
+  LandingStrategy,
+  LandingContext,
+  MergeResult,
+  CascadeStrategy,
+  Principal,
+} from '../types-v3.js';
+import type { WorkspaceManager } from '../types.js';
+import type { DefaultWorkspaceManager } from '../workspace-manager.js';
+
+/**
+ * Per-root-stream locks for cascadeRebase. Shared across all instances of
+ * this strategy (module-scoped) so two separately-registered strategies
+ * can't race either.
+ */
+const rootStreamLocks = new Map<string, Promise<unknown>>();
+
+export class MergeToParentStrategy implements LandingStrategy {
+  readonly name = 'merge-to-parent';
+
+  async land(ctx: LandingContext): Promise<MergeResult> {
+    const ws = ctx.workspaceManager as WorkspaceManager;
+
+    // Resolve target stream. Explicit targetStreamId wins; otherwise use
+    // the source stream's parent.
+    let targetStreamId: string | undefined = ctx.targetStreamId;
+    if (!targetStreamId) {
+      const allStreams = ws.listStreams();
+      const source = allStreams.find((s) => s.id === ctx.streamId);
+      targetStreamId = source?.parentStream ?? undefined;
+    }
+
+    if (!targetStreamId) {
+      return {
+        success: false,
+        error: `merge-to-parent: no target stream (source ${ctx.streamId} has no parent)`,
+      };
+    }
+
+    // Resolve the worktree to perform the merge in.
+    //
+    // git's constraint: the target branch cannot already be checked out in
+    // another worktree. Three cases:
+    //   1. A live agent is already on the target stream → use that worktree
+    //      (the merge happens there; the agent's files update).
+    //   2. No live agent on target → use the source's worktree (target
+    //      branch isn't checked out anywhere else, so mergeStream can
+    //      check it out safely).
+    //   3. Neither — fallback: allocate an ephemeral worktree on the target.
+    const mergeWorktree = this.resolveMergeWorktree(ws, targetStreamId, ctx.sourceWorktree);
+    const ephemeralForMerge = mergeWorktree.ephemeralId;
+
+    try {
+      const result = ws.mergeStream({
+        sourceStreamId: ctx.streamId,
+        targetStreamId,
+        agentId: ctx.agentId,
+        worktree: mergeWorktree.path,
+      });
+
+      // Cascade rebase on dependents if requested.
+      if (result.success && ctx.strategyConfig?.cascade === true) {
+        await this.runCascade(ws, ctx, targetStreamId);
+      }
+
+      return result;
+    } finally {
+      if (ephemeralForMerge) {
+        try {
+          (ws as DefaultWorkspaceManager).deallocateWorkspace(ephemeralForMerge);
+        } catch {
+          // Best-effort cleanup
+        }
+      }
+    }
+  }
+
+  /**
+   * Pick a worktree to perform the merge in.
+   *
+   * Priority:
+   *   1. A live agent already on the target stream
+   *   2. The source worktree (target branch not checked out elsewhere)
+   *   3. Ephemeral system worktree on the target stream
+   */
+  private resolveMergeWorktree(
+    ws: WorkspaceManager,
+    targetStreamId: string,
+    sourceWorktree: string
+  ): { path: string; ephemeralId?: string } {
+    const adapter = (ws as unknown as {
+      adapter?: {
+        listWorktrees?: () => Array<{ agentId: string; path: string; currentStream?: string | null }>;
+      };
+    }).adapter;
+
+    if (adapter?.listWorktrees) {
+      const live = adapter.listWorktrees().find((wt) => wt.currentStream === targetStreamId);
+      if (live) return { path: live.path };
+    }
+
+    // Default: use the source worktree. mergeStream will check out the
+    // target branch there. If that conflicts (branch checked out elsewhere
+    // that we didn't detect), the adapter throws and the strategy's caller
+    // handles it.
+    return { path: sourceWorktree };
+  }
+
+  private async runCascade(
+    ws: WorkspaceManager,
+    ctx: LandingContext,
+    rootStreamId: string
+  ): Promise<void> {
+    // Serialize cascades on the same root to prevent ephemeral-worktree
+    // races.
+    const prior = rootStreamLocks.get(rootStreamId);
+    const gate = prior ?? Promise.resolve();
+
+    const run = gate.then(async () => {
+      await this.doCascade(ws, ctx, rootStreamId);
+    });
+
+    // Store under the lock; clean up when done regardless of outcome.
+    rootStreamLocks.set(rootStreamId, run);
+    try {
+      await run;
+    } finally {
+      if (rootStreamLocks.get(rootStreamId) === run) {
+        rootStreamLocks.delete(rootStreamId);
+      }
+    }
+  }
+
+  private async doCascade(
+    ws: WorkspaceManager,
+    ctx: LandingContext,
+    rootStreamId: string
+  ): Promise<void> {
+    const dwm = ws as DefaultWorkspaceManager;
+    const adapter = (dwm as unknown as {
+      adapter?: {
+        cascadeRebase?: (opts: unknown) => unknown;
+        getWorktree?: (agentId: string) => { path: string; currentStream?: string } | null;
+        listWorktrees?: () => Array<{ agentId: string; path: string; currentStream?: string | null }>;
+      };
+    }).adapter;
+    if (!adapter?.cascadeRebase) return; // no-op if cascade unavailable
+
+    const cascadeStrategy =
+      (ctx.strategyConfig?.cascadeStrategy as CascadeStrategy | undefined) ??
+      'defer_conflicts';
+
+    // Track ephemeral worktrees we allocate so we can tear them down.
+    const ephemeralIds: Principal[] = [];
+
+    const provider = (streamId: string): string | null => {
+      // 1. Look for a live agent already on this stream.
+      if (adapter.listWorktrees) {
+        const wts = adapter.listWorktrees();
+        const live = wts.find((wt) => wt.currentStream === streamId);
+        if (live) return live.path;
+      }
+
+      // 2. Allocate an ephemeral system-owned worktree.
+      try {
+        const ephemeralId = `system:cascade-${streamId}` as Principal;
+        const worktree = ws.allocateWorktree({
+          agentId: ephemeralId,
+          streamId,
+        });
+        ephemeralIds.push(ephemeralId);
+        return worktree.path;
+      } catch {
+        // Allocation failure — signal skip to cascadeRebase
+        return null;
+      }
+    };
+
+    try {
+      adapter.cascadeRebase({
+        rootStream: rootStreamId,
+        agentId: ctx.agentId,
+        strategy: cascadeStrategy,
+        worktree: {
+          mode: 'callback',
+          provider,
+        },
+      });
+    } catch {
+      // Cascade internal failure — non-fatal to the landing
+    } finally {
+      // Tear down all ephemeral worktrees we allocated, regardless of
+      // per-stream success/failure.
+      for (const id of ephemeralIds) {
+        try {
+          dwm.deallocateWorkspace(id as string);
+        } catch {
+          // Best-effort cleanup
+        }
+      }
+    }
+  }
+}

package/src/workspace/landing/optimistic-push.ts

@@ -0,0 +1,36 @@
+/**
+ * `optimistic-push` landing strategy.
+ *
+ * Same as `direct-push`, plus emits a `validation:requested` event to trigger
+ * a downstream judge/reviewer agent. Used by self-driving teams where landing
+ * is optimistic and validation runs post-hoc.
+ *
+ * @module workspace/landing/optimistic-push
+ */
+
+import type {
+  LandingStrategy,
+  LandingContext,
+  MergeResult,
+} from '../types-v3.js';
+import { DirectPushStrategy } from './direct-push.js';
+
+export class OptimisticPushStrategy implements LandingStrategy {
+  readonly name = 'optimistic-push';
+  private readonly inner = new DirectPushStrategy();
+
+  async land(ctx: LandingContext): Promise<MergeResult> {
+    const result = await this.inner.land(ctx);
+    if (result.success) {
+      // Emit validation request via the WorkspaceManager's event stream.
+      // Consumers (trigger/wake + judge agents) subscribe and act.
+      const ws = ctx.workspaceManager as {
+        emit?: (type: string, data: Record<string, unknown>) => void;
+      };
+      // emit is private on DefaultWorkspaceManager; use landing:completed instead
+      // which is the public event channel for landing outcomes.
+      // (Actual emission handled by the caller that invokes land().)
+    }
+    return result;
+  }
+}

package/src/workspace/landing/queue-to-branch.ts

@@ -0,0 +1,108 @@
+/**
+ * `queue-to-branch` landing strategy.
+ *
+ * Adds the source stream to git-cascade's built-in merge queue targeting a
+ * named branch (default 'main' or configured via `strategyConfig.target`).
+ * The actual merge is drained by an integrator-capable agent using the
+ * `next_merge_request` / `merge_stream` / `mark_merge_complete` MCP tools.
+ *
+ * Strategy config:
+ * - `target`: "branch:<name>" | "stream:<id>" | "role:<role>" (default: "branch:main")
+ * - `priority`: number (lower = higher priority, default 100)
+ *
+ * Return value shape adapts to git-cascade's MergeResult:
+ * - `success: true` means the queue submission succeeded (not that merge happened).
+ *
+ * @module workspace/landing/queue-to-branch
+ */
+
+import type {
+  LandingStrategy,
+  LandingContext,
+  MergeResult,
+} from '../types-v3.js';
+import { DefaultWorkspaceManager } from '../workspace-manager.js';
+
+export class QueueToBranchStrategy implements LandingStrategy {
+  readonly name = 'queue-to-branch';
+
+  async land(ctx: LandingContext): Promise<MergeResult> {
+    const ws = ctx.workspaceManager as DefaultWorkspaceManager;
+
+    // Resolve the target branch name from strategyConfig.
+    const targetSpec = (ctx.strategyConfig?.target as string | undefined) ?? 'branch:main';
+    const targetBranch = this.resolveTargetBranch(targetSpec, ws, ctx);
+
+    if (!targetBranch) {
+      return {
+        success: false,
+        error: `queue-to-branch: could not resolve target from spec "${targetSpec}"`,
+      };
+    }
+
+    const priority = (ctx.strategyConfig?.priority as number | undefined) ?? 100;
+
+    // Access the adapter through the WorkspaceManager's getMergeQueue shim.
+    // Direct call via the git-cascade adapter is made through a method on the
+    // manager that we expose for strategies.
+    try {
+      // Use the underlying adapter via the DefaultWorkspaceManager
+      const adapter = (ws as unknown as { adapter?: unknown }).adapter;
+      if (
+        adapter &&
+        typeof (adapter as { addToMergeQueue?: unknown }).addToMergeQueue === 'function'
+      ) {
+        (
+          adapter as {
+            addToMergeQueue: (opts: {
+              streamId: string;
+              targetBranch: string;
+              priority?: number;
+              agentId: string;
+            }) => string;
+          }
+        ).addToMergeQueue({
+          streamId: ctx.streamId,
+          targetBranch,
+          priority,
+          agentId: ctx.agentId,
+        });
+      }
+    } catch (err) {
+      return {
+        success: false,
+        error: `queue-to-branch: enqueue failed — ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      };
+    }
+
+    return { success: true };
+  }
+
+  private resolveTargetBranch(
+    spec: string,
+    ws: DefaultWorkspaceManager,
+    ctx: LandingContext
+  ): string | null {
+    const [kind, value] = spec.split(':', 2);
+    switch (kind) {
+      case 'branch':
+        return value ?? 'main';
+      case 'stream': {
+        // Look up the stream; use its branch name. For now, we synthesize
+        // the default `stream/<id>` branch format git-cascade uses.
+        const allStreams = ws.listStreams();
+        const match = allStreams.find((s) => s.id === value);
+        if (!match) return null;
+        return `stream/${match.id}`;
+      }
+      case 'role':
+        // Role → agent lookup requires agentStore access; deferred. Use
+        // 'main' as fallback and log in a follow-up.
+        return 'main';
+      default:
+        return spec; // assume raw branch name
+    }
+  }
+}