wave-agent-sdk 0.19.7 → 0.19.8

package/dist/agent.d.ts

@@ -390,4 +390,11 @@ export declare class Agent {
      * Check if there are any running background tasks or active subagents
      */
     get hasRunningBackgroundWork(): boolean;
+    /**
+     * Check if there are pending items (messages, bang commands, or background
+     * task notifications) in the message queue. Background task completion
+     * notifications are enqueued before the main agent's dispatch consumes them,
+     * so callers waiting for the agent to fully settle must also wait on this.
+     */
+    get hasPendingMessages(): boolean;
 }

package/dist/agent.js

@@ -978,4 +978,13 @@ export class Agent {
         const activeSubagents = this.subagentManager.getActiveInstances().length > 0;
         return runningTasks || activeSubagents;
     }
+    /**
+     * Check if there are pending items (messages, bang commands, or background
+     * task notifications) in the message queue. Background task completion
+     * notifications are enqueued before the main agent's dispatch consumes them,
+     * so callers waiting for the agent to fully settle must also wait on this.
+     */
+    get hasPendingMessages() {
+        return this.messageQueue.hasPending();
+    }
 }

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 export * from "./tools/buildTool.js";
 export type { ToolPlugin, ToolResult, ToolContext } from "./tools/types.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 // Export tool building utilities
 export * from "./tools/buildTool.js";

package/dist/managers/aiManager.d.ts

