@nathapp/nax 0.18.1

package/src/execution/lifecycle/acceptance-loop.ts

@@ -0,0 +1,272 @@
+/**
+ * Acceptance Retry Loop
+ *
+ * Handles the acceptance testing retry loop after main execution completes:
+ * 1. Runs acceptance validation
+ * 2. Generates fix stories for failed acceptance criteria
+ * 3. Executes fix stories through pipeline
+ * 4. Retries until max retries or all tests pass
+ */
+
+import path from "node:path";
+import { type FixStory, convertFixStoryToUserStory, generateFixStories } from "../../acceptance";
+import { getAgent } from "../../agents";
+import type { NaxConfig } from "../../config";
+import { resolveModel } from "../../config/schema";
+import { type LoadedHooksConfig, fireHook } from "../../hooks";
+import { getSafeLogger } from "../../logger";
+import type { StoryMetrics } from "../../metrics";
+import type { PipelineEventEmitter } from "../../pipeline/events";
+import { runPipeline } from "../../pipeline/runner";
+import { defaultPipeline } from "../../pipeline/stages";
+import type { PipelineContext, RoutingResult } from "../../pipeline/types";
+import type { PluginRegistry } from "../../plugins";
+import { loadPRD, savePRD } from "../../prd";
+import type { PRD, UserStory } from "../../prd/types";
+import { routeTask } from "../../routing";
+import { hookCtx } from "../helpers";
+import type { StatusWriter } from "../status-writer";
+
+export interface AcceptanceLoopContext {
+  config: NaxConfig;
+  prd: PRD;
+  prdPath: string;
+  workdir: string;
+  featureDir?: string;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  totalCost: number;
+  iterations: number;
+  storiesCompleted: number;
+  allStoryMetrics: StoryMetrics[];
+  pluginRegistry: PluginRegistry;
+  eventEmitter?: PipelineEventEmitter;
+  statusWriter: StatusWriter;
+}
+
+export interface AcceptanceLoopResult {
+  success: boolean;
+  prd: PRD;
+  totalCost: number;
+  iterations: number;
+  storiesCompleted: number;
+  prdDirty: boolean;
+}
+
+/** Load spec.md content for AC text */
+async function loadSpecContent(featureDir?: string): Promise<string> {
+  if (!featureDir) return "";
+  const specPath = path.join(featureDir, "spec.md");
+  const specFile = Bun.file(specPath);
+  return (await specFile.exists()) ? await specFile.text() : "";
+}
+
+/** Build result object for loop exit */
+function buildResult(
+  success: boolean,
+  prd: PRD,
+  totalCost: number,
+  iterations: number,
+  storiesCompleted: number,
+  prdDirty: boolean,
+): AcceptanceLoopResult {
+  return { success, prd, totalCost, iterations, storiesCompleted, prdDirty };
+}
+
+/** Generate and add fix stories to PRD */
+async function generateAndAddFixStories(
+  ctx: AcceptanceLoopContext,
+  failures: { failedACs: string[]; testOutput: string },
+  prd: PRD,
+): Promise<FixStory[] | null> {
+  const logger = getSafeLogger();
+  const agent = getAgent(ctx.config.autoMode.defaultAgent);
+  if (!agent) {
+    logger?.error("acceptance", "Agent not found, cannot generate fix stories");
+    return null;
+  }
+  const modelDef = resolveModel(ctx.config.models[ctx.config.analyze.model]);
+  const fixStories = await generateFixStories(agent, {
+    failedACs: failures.failedACs,
+    testOutput: failures.testOutput,
+    prd,
+    specContent: await loadSpecContent(ctx.featureDir),
+    workdir: ctx.workdir,
+    modelDef,
+  });
+  if (fixStories.length === 0) {
+    logger?.error("acceptance", "Failed to generate fix stories");
+    return null;
+  }
+  logger?.info("acceptance", `Generated ${fixStories.length} fix stories`);
+  for (const fixStory of fixStories) {
+    const userStory = convertFixStoryToUserStory(fixStory);
+    prd.userStories.push(userStory);
+    logger?.debug("acceptance", `Fix story added: ${userStory.id}: ${userStory.title}`);
+  }
+  return fixStories;
+}
+
+/** Execute a single fix story through the pipeline */
+async function executeFixStory(
+  ctx: AcceptanceLoopContext,
+  story: UserStory,
+  prd: PRD,
+  iterations: number,
+): Promise<{ success: boolean; cost: number; metrics?: StoryMetrics[] }> {
+  const logger = getSafeLogger();
+  const routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, ctx.config);
+  logger?.info("acceptance", `Starting fix story: ${story.id}`, { storyId: story.id, storyTitle: story.title });
+  await fireHook(
+    ctx.hooks,
+    "on-story-start",
+    hookCtx(ctx.feature, {
+      storyId: story.id,
+      model: routing.modelTier,
+      agent: ctx.config.autoMode.defaultAgent,
+      iteration: iterations,
+    }),
+    ctx.workdir,
+  );
+  const fixContext: PipelineContext = {
+    config: ctx.config,
+    prd,
+    story,
+    stories: [story],
+    routing: routing as RoutingResult,
+    workdir: ctx.workdir,
+    featureDir: ctx.featureDir,
+    hooks: ctx.hooks,
+    plugins: ctx.pluginRegistry,
+    storyStartTime: new Date().toISOString(),
+  };
+  const result = await runPipeline(defaultPipeline, fixContext, ctx.eventEmitter);
+  logger?.info("acceptance", `Fix story ${story.id} ${result.success ? "passed" : "failed"}`);
+  return {
+    success: result.success,
+    cost: result.context.agentResult?.estimatedCost || 0,
+    metrics: result.context.storyMetrics,
+  };
+}
+
+/**
+ * Run the acceptance retry loop
+ *
+ * Executes acceptance tests and handles retry logic with fix story generation.
+ */
+export async function runAcceptanceLoop(ctx: AcceptanceLoopContext): Promise<AcceptanceLoopResult> {
+  const logger = getSafeLogger();
+  const maxRetries = ctx.config.acceptance.maxRetries;
+
+  let acceptanceRetries = 0;
+  let prd = ctx.prd;
+  let totalCost = ctx.totalCost;
+  let iterations = ctx.iterations;
+  let storiesCompleted = ctx.storiesCompleted;
+  let prdDirty = false;
+
+  logger?.info("acceptance", "All stories complete, running acceptance validation");
+
+  while (acceptanceRetries < maxRetries) {
+    // Run acceptance validation
+    const firstStory = prd.userStories[0];
+    const acceptanceContext: PipelineContext = {
+      config: ctx.config,
+      prd,
+      story: firstStory,
+      stories: [firstStory],
+      routing: {
+        complexity: "simple",
+        modelTier: "balanced",
+        testStrategy: "test-after",
+        reasoning: "Acceptance validation",
+      },
+      workdir: ctx.workdir,
+      featureDir: ctx.featureDir,
+      hooks: ctx.hooks,
+      plugins: ctx.pluginRegistry,
+    };
+
+    const { acceptanceStage } = await import("../../pipeline/stages/acceptance");
+    const acceptanceResult = await acceptanceStage.execute(acceptanceContext);
+
+    if (acceptanceResult.action === "continue") {
+      logger?.info("acceptance", "Acceptance validation passed!");
+      return buildResult(true, prd, totalCost, iterations, storiesCompleted, prdDirty);
+    }
+
+    if (acceptanceResult.action !== "fail") {
+      logger?.warn("acceptance", `Unexpected acceptance result: ${acceptanceResult.action}`);
+      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
+    }
+
+    // Handle acceptance test failures
+    const failures = acceptanceContext.acceptanceFailures;
+    if (!failures || failures.failedACs.length === 0) {
+      logger?.error("acceptance", "Acceptance tests failed but no specific failures detected");
+      logger?.warn("acceptance", "Manual intervention required");
+      await fireHook(
+        ctx.hooks,
+        "on-pause",
+        hookCtx(ctx.feature, { reason: "Acceptance tests failed (no failures detected)", cost: totalCost }),
+        ctx.workdir,
+      );
+      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
+    }
+
+    acceptanceRetries++;
+    logger?.warn("acceptance", `Acceptance retry ${acceptanceRetries}/${maxRetries}`, {
+      failedACs: failures.failedACs,
+    });
+
+    if (acceptanceRetries >= maxRetries) {
+      logger?.error("acceptance", "Max acceptance retries reached");
+      logger?.warn("acceptance", "Manual intervention required");
+      logger?.debug("acceptance", 'Run: nax accept --override AC-N "reason" to skip specific ACs');
+      await fireHook(
+        ctx.hooks,
+        "on-pause",
+        hookCtx(ctx.feature, {
+          reason: `Acceptance validation failed after ${maxRetries} retries: ${failures.failedACs.join(", ")}`,
+          cost: totalCost,
+        }),
+        ctx.workdir,
+      );
+      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
+    }
+
+    // Generate and add fix stories
+    logger?.info("acceptance", "Generating fix stories...");
+    const fixStories = await generateAndAddFixStories(ctx, failures, prd);
+    if (!fixStories) {
+      return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
+    }
+
+    await savePRD(prd, ctx.prdPath);
+    prdDirty = true;
+
+    // Execute fix stories
+    logger?.info("acceptance", "Running fix stories...");
+    for (const fixStory of fixStories) {
+      const userStory = prd.userStories.find((s) => s.id === fixStory.id);
+      if (!userStory || userStory.status !== "pending") continue;
+
+      iterations++;
+      const result = await executeFixStory(ctx, userStory, prd, iterations);
+      prd = await loadPRD(ctx.prdPath); // Reload to get updated PRD
+
+      if (result.success) {
+        storiesCompleted++;
+        totalCost += result.cost;
+        if (result.metrics) ctx.allStoryMetrics.push(...result.metrics);
+      }
+
+      await savePRD(prd, ctx.prdPath);
+      prdDirty = true;
+    }
+
+    logger?.info("acceptance", "Re-running acceptance tests...");
+  }
+
+  return buildResult(false, prd, totalCost, iterations, storiesCompleted, prdDirty);
+}

