feat(engine): collapse the duplicated plan-DAG state machine into @loopover/engine

Completes #9537's last requirement, and fixes the build failure the first push
of PR #9565 hit.

THE BUILD FIX: `ToolContract` was imported from @loopover/contract/tools, which
only imports that type internally and never re-exports it. The local typecheck
resolves the package through a src alias and passed; the real package build
resolves the export map and failed at 'Build MCP'. Now imported from the package
root, which does export it.

THE PLAN-DAG DEDUP: buildPlanDag/validatePlanDag/the step state machine existed
in src/services/plan-dag.ts AND hand-copied, untyped, into the stdio MCP bin --
whose own comment explained why: it resolves @loopover/engine through the
published package, whose export map did not surface them. It does now.

Moving it turned up a THIRD partial copy already in the engine: plan-export.ts
holds the step/plan types, plan-step-readiness.ts holds nextReadySteps/isDone,
and plan-overall-status.ts holds the status vocabulary, each decomposed into its
own module. The moved file imports all three rather than restating them -- a
fourth PlanDag would have defeated the point -- and contributes only the
mutating half (build, validate, advance) that had no engine home.

src/services/plan-dag.ts stays as the Worker's import path, now a re-export, so
nothing else had to move.

Release ordering, which is why this looked blocked: both publish workflows are
workflow_dispatch-only, so nothing auto-publishes on merge and an operator
publishes the engine before the CLI, as usual. The engine takes a minor bump for
the new export, with packages/loopover-miner/expected-engine.version and both
consumers' dependency ranges moved to ^3.16.0 in the same commit so a published
CLI can never resolve an engine without it.

Also declares @loopover/contract#build as an edge of the root typecheck task.
That was working only because ci.yml happens to run a contract build first; the
edge makes a bare 'turbo run typecheck' correct on its own.

Author: JSONbored

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopover/engine",
-  "version": "3.15.3",
+  "version": "3.16.0",
   "license": "AGPL-3.0-only",
   "type": "module",
   "description": "Shared deterministic engine logic for the LoopOver review stack and loopover-miner.",

packages/loopover-engine/package.json

@@ -927,3 +927,17 @@ export { parsePullRequestTargetKey } from "./parse-pull-request-target-key.js";
 // loopover-mcp production local-branch collector so both enforce the same forbidden-source-upload-key /
 // oversized-content, metadata-only contract on the real collection path.
 export { assertScenarioLocalBranchInputSafe } from "./scenario-input-safety.js";
+
+// #783 multi-step plan DAG (#9537) -- the per-step state machine loopover_build_plan /
+// loopover_plan_status / loopover_record_step_result advance. Lives here because BOTH MCP servers
+// need it and the stdio one resolves this package from the registry; before #9537 it existed twice,
+// once in src/services/plan-dag.ts and once hand-copied and untyped into the stdio bin.
+export {
+  buildPlanDag,
+  validatePlanDag,
+  markStepRunning,
+  applyStepResult,
+  planProgress,
+  type PlanProgress,
+} from "./plan-dag.js";
+export { isDone as isPlanStepDone, nextReadySteps } from "./plan-step-readiness.js";

packages/loopover-engine/src/index.ts