@@ -58,6 +58,7 @@ export declare class AIManager {
     getMaxInputTokens(): number;
     getLanguage(): string | undefined;
     getAutoMemoryEnabled(): boolean;
+    getWorktreeBaseRef(): "fresh" | "head";
     getWorkdir(): string;
     getOriginalWorkdir(): string;
     /**

package/dist/managers/aiManager.js

@@ -128,6 +128,9 @@ export class AIManager {
     getAutoMemoryEnabled() {
         return this.configurationService.resolveAutoMemoryEnabled();
     }
+    getWorktreeBaseRef() {
+        return this.configurationService.resolveWorktreeBaseRef();
+    }
     getWorkdir() {
         return this.container.get("Workdir") ?? process.cwd();
     }

package/dist/managers/subagentManager.js

@@ -8,6 +8,7 @@ import { ToolManager } from "./toolManager.js";
 import { AGENT_TOOL_NAME, TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_LIST_TOOL_NAME, TASK_UPDATE_TOOL_NAME, } from "../constants/tools.js";
 import { addConsolidatedAbortListener, createAbortPromise, } from "../utils/abortUtils.js";
 import { BackgroundTaskManager } from "./backgroundTaskManager.js";
+import { MessageQueue } from "./messageQueue.js";
 import { logger } from "../utils/globalLogger.js";
 export class SubagentManager {
     constructor(container, options) {
@@ -135,6 +136,11 @@ export class SubagentManager {
         const subagentId = randomUUID();
         // Create a child container for the subagent to isolate its managers
         const subagentContainer = this.container.createChild();
+        // Register an independent MessageQueue so the subagent's AIManager drains its
+        // own (empty) queue instead of falling back to the parent container's queue.
+        // Without this, concurrent background subagents steal sibling completion
+        // notifications from the parent queue, causing the main agent to exit early.
+        subagentContainer.register("MessageQueue", new MessageQueue());
         // Register a modified AgentOptions without onLoadingChange to prevent subagent loading
         // from affecting the parent agent's loading state
         const parentOptions = this.container.get("AgentOptions");

package/dist/services/configurationService.d.ts

@@ -85,6 +85,12 @@ export declare class ConfigurationService {
      * @returns Resolved auto-memory enabled state
      */
     resolveAutoMemoryEnabled(): boolean;
+    /**
+     * Resolves worktree base ref with fallbacks
+     * Resolution priority: settings.json > default ("fresh")
+     * @returns Resolved worktree base ref
+     */
+    resolveWorktreeBaseRef(): "fresh" | "head";
     /**
      * Resolves auto-memory extraction frequency with fallbacks
      * Resolution priority: settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)

package/dist/services/configurationService.js

@@ -241,6 +241,19 @@ export class ConfigurationService {
                 }
             }
         }
+        // Validate worktree if present
+        if (config.worktree !== undefined) {
+            if (typeof config.worktree !== "object" || config.worktree === null) {
+                result.isValid = false;
+                result.errors.push("worktree configuration must be an object");
+            }
+            else if (config.worktree.baseRef !== undefined &&
+                config.worktree.baseRef !== "fresh" &&
+                config.worktree.baseRef !== "head") {
+                result.isValid = false;
+                result.errors.push(`Invalid worktree.baseRef: "${config.worktree.baseRef}". Must be "fresh" or "head".`);
+            }
+        }
         return result;
     }
     /**
@@ -506,6 +519,18 @@ export class ConfigurationService {
         // 3. Default (true)
         return true;
     }
+    /**
+     * Resolves worktree base ref with fallbacks
+     * Resolution priority: settings.json > default ("fresh")
+     * @returns Resolved worktree base ref
+     */
+    resolveWorktreeBaseRef() {
+        const baseRef = this.currentConfiguration?.worktree?.baseRef;
+        if (baseRef === "head") {
+            return "head";
+        }
+        return "fresh";
+    }
     /**
      * Resolves auto-memory extraction frequency with fallbacks
      * Resolution priority: settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)
@@ -944,6 +969,7 @@ export function loadWaveConfigFromFile(filePath) {
                 : undefined,
             models: config.models || undefined,
             marketplaces: config.marketplaces || undefined,
+            worktree: config.worktree || undefined,
         };
     }
     catch (error) {
@@ -1074,6 +1100,10 @@ export function loadMergedWaveConfig(workdir) {
                 mergedConfig.marketplaces = {};
             Object.assign(mergedConfig.marketplaces, config.marketplaces);
         }
+        // Merge worktree (last one wins)
+        if (config.worktree !== undefined) {
+            mergedConfig.worktree = config.worktree;
+        }
         // Merge models
         if (config.models) {
             if (!mergedConfig.models)
@@ -1111,5 +1141,6 @@ export function loadMergedWaveConfig(workdir) {
         models: mergedConfig.models && Object.keys(mergedConfig.models).length > 0
             ? mergedConfig.models
             : undefined,
+        worktree: mergedConfig.worktree,
     };
 }

package/dist/services/remoteSettingsService.js

@@ -286,6 +286,8 @@ export function mergeRemoteSettings(localMerged, remote) {
         result.autoMemoryEnabled = remote.autoMemoryEnabled;
     if (remote.autoMemoryFrequency !== undefined)
         result.autoMemoryFrequency = remote.autoMemoryFrequency;
+    if (remote.worktree !== undefined)
+        result.worktree = remote.worktree;
     if (remote.models !== undefined)
         result.models = remote.models;
     if (remote.marketplaces !== undefined)

package/dist/tools/enterWorktreeTool.js

@@ -83,7 +83,8 @@ export const enterWorktreeTool = {
             };
         }
         // Create the worktree (captures originalHeadCommit internally)
-        const worktreeInfo = createWorktree(name, mainRepoRoot);
+        const baseRef = context.aiManager?.getWorktreeBaseRef?.();
+        const worktreeInfo = createWorktree(name, mainRepoRoot, { baseRef });
         // Build session state
         const session = {
             originalCwd: context.workdir,

package/dist/types/configuration.d.ts

@@ -50,6 +50,11 @@ export interface WaveConfiguration {
     monitoring?: {
         telemetry?: Partial<TelemetryConfig>;
     };
+    /** Worktree configuration */
+    worktree?: {
+        /** Base ref for new worktrees: "fresh" (origin/<default-branch>, default) | "head" (local HEAD) */
+        baseRef?: "fresh" | "head";
+    };
 }
 /**
  * Legacy alias for backward compatibility - will be deprecated

package/dist/types/permissions.d.ts

@@ -15,8 +15,6 @@ export interface PermissionDecision {
     newPermissionMode?: PermissionMode;
     /** Signal to persist a new allowed rule */
     newPermissionRule?: string;
-    /** Signal to clear the conversation context and proceed with the plan */
-    clearContext?: boolean;
 }
 /** Callback function for custom permission logic */
 export type PermissionCallback = (context: ToolPermissionContext) => Promise<PermissionDecision>;

package/dist/types/processes.d.ts

@@ -44,6 +44,33 @@ export interface BackgroundWorkflow extends BackgroundTaskBase {
     runId: string;
 }
 export type BackgroundTask = BackgroundShell | BackgroundSubagent | BackgroundWorkflow;