package/src/execution/lifecycle/headless-formatter.ts

@@ -0,0 +1,85 @@
+/**
+ * Headless Output Formatting
+ *
+ * Handles console output formatting for headless (non-TUI) mode.
+ * Extracts run header and footer formatting logic from runner.ts.
+ */
+
+import path from "node:path";
+import chalk from "chalk";
+import type { RunSummary } from "../../logging";
+import { formatRunSummary } from "../../logging";
+
+export interface RunHeaderOptions {
+  feature: string;
+  totalStories: number;
+  pendingStories: number;
+  workdir: string;
+  formatterMode: "quiet" | "normal" | "verbose" | "json";
+}
+
+export interface RunFooterOptions {
+  finalCounts: {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+  };
+  durationMs: number;
+  totalCost: number;
+  startedAt: string;
+  completedAt: string;
+  formatterMode: "quiet" | "normal" | "verbose" | "json";
+}
+
+/**
+ * Output run header in headless mode
+ */
+export async function outputRunHeader(options: RunHeaderOptions): Promise<void> {
+  const { feature, totalStories, pendingStories, workdir, formatterMode } = options;
+
+  if (formatterMode === "json") {
+    return;
+  }
+
+  const pkg = await Bun.file(path.join(import.meta.dir, "..", "..", "..", "package.json")).json();
+
+  console.log("");
+  console.log(chalk.bold(chalk.blue("═".repeat(60))));
+  console.log(chalk.bold(chalk.blue(`  ▶ NAX v${pkg.version} — RUN STARTED`)));
+  console.log(chalk.blue("═".repeat(60)));
+  console.log(`  ${chalk.gray("Feature:")}  ${chalk.cyan(feature)}`);
+  console.log(`  ${chalk.gray("Stories:")}  ${chalk.cyan(`${totalStories} total, ${pendingStories} pending`)}`);
+  console.log(`  ${chalk.gray("Path:")}     ${chalk.dim(workdir)}`);
+  console.log(chalk.blue("═".repeat(60)));
+  console.log("");
+}
+
+/**
+ * Output run footer in headless mode
+ */
+export function outputRunFooter(options: RunFooterOptions): void {
+  const { finalCounts, durationMs, totalCost, startedAt, completedAt, formatterMode } = options;
+
+  if (formatterMode === "json") {
+    return;
+  }
+
+  const runSummary: RunSummary = {
+    total: finalCounts.total,
+    passed: finalCounts.passed,
+    failed: finalCounts.failed,
+    skipped: finalCounts.skipped,
+    durationMs,
+    totalCost,
+    startedAt,
+    completedAt,
+  };
+
+  const summaryOutput = formatRunSummary(runSummary, {
+    mode: formatterMode,
+    useColor: true,
+  });
+
+  console.log(summaryOutput);
+}