@@ -0,0 +1,118 @@
+// #783 multi-step action DAG. A miner plan is a set of steps with dependencies ("close 1 stale PR → land 2 →
+// open a new direct PR"); loopover tracks per-step state + retries so the plan survives across MCP tool
+// calls and resumes where it left off. PURE + deterministic — the harness performs each step's real work and
+// reports the result back; this module only advances the state machine.
+
+// #9537: the step/plan TYPES and the readiness + overall-status functions already lived in this
+// package, decomposed one-per-module. This file adds only the mutating half of the state machine
+// (build, validate, advance) that had no engine home and was therefore duplicated in the Worker and
+// hand-copied into the stdio MCP bin. It imports the existing pieces rather than restating them --
+// a fourth copy of `PlanDag` would defeat the point of the move.
+import type { PlanDag, PlanStep, PlanStepStatus } from "./plan-export.js";
+import { isDone, nextReadySteps } from "./plan-step-readiness.js";
+import type { PlanOverallStatus } from "./plan-overall-status.js";
+
+export type PlanProgress = {
+  total: number;
+  completed: number;
+  failed: number;
+  running: number;
+  pending: number;
+  skipped: number;
+  status: PlanOverallStatus;
+};
+
+const DEFAULT_MAX_ATTEMPTS = 1;
+
+/** Build a normalized DAG from raw step input: default status pending / attempts 0, clamp maxAttempts to [1,10],
+ *  drop self-deps + duplicate dep ids. Pure. */
+export function buildPlanDag(steps: Array<{ id: string; title: string; actionClass?: string | undefined; dependsOn?: string[] | undefined; maxAttempts?: number | undefined }>): PlanDag {
+  return {
+    steps: steps.map((step) => ({
+      id: step.id,
+      title: step.title,
+      ...(step.actionClass !== undefined ? { actionClass: step.actionClass } : {}),
+      dependsOn: [...new Set((step.dependsOn ?? []).filter((dep) => dep !== step.id))],
+      status: "pending" as PlanStepStatus,
+      attempts: 0,
+      maxAttempts: Math.min(10, Math.max(1, Math.trunc(step.maxAttempts ?? DEFAULT_MAX_ATTEMPTS))),
+    })),
+  };
+}
+
+/** Validate the DAG: unique ids, every dependency exists, and no cycles. Pure. */
+export function validatePlanDag(plan: PlanDag): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const ids = plan.steps.map((step) => step.id);
+  const idSet = new Set(ids);
+  if (idSet.size !== ids.length) errors.push("duplicate step ids");
+  for (const step of plan.steps) {
+    for (const dep of step.dependsOn) {
+      if (!idSet.has(dep)) errors.push(`step ${step.id} depends on unknown step ${dep}`);
+    }
+  }
+  // Cycle detection via DFS coloring.
+  const color = new Map<string, 0 | 1 | 2>();
+  const byId = new Map(plan.steps.map((step) => [step.id, step]));
+  const hasCycle = (id: string): boolean => {
+    color.set(id, 1);
+    /* v8 ignore next -- hasCycle is only ever called with an id present in byId, so the [] fallback is defensive. */
+    for (const dep of byId.get(id)?.dependsOn ?? []) {
+      const depColor = color.get(dep) ?? 0;
+      if (depColor === 1) return true;
+      if (depColor === 0 && byId.has(dep) && hasCycle(dep)) return true;
+    }
+    color.set(id, 2);
+    return false;
+  };
+  for (const step of plan.steps) {
+    if ((color.get(step.id) ?? 0) === 0 && hasCycle(step.id)) {
+      errors.push("plan has a dependency cycle");
+      break;
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function mapStep(plan: PlanDag, stepId: string, update: (step: PlanStep) => PlanStep): PlanDag {
+  return { steps: plan.steps.map((step) => (step.id === stepId ? update(step) : step)) };
+}
+
+/** Mark a ready step as running (the harness has started it). No-op for an unknown/non-pending step. Pure. */
+export function markStepRunning(plan: PlanDag, stepId: string): PlanDag {
+  return mapStep(plan, stepId, (step) => (step.status === "pending" ? { ...step, status: "running" } : step));
+}
+
+/**
+ * Record the outcome of a step the harness ran. `completed` / `skipped` are terminal. `failed` increments the
+ * attempt count and retries (back to pending) until maxAttempts is exhausted, after which it stays failed. An
+ * unknown step id is a no-op. Pure.
+ */
+export function applyStepResult(plan: PlanDag, stepId: string, result: { outcome: "completed" | "failed" | "skipped"; error?: string | null | undefined }): PlanDag {
+  return mapStep(plan, stepId, (step) => {
+    if (isDone(step.status) || step.status === "failed") return step;
+    if (result.outcome === "completed") return { ...step, status: "completed", lastError: null };
+    if (result.outcome === "skipped") return { ...step, status: "skipped", lastError: null };
+    const attempts = step.attempts + 1;
+    const exhausted = attempts >= step.maxAttempts;
+    return { ...step, attempts, status: exhausted ? "failed" : "pending", lastError: result.error ?? "step failed" };
+  });
+}
+
+/** Aggregate progress + the overall plan status. Pure. */
+export function planProgress(plan: PlanDag): PlanProgress {
+  const count = (status: PlanStepStatus) => plan.steps.filter((step) => step.status === status).length;
+  const completed = count("completed");
+  const skipped = count("skipped");
+  const failed = count("failed");
+  const running = count("running");
+  const pending = count("pending");
+  const total = plan.steps.length;
+  let status: PlanOverallStatus;
+  if (total > 0 && completed + skipped === total) status = "completed";
+  else if (failed > 0) status = "failed";
+  else if (running > 0) status = "running";
+  else if (pending > 0 && nextReadySteps(plan).length === 0) status = "blocked";
+  else status = "pending";
+  return { total, completed, failed, running, pending, skipped, status };
+}

packages/loopover-engine/src/plan-dag.ts

@@ -9,6 +9,8 @@ import { fileURLToPath } from "node:url";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { buildFeasibilityVerdict, buildPrTextLint, buildGateDispositions, buildPublicPrBodyDraft } from "@loopover/engine";
+// #9537: the plan-DAG state machine, formerly hand-copied into this file, untyped.
+import { applyStepResult, buildPlanDag, nextReadySteps, planProgress, validatePlanDag, type PlanDag } from "@loopover/engine";
 // #6149: the miner write-tools are PURE local-execution spec builders (loopover never performs the write);
 // registering them locally is just importing the same engine builders the remote server uses.
 import {
@@ -143,8 +145,8 @@ import {
   WatchIssuesInput,
   getToolContract,
   ListPendingActionsStdioInput,
-  type ToolContract,
 } from "@loopover/contract/tools";
+import type { ToolContract } from "@loopover/contract";
 import { buildBranchAnalysisPayload, collectLocalDiff, collectLocalBranchMetadata, probeLocalScorer, referenceScorePreviewExample, resolveScorePreviewCommand, resolveWorkspaceCwd, sanitizeLocalScorerStatus, setupGuidanceForLocalScorer, isTestFile } from "../lib/local-branch.js";
 import { formatTable } from "../lib/format-table.js";
 import { argsWantJson, describeCliError, reportCliFailure } from "../lib/cli-error.js";
@@ -274,105 +276,15 @@ const MAINTAIN_AUTONOMY_LEVELS = ["observe", "auto_with_approval", "auto"];
 // route + MCP tool accept, while set-level keeps its own autonomy-configurable subset above.
 const PROPOSE_ACTION_CLASSES = ["review", "request_changes", "approve", "merge", "close", "label", "review_state_label"];
 
-// #6150 — plan-DAG step tracking for loopover_build_plan/loopover_plan_status/loopover_record_step_result.
-// Hand-duplicated from src/services/plan-dag.ts (packages/loopover-engine/src/services/plan-dag.ts is NOT
-// where it lives -- this module was never extracted to @loopover/engine, so there is nothing to import from
-// the published package's export map), same rationale as MAINTAIN_ACTION_CLASSES/AUTONOMY_LEVELS above: this
-// file resolves @loopover/engine through the published package, whose export map does not surface it.
-// PURE + stateless (no DB, no repo/network access) -- the harness performs each step's real work and calls
-// loopover_record_step_result to report it back; this only advances the in-memory state machine the caller
-// passes in and gets back on every call.
-const DEFAULT_PLAN_MAX_ATTEMPTS = 1;
-
-function buildPlanDag(steps: any) {
-  return {
-    steps: steps.map((step: any) => ({
-      id: step.id,
-      title: step.title,
-      ...(step.actionClass !== undefined ? { actionClass: step.actionClass } : {}),
-      dependsOn: [...new Set((step.dependsOn ?? []).filter((dep: any) => dep !== step.id))],
-      status: "pending",
-      attempts: 0,
-      maxAttempts: Math.min(10, Math.max(1, Math.trunc(step.maxAttempts ?? DEFAULT_PLAN_MAX_ATTEMPTS))),
-    })),
-  };
-}
-
-function validatePlanDag(plan: any) {
-  const errors = [];
-  const ids = plan.steps.map((step: any) => step.id);
-  const idSet = new Set(ids);
-  if (idSet.size !== ids.length) errors.push("duplicate step ids");
-  for (const step of plan.steps) {
-    for (const dep of step.dependsOn) {
-      if (!idSet.has(dep)) errors.push(`step ${step.id} depends on unknown step ${dep}`);
-    }
-  }
-  const color = new Map();
-  const byId = new Map<any, any>(plan.steps.map((step: any) => [step.id, step]));
-  const hasCycle = (id: any) => {
-    color.set(id, 1);
-    for (const dep of byId.get(id)?.dependsOn ?? []) {
-      const depColor = color.get(dep) ?? 0;
-      if (depColor === 1) return true;
-      if (depColor === 0 && byId.has(dep) && hasCycle(dep)) return true;
-    }
-    color.set(id, 2);
-    return false;
-  };
-  for (const step of plan.steps) {
-    if ((color.get(step.id) ?? 0) === 0 && hasCycle(step.id)) {
-      errors.push("plan has a dependency cycle");
-      break;
-    }
-  }
-  return { valid: errors.length === 0, errors };
-}
-
-const isPlanStepDone = (status: any) => status === "completed" || status === "skipped";
-
-function nextReadySteps(plan: any) {
-  const statusById = new Map(plan.steps.map((step: any) => [step.id, step.status]));
-  return plan.steps.filter((step: any) => step.status === "pending" && step.dependsOn.every((dep: any) => isPlanStepDone(statusById.get(dep) ?? "pending")));
-}
-
-function mapPlanStep(plan: any, stepId: any, update: any) {
-  return { steps: plan.steps.map((step: any) => (step.id === stepId ? update(step) : step)) };
-}
-
-function applyStepResult(plan: any, stepId: any, result: any) {
-  return mapPlanStep(plan, stepId, (step: any) => {
-    if (isPlanStepDone(step.status) || step.status === "failed") return step;
-    if (result.outcome === "completed") return { ...step, status: "completed", lastError: null };
-    if (result.outcome === "skipped") return { ...step, status: "skipped", lastError: null };
-    const attempts = step.attempts + 1;
-    const exhausted = attempts >= step.maxAttempts;
-    return { ...step, attempts, status: exhausted ? "failed" : "pending", lastError: result.error ?? "step failed" };
-  });
-}
+// #783 plan DAG -- one implementation, in @loopover/engine (#9537). This file carried a
+// hand-copied, untyped duplicate of buildPlanDag/validatePlanDag/nextReadySteps/the step state
+// machine because the engine's export map did not surface them; it does now, so the copy is gone.
 
-function planProgress(plan: any) {
-  const count = (status: any) => plan.steps.filter((step: any) => step.status === status).length;
-  const completed = count("completed");
-  const skipped = count("skipped");
-  const failed = count("failed");
-  const running = count("running");
-  const pending = count("pending");
-  const total = plan.steps.length;
-  let status;
-  if (total > 0 && completed + skipped === total) status = "completed";
-  else if (failed > 0) status = "failed";
-  else if (running > 0) status = "running";
-  else if (pending > 0 && nextReadySteps(plan).length === 0) status = "blocked";
-  else status = "pending";
-  return { total, completed, failed, running, pending, skipped, status };
-}
-
-function planView(plan: any) {
+function planView(plan: PlanDag) {
   return {
     plan,
     progress: planProgress(plan),
-    readySteps: nextReadySteps(plan).map((step: any) => ({ id: step.id, title: step.title })),
+    readySteps: nextReadySteps(plan).map((step) => ({ id: step.id, title: step.title })),
     validation: validatePlanDag(plan),
   };
 }

packages/loopover-mcp/bin/loopover-mcp.ts

@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@loopover/contract": "^0.1.0",
-    "@loopover/engine": "^3.15.2",
+    "@loopover/engine": "^3.16.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "posthog-node": "^5.46.1",
     "zod": "^4.4.3"

packages/loopover-mcp/package.json

@@ -1 +1 @@
-3.15.3
+3.16.0

packages/loopover-miner/expected-engine.version

@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@loopover/contract": "^0.1.0",
-    "@loopover/engine": "^3.15.2",
+    "@loopover/engine": "^3.16.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.67.0",
     "zod": "^4.4.3"