+/**
+ * Serializable summary of a BackgroundTask, used for notifications where the
+ * full stdout/stderr and non-serializable process/onStop fields must be
+ * stripped to control payload size. Output is fetched on demand via
+ * getBackgroundTaskOutput.
+ */
+export interface BackgroundTaskSummary {
+    id: string;
+    type: BackgroundTaskType;
+    status: BackgroundTaskStatus;
+    startTime: number;
+    endTime?: number;
+    command?: string;
+    description?: string;
+    exitCode?: number;
+    runtime?: number;
+    outputPath?: string;
+}
+/** Output snapshot returned by getBackgroundTaskOutput. */
+export interface BackgroundTaskOutput {
+    stdout: string;
+    stderr: string;
+    status: BackgroundTaskStatus;
+    outputPath?: string;
+    type: BackgroundTaskType;
+    exitCode?: number;
+}
 export interface ForegroundTask {
     id: string;
     backgroundHandler: () => Promise<void>;

package/dist/types/workflow.d.ts

@@ -1 +1 @@
-export type { WorkflowRun, WorkflowMeta, WorkflowPhaseState, } from "../workflow/types.js";
+export type { WorkflowRun, WorkflowMeta, WorkflowPhaseState, SerializableWorkflowRun, } from "../workflow/types.js";

package/dist/utils/containerSetup.js

@@ -179,21 +179,12 @@ export function setupAgentContainer(setupOptions) {
                 });
             }
             const decision = await options.canUseTool(context);
-            const planFilePath = permissionManager.getPlanFilePath();
             if (decision.newPermissionMode) {
                 setPermissionMode(decision.newPermissionMode);
             }
             if (decision.newPermissionRule) {
                 await addPermissionRule(decision.newPermissionRule);
             }
-            if (decision.clearContext) {
-                messageManager.clearMessages();
-                if (planFilePath) {
-                    messageManager.addUserMessage({
-                        content: `Implement the plan at ${planFilePath}`,
-                    });
-                }
-            }
             return decision;
         }
         : undefined;

package/dist/utils/worktreeSession.d.ts

@@ -5,7 +5,7 @@
  * "WorktreeSession" container slot registered in containerSetup.ts and accessed via
  * AIManager.getWorktreeSession()/setWorktreeSession()). This keeps worktree state
  * isolated per session in stdio multi-agent mode — a process-level singleton would
- * leak state across concurrent sessions (see specs/047-worktree.md FR-042).
+ * leak state across concurrent sessions (see docs/specs/multi-agent/worktree.md FR-042).
  */
 export interface WorktreeSession {
     /** The working directory the session was in before EnterWorktree */

package/dist/utils/worktreeSession.js

@@ -5,6 +5,6 @@
  * "WorktreeSession" container slot registered in containerSetup.ts and accessed via
  * AIManager.getWorktreeSession()/setWorktreeSession()). This keeps worktree state
  * isolated per session in stdio multi-agent mode — a process-level singleton would
- * leak state across concurrent sessions (see specs/047-worktree.md FR-042).
+ * leak state across concurrent sessions (see docs/specs/multi-agent/worktree.md FR-042).
  */
 export {};

package/dist/utils/worktreeUtils.d.ts

@@ -25,8 +25,14 @@ export declare function generateWorktreeName(): string;
 export declare function getHeadCommit(cwd: string): string;
 /**
  * Create a git worktree for use during a session.
+ * @param name Worktree name
+ * @param cwd Current working directory (will be resolved to main repo root)
+ * @param options Optional creation options
+ * @param options.baseRef "fresh" (default, origin/<default-branch>) | "head" (local HEAD)
  */
-export declare function createWorktree(name: string, cwd: string): WorktreeInfo;
+export declare function createWorktree(name: string, cwd: string, options?: {
+    baseRef?: "fresh" | "head";
+}): WorktreeInfo;
 /**
  * Remove a git worktree and its branch.
  */

package/dist/utils/worktreeUtils.js

@@ -68,8 +68,12 @@ export function getHeadCommit(cwd) {
 }
 /**
  * Create a git worktree for use during a session.
+ * @param name Worktree name
+ * @param cwd Current working directory (will be resolved to main repo root)
+ * @param options Optional creation options
+ * @param options.baseRef "fresh" (default, origin/<default-branch>) | "head" (local HEAD)
  */