package/src/execution/lifecycle/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Lifecycle module exports
+ */
+
+export { RunLifecycle, type SetupResult, type TeardownOptions } from "./run-lifecycle";
+export { runAcceptanceLoop, type AcceptanceLoopContext, type AcceptanceLoopResult } from "./acceptance-loop";
+export { emitStoryComplete, type StoryCompleteEvent } from "./story-hooks";
+export { outputRunHeader, outputRunFooter, type RunHeaderOptions, type RunFooterOptions } from "./headless-formatter";
+export { handleParallelCompletion, type ParallelCompletionOptions } from "./parallel-lifecycle";
+export { handleRunCompletion, type RunCompletionOptions, type RunCompletionResult } from "./run-completion";
+export { cleanupRun, type RunCleanupOptions } from "./run-cleanup";
+export { setupRun, type RunSetupOptions, type RunSetupResult } from "./run-setup";

package/src/execution/lifecycle/parallel-lifecycle.ts

@@ -0,0 +1,101 @@
+/**
+ * Parallel Execution Lifecycle
+ *
+ * Handles metrics saving and reporter notifications for parallel execution completion.
+ * Extracted from runner.ts to reduce its size.
+ */
+
+import { getSafeLogger } from "../../logger";
+import type { StoryMetrics } from "../../metrics";
+import { saveRunMetrics } from "../../metrics";
+import type { PluginRegistry } from "../../plugins/registry";
+import { countStories } from "../../prd";
+import type { PRD } from "../../prd";
+
+export interface ParallelCompletionOptions {
+  runId: string;
+  feature: string;
+  startedAt: string;
+  completedAt: string;
+  prd: PRD;
+  allStoryMetrics: StoryMetrics[];
+  totalCost: number;
+  storiesCompleted: number;
+  durationMs: number;
+  workdir: string;
+  pluginRegistry: PluginRegistry;
+}
+
+/**
+ * Handle parallel execution completion:
+ * - Save run metrics
+ * - Emit reporter events
+ */
+export async function handleParallelCompletion(options: ParallelCompletionOptions): Promise<void> {
+  const logger = getSafeLogger();
+  const {
+    runId,
+    feature,
+    startedAt,
+    completedAt,
+    prd,
+    allStoryMetrics,
+    totalCost,
+    storiesCompleted,
+    durationMs,
+    workdir,
+    pluginRegistry,
+  } = options;
+
+  // Save run metrics
+  const runMetrics = {
+    runId,
+    feature,
+    startedAt,
+    completedAt,
+    totalCost,
+    totalStories: allStoryMetrics.length,
+    storiesCompleted,
+    storiesFailed: countStories(prd).failed,
+    totalDurationMs: durationMs,
+    stories: allStoryMetrics,
+  };
+
+  await saveRunMetrics(workdir, runMetrics);
+
+  // Log run completion
+  const finalCounts = countStories(prd);
+  logger?.info("run.complete", "Feature execution completed", {
+    runId,
+    feature,
+    success: true,
+    totalStories: finalCounts.total,
+    storiesCompleted,
+    storiesFailed: finalCounts.failed,
+    storiesPending: finalCounts.pending,
+    totalCost,
+    durationMs,
+  });
+
+  // Emit onRunEnd to reporters
+  const reporters = pluginRegistry.getReporters();
+  for (const reporter of reporters) {
+    if (reporter.onRunEnd) {
+      try {
+        await reporter.onRunEnd({
+          runId,
+          totalDurationMs: durationMs,
+          totalCost,
+          storySummary: {
+            completed: storiesCompleted,
+            failed: finalCounts.failed,
+            skipped: finalCounts.skipped,
+            paused: finalCounts.paused,
+          },
+        });
+      } catch (error) {
+        logger?.warn("plugins", `Reporter '${reporter.name}' onRunEnd failed`, { error });
+      }
+    }
+  }
+}