-export function createWorktree(name, cwd) {
+export function createWorktree(name, cwd, options) {
     const repoRoot = getGitMainRepoRoot(cwd);
     if (!repoRoot) {
         throw new Error("Cannot create a worktree: not in a git repository. Configure WorktreeCreate and WorktreeRemove hooks in settings.json to use worktree isolation with other VCS systems.");
@@ -78,7 +82,8 @@ export function createWorktree(name, cwd) {
     const originalHeadCommit = getHeadCommit(cwd);
     const worktreePath = path.join(repoRoot, ".wave", "worktrees", name);
     const branchName = `worktree-${name}`;
-    const baseBranch = getDefaultRemoteBranch(cwd);
+    const useHead = options?.baseRef === "head";
+    const baseBranch = useHead ? "HEAD" : getDefaultRemoteBranch(cwd);
     // Ensure Wave runtime files are git-excluded in this repo
     ensureWaveRuntimeFilesExcluded(cwd);
     // Ensure parent directory exists
@@ -144,8 +149,9 @@ export function createWorktree(name, cwd) {
                 throw new Error(`Failed to add worktree: ${innerError.message}`);
             }
         }
-        if (stderr.includes("not a valid object name") ||
-            stderr.includes("unknown revision")) {
+        if (!useHead &&
+            (stderr.includes("not a valid object name") ||
+                stderr.includes("unknown revision"))) {
             // Base branch not fetched yet — try fetching then retrying
             const branchNameOnly = baseBranch.split("/").pop();
             try {

package/dist/workflow/types.d.ts

@@ -38,6 +38,11 @@ export interface WorkflowRun {
     /** Error message from the failed agent */
     failedAgentError?: string;
 }
+/**
+ * Serializable workflow run for stdio transport, with the non-serializable
+ * `completionPromise` stripped. Returned by the `getWorkflowRuns` RPC.
+ */
+export type SerializableWorkflowRun = Omit<WorkflowRun, "completionPromise">;
 export interface JournalEntry {
     agentIndex: number;
     prompt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "0.19.7",
+  "version": "0.19.8",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",

package/src/agent.ts

@@ -1266,4 +1266,14 @@ export class Agent {
       this.subagentManager.getActiveInstances().length > 0;
     return runningTasks || activeSubagents;
   }
+
+  /**
+   * Check if there are pending items (messages, bang commands, or background
+   * task notifications) in the message queue. Background task completion
+   * notifications are enqueued before the main agent's dispatch consumes them,
+   * so callers waiting for the agent to fully settle must also wait on this.
+   */
+  public get hasPendingMessages(): boolean {
+    return this.messageQueue.hasPending();
+  }
 }

package/src/index.ts

@@ -29,6 +29,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 
 // Export tool building utilities

package/src/managers/aiManager.ts

@@ -252,6 +252,10 @@ export class AIManager {
     return this.configurationService.resolveAutoMemoryEnabled();
   }
 
+  public getWorktreeBaseRef(): "fresh" | "head" {
+    return this.configurationService.resolveWorktreeBaseRef();
+  }
+
   public getWorkdir(): string {
     return this.container.get<string>("Workdir") ?? process.cwd();
   }

package/src/managers/subagentManager.ts

@@ -290,6 +290,12 @@ export class SubagentManager {
     // Create a child container for the subagent to isolate its managers
     const subagentContainer = this.container.createChild();
 
+    // Register an independent MessageQueue so the subagent's AIManager drains its
+    // own (empty) queue instead of falling back to the parent container's queue.
+    // Without this, concurrent background subagents steal sibling completion
+    // notifications from the parent queue, causing the main agent to exit early.
+    subagentContainer.register("MessageQueue", new MessageQueue());
+
     // Register a modified AgentOptions without onLoadingChange to prevent subagent loading
     // from affecting the parent agent's loading state
     const parentOptions =

package/src/services/configurationService.ts

@@ -320,6 +320,23 @@ export class ConfigurationService {
       }
     }
 
+    // Validate worktree if present
+    if (config.worktree !== undefined) {
+      if (typeof config.worktree !== "object" || config.worktree === null) {
+        result.isValid = false;
+        result.errors.push("worktree configuration must be an object");
+      } else if (
+        config.worktree.baseRef !== undefined &&
+        config.worktree.baseRef !== "fresh" &&
+        config.worktree.baseRef !== "head"
+      ) {
+        result.isValid = false;
+        result.errors.push(
+          `Invalid worktree.baseRef: "${config.worktree.baseRef}". Must be "fresh" or "head".`,
+        );
+      }
+    }
+
     return result;
   }
 
@@ -640,6 +657,19 @@ export class ConfigurationService {
     return true;
   }
 
+  /**
+   * Resolves worktree base ref with fallbacks
+   * Resolution priority: settings.json > default ("fresh")
+   * @returns Resolved worktree base ref
+   */
+  resolveWorktreeBaseRef(): "fresh" | "head" {
+    const baseRef = this.currentConfiguration?.worktree?.baseRef;
+    if (baseRef === "head") {
+      return "head";
+    }
+    return "fresh";
+  }
+
   /**
    * Resolves auto-memory extraction frequency with fallbacks
    * Resolution priority: settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)
@@ -1172,6 +1202,7 @@ export function loadWaveConfigFromFile(
           : undefined,
       models: config.models || undefined,
       marketplaces: config.marketplaces || undefined,
+      worktree: config.worktree || undefined,
     };
   } catch (error) {
     if (error instanceof SyntaxError) {
@@ -1320,6 +1351,11 @@ export function loadMergedWaveConfig(
       Object.assign(mergedConfig.marketplaces, config.marketplaces);
     }
 
+    // Merge worktree (last one wins)
+    if (config.worktree !== undefined) {
+      mergedConfig.worktree = config.worktree;
+    }
+
     // Merge models
     if (config.models) {
       if (!mergedConfig.models) mergedConfig.models = {};
@@ -1363,5 +1399,6 @@ export function loadMergedWaveConfig(
       mergedConfig.models && Object.keys(mergedConfig.models).length > 0
         ? mergedConfig.models
         : undefined,
+    worktree: mergedConfig.worktree,
   };
 }

package/src/services/remoteSettingsService.ts

@@ -326,6 +326,7 @@ export function mergeRemoteSettings(
     result.autoMemoryEnabled = remote.autoMemoryEnabled;
   if (remote.autoMemoryFrequency !== undefined)
     result.autoMemoryFrequency = remote.autoMemoryFrequency;
+  if (remote.worktree !== undefined) result.worktree = remote.worktree;
   if (remote.models !== undefined) result.models = remote.models;
   if (remote.marketplaces !== undefined)
     result.marketplaces = remote.marketplaces;

package/src/tools/enterWorktreeTool.ts

@@ -102,7 +102,8 @@ export const enterWorktreeTool: ToolPlugin = {
     }
 
     // Create the worktree (captures originalHeadCommit internally)
-    const worktreeInfo = createWorktree(name, mainRepoRoot);
+    const baseRef = context.aiManager?.getWorktreeBaseRef?.();
+    const worktreeInfo = createWorktree(name, mainRepoRoot, { baseRef });
 
     // Build session state
     const session: WorktreeSession = {

package/src/types/configuration.ts

@@ -54,6 +54,11 @@ export interface WaveConfiguration {
   monitoring?: {
     telemetry?: Partial<TelemetryConfig>;
   };
+  /** Worktree configuration */
+  worktree?: {
+    /** Base ref for new worktrees: "fresh" (origin/<default-branch>, default) | "head" (local HEAD) */
+    baseRef?: "fresh" | "head";
+  };
 }
 
 /**

package/src/types/permissions.ts

@@ -35,8 +35,6 @@ export interface PermissionDecision {
   newPermissionMode?: PermissionMode;
   /** Signal to persist a new allowed rule */
   newPermissionRule?: string;
-  /** Signal to clear the conversation context and proceed with the plan */
-  clearContext?: boolean;
 }
 
 /** Callback function for custom permission logic */

package/src/types/processes.ts

@@ -59,6 +59,35 @@ export type BackgroundTask =
   | BackgroundSubagent
   | BackgroundWorkflow;
 
+/**
+ * Serializable summary of a BackgroundTask, used for notifications where the
+ * full stdout/stderr and non-serializable process/onStop fields must be
+ * stripped to control payload size. Output is fetched on demand via
+ * getBackgroundTaskOutput.
+ */
+export interface BackgroundTaskSummary {
+  id: string;
+  type: BackgroundTaskType;
+  status: BackgroundTaskStatus;
+  startTime: number;
+  endTime?: number;
+  command?: string;
+  description?: string;
+  exitCode?: number;
+  runtime?: number;
+  outputPath?: string;
+}
+
+/** Output snapshot returned by getBackgroundTaskOutput. */
+export interface BackgroundTaskOutput {
+  stdout: string;
+  stderr: string;
+  status: BackgroundTaskStatus;
+  outputPath?: string;
+  type: BackgroundTaskType;
+  exitCode?: number;
+}
+
 export interface ForegroundTask {
   id: string;
   backgroundHandler: () => Promise<void>;

package/src/types/workflow.ts

@@ -2,4 +2,5 @@ export type {
   WorkflowRun,
   WorkflowMeta,
   WorkflowPhaseState,
+  SerializableWorkflowRun,
 } from "../workflow/types.js";

package/src/utils/containerSetup.ts

@@ -256,8 +256,6 @@ export function setupAgentContainer(
 
         const decision = await options.canUseTool!(context);
 
-        const planFilePath = permissionManager.getPlanFilePath();
-
         if (decision.newPermissionMode) {
           setPermissionMode(decision.newPermissionMode);
         }
@@ -266,15 +264,6 @@ export function setupAgentContainer(
           await addPermissionRule(decision.newPermissionRule);
         }
 
-        if (decision.clearContext) {
-          messageManager.clearMessages();
-          if (planFilePath) {
-            messageManager.addUserMessage({
-              content: `Implement the plan at ${planFilePath}`,
-            });
-          }
-        }
-
         return decision;
       }
     : undefined;

package/src/utils/worktreeSession.ts

@@ -5,7 +5,7 @@
  * "WorktreeSession" container slot registered in containerSetup.ts and accessed via
  * AIManager.getWorktreeSession()/setWorktreeSession()). This keeps worktree state
  * isolated per session in stdio multi-agent mode — a process-level singleton would
- * leak state across concurrent sessions (see specs/047-worktree.md FR-042).
+ * leak state across concurrent sessions (see docs/specs/multi-agent/worktree.md FR-042).
  */
 
 export interface WorktreeSession {

package/src/utils/worktreeUtils.ts

@@ -93,8 +93,16 @@ export function getHeadCommit(cwd: string): string {
 
 /**
  * Create a git worktree for use during a session.
+ * @param name Worktree name
+ * @param cwd Current working directory (will be resolved to main repo root)
+ * @param options Optional creation options
+ * @param options.baseRef "fresh" (default, origin/<default-branch>) | "head" (local HEAD)
  */
-export function createWorktree(name: string, cwd: string): WorktreeInfo {
+export function createWorktree(
+  name: string,
+  cwd: string,
+  options?: { baseRef?: "fresh" | "head" },
+): WorktreeInfo {
   const repoRoot = getGitMainRepoRoot(cwd);
   if (!repoRoot) {
     throw new Error(
@@ -107,7 +115,8 @@ export function createWorktree(name: string, cwd: string): WorktreeInfo {
 
   const worktreePath = path.join(repoRoot, ".wave", "worktrees", name);
   const branchName = `worktree-${name}`;
-  const baseBranch = getDefaultRemoteBranch(cwd);
+  const useHead = options?.baseRef === "head";
+  const baseBranch = useHead ? "HEAD" : getDefaultRemoteBranch(cwd);
 
   // Ensure Wave runtime files are git-excluded in this repo
   ensureWaveRuntimeFilesExcluded(cwd);
@@ -183,8 +192,9 @@ export function createWorktree(name: string, cwd: string): WorktreeInfo {
       }
     }
     if (
-      stderr.includes("not a valid object name") ||
-      stderr.includes("unknown revision")
+      !useHead &&
+      (stderr.includes("not a valid object name") ||
+        stderr.includes("unknown revision"))
     ) {
       // Base branch not fetched yet — try fetching then retrying
       const branchNameOnly = baseBranch.split("/").pop()!;

package/src/workflow/types.ts

@@ -42,6 +42,12 @@ export interface WorkflowRun {
   failedAgentError?: string;
 }
 
+/**
+ * Serializable workflow run for stdio transport, with the non-serializable
+ * `completionPromise` stripped. Returned by the `getWorkflowRuns` RPC.
+ */
+export type SerializableWorkflowRun = Omit<WorkflowRun, "completionPromise">;
+
 export interface JournalEntry {
   agentIndex: number;
   prompt: string;