package/src/execution/lifecycle/precheck-runner.ts

@@ -0,0 +1,140 @@
+/**
+ * Precheck Runner
+ *
+ * Handles precheck validation execution before the main run starts.
+ * Validates project state, dependencies, and configuration.
+ * Blocks execution on Tier 1 failures, warns on Tier 2 failures.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import type { NaxConfig } from "../../config";
+import type { InteractionChain } from "../../interaction/chain";
+import { getSafeLogger } from "../../logger";
+import type { PRD } from "../../prd/types";
+import type { StatusWriter } from "../status-writer";
+
+export interface PrecheckContext {
+  config: NaxConfig;
+  prd: PRD;
+  workdir: string;
+  logFilePath?: string;
+  statusWriter: StatusWriter;
+  headless: boolean;
+  formatterMode: "quiet" | "normal" | "verbose" | "json";
+  interactionChain?: InteractionChain | null;
+  featureName?: string;
+}
+
+/**
+ * Run precheck validations before execution starts
+ *
+ * @throws Error if precheck blockers are found (Tier 1 failures)
+ */
+export async function runPrecheckValidation(ctx: PrecheckContext): Promise<void> {
+  const logger = getSafeLogger();
+
+  // Allow tests to skip precheck entirely (git-repo-exists, working-tree-clean, etc. fail in temp dirs)
+  if (process.env.NAX_SKIP_PRECHECK === "1") {
+    logger?.info("precheck", "Skipping precheck validations (NAX_SKIP_PRECHECK=1)");
+    return;
+  }
+
+  logger?.info("precheck", "Running precheck validations...");
+
+  const { runPrecheck } = await import("../../precheck");
+  const precheckResult = await runPrecheck(ctx.config, ctx.prd, {
+    workdir: ctx.workdir,
+    format: "human",
+  });
+
+  // Log precheck results to JSONL
+  if (ctx.logFilePath) {
+    // Ensure directory exists
+    mkdirSync(path.dirname(ctx.logFilePath), { recursive: true });
+
+    const precheckLog = {
+      type: "precheck",
+      timestamp: new Date().toISOString(),
+      passed: precheckResult.output.passed,
+      blockers: precheckResult.output.blockers.map((b) => ({ name: b.name, message: b.message })),
+      warnings: precheckResult.output.warnings.map((w) => ({ name: w.name, message: w.message })),
+      summary: precheckResult.output.summary,
+    };
+    appendFileSync(ctx.logFilePath, `${JSON.stringify(precheckLog)}\n`, "utf8");
+  }
+
+  // Handle blockers (Tier 1 failures)
+  if (!precheckResult.output.passed) {
+    logger?.error("precheck", "Precheck failed - execution blocked", {
+      blockers: precheckResult.output.blockers.length,
+      failedChecks: precheckResult.output.blockers.map((b) => b.name),
+    });
+
+    // Update status file with precheck-failed status
+    ctx.statusWriter.setRunStatus("precheck-failed");
+    ctx.statusWriter.setCurrentStory(null);
+    await ctx.statusWriter.update(0, 0);
+
+    // Log detailed error message to console
+    console.error("");
+    console.error(chalk.red("❌ PRECHECK FAILED"));
+    console.error(chalk.red("─".repeat(60)));
+    for (const blocker of precheckResult.output.blockers) {
+      console.error(chalk.red(`✗ ${blocker.name}: ${blocker.message}`));
+    }
+    console.error(chalk.red("─".repeat(60)));
+    console.error(chalk.yellow("\nRun 'nax precheck' for detailed information"));
+    console.error(chalk.dim("Use --skip-precheck to bypass (not recommended)\n"));
+
+    throw new Error(`Precheck failed: ${precheckResult.output.blockers.map((b) => b.name).join(", ")}`);
+  }
+
+  // Handle warnings (Tier 2 failures) - log but continue
+  if (precheckResult.output.warnings.length > 0) {
+    logger?.warn("precheck", "Precheck passed with warnings", {
+      warnings: precheckResult.output.warnings.length,
+      issues: precheckResult.output.warnings.map((w) => w.name),
+    });
+
+    if (ctx.headless && ctx.formatterMode !== "json") {
+      console.log(chalk.yellow("\n⚠️  Precheck warnings:"));
+      for (const warning of precheckResult.output.warnings) {
+        console.log(chalk.yellow(`  ⚠ ${warning.name}: ${warning.message}`));
+      }
+      console.log("");
+    }
+  } else {
+    logger?.info("precheck", "All precheck validations passed");
+  }
+
+  // Story size gate interaction (v0.16.0) - prompt for flagged stories if interaction chain exists
+  if (precheckResult.flaggedStories && precheckResult.flaggedStories.length > 0) {
+    if (ctx.interactionChain && ctx.featureName) {
+      logger?.info("precheck", "Story size gate: prompting user for flagged stories", {
+        count: precheckResult.flaggedStories.length,
+      });
+
+      const { promptForFlaggedStories } = await import("./story-size-prompts");
+      const summary = await promptForFlaggedStories(
+        precheckResult.flaggedStories,
+        ctx.prd,
+        ctx.interactionChain,
+        ctx.featureName,
+      );
+
+      logger?.info("precheck", "Story size gate prompts complete", {
+        approved: summary.approved.length,
+        skipped: summary.skipped.length,
+        aborted: summary.aborted,
+      });
+
+      // PRD has been mutated with skipped stories - no need to return anything
+    } else {
+      logger?.warn("precheck", "Story size gate: interaction chain not available, skipping prompts", {
+        flaggedCount: precheckResult.flaggedStories.length,
+      });
+    }
+  }
+}

package/src/execution/lifecycle/run-cleanup.ts

@@ -0,0 +1,81 @@
+/**
+ * Run Cleanup — Finally Block Cleanup Logic
+ *
+ * Handles cleanup operations that run in the finally block:
+ * - Stop heartbeat
+ * - Cleanup crash handlers
+ * - Fire onRunEnd for reporters
+ * - Teardown plugins
+ * - Release lock
+ */
+
+import type { InteractionChain } from "../../interaction";
+import { getSafeLogger } from "../../logger";
+import type { PluginRegistry } from "../../plugins/registry";
+import { countStories } from "../../prd";
+import type { PRD } from "../../prd";
+import { releaseLock } from "../helpers";
+
+export interface RunCleanupOptions {
+  runId: string;
+  startTime: number;
+  totalCost: number;
+  storiesCompleted: number;
+  prd: PRD;
+  pluginRegistry: PluginRegistry;
+  workdir: string;
+  interactionChain: InteractionChain | null;
+}
+
+/**
+ * Execute cleanup operations in finally block
+ */
+export async function cleanupRun(options: RunCleanupOptions): Promise<void> {
+  const logger = getSafeLogger();
+  const { runId, startTime, totalCost, storiesCompleted, prd, pluginRegistry, workdir, interactionChain } = options;
+
+  // Fire onRunEnd for reporters (even on failure/abort)
+  const durationMs = Date.now() - startTime;
+  const finalCounts = countStories(prd);
+  const reporters = pluginRegistry.getReporters();
+
+  for (const reporter of reporters) {
+    if (reporter.onRunEnd) {
+      try {
+        await reporter.onRunEnd({
+          runId,
+          totalDurationMs: durationMs,
+          totalCost,
+          storySummary: {
+            completed: storiesCompleted,
+            failed: finalCounts.failed,
+            skipped: finalCounts.skipped,
+            paused: finalCounts.paused,
+          },
+        });
+      } catch (error) {
+        logger?.warn("plugins", `Reporter '${reporter.name}' onRunEnd failed`, { error });
+      }
+    }
+  }
+
+  // Teardown plugins
+  try {
+    await pluginRegistry.teardownAll();
+  } catch (error) {
+    logger?.warn("plugins", "Plugin teardown failed", { error });
+  }
+
+  // Destroy interaction chain (US-008)
+  if (interactionChain) {
+    try {
+      await interactionChain.destroy();
+      logger?.debug("interaction", "Interaction chain destroyed");
+    } catch (error) {
+      logger?.warn("interaction", "Interaction chain cleanup failed", { error });
+    }
+  }
+
+  // Always release lock, even if execution fails
+  await releaseLock(workdir);
